importGroups

Category	Metadata modification
Description	Import user groups that you created in core Workday or an external system. If successful, the API returns the details for the groups that you imported. You can't use this API to update user groups created in the Adaptive Planning user interface.
Permissions Required To Invoke	Manage Global User Groups permission
Parameters Required On Request	Credentials

This method's request contains a credentials tag to identify and authorize the calling user. User must have the

Admin Access

Manage Global User Groups

permission to import the user groups.

Request Format

<?xml version='1.0' encoding='UTF-8'?>
<call method="importGroups" callerName="a string that identifies your client application"
dataSource="WORKDAY/EXTERNAL" mode="REPLACE_ALL/UPDATE" userIdentifier="userName/userGUID/wid">
  <credentials login="sampleuser@company.com" password="my_pwd" />
    <groups>
        <group
          externalID="userGroup_ID_1"
          name="new user group"
           >
          <users>
              <user userGUID="B9ADBCB81AA2F9BAE040307F02092C2E"
                  userName="user1"
                  wid="A9ADBCB81AA2F9BAE040307F02092C2E" />
              <user userGUID="B9ADBCB81AA2F9BAE040307F02092C2F"
                   userName="user3"
                   wid="A9ADBCB81AA2F9BAE040307F02092C2F" />
          </users>
        </group>
     </groups>
</call>

Query Attributes

Name	Description	Required
dataSource	The source for the user groups data: WORKDAY. The source of the user groups data is Workday. These groups can't be edited within Adaptive Planning. EXTERNAL. The source of the user groups data is any other system outside Workday. From the General Setup page, your administrator can enable the editing of groups with an EXTERNAL data source. You can then update these groups using the Adaptive Planning user interface. See Reference: General Setup.	Y
mode	The mode for the API call: REPLACE_ALL. The mode replaces all user groups in your Adaptive Planning instance with the user groups that you specify in the payload. UPDATE. The mode only updates the user groups that you specify in the payload.	Y
userIdentifier	The identifier for the users specified in the user groups: userName. The user name for the specified user. userGUID. The global user ID for the specified user. wid. The Workday ID for the specified user.	Y

credentials element
Tag Name		credentials
Description		All API calls must contain a single credentials element to identify the user invoking the API. The API call is then performed as this user. Any audit trail or history of actions in the system shows that this user performed the action. Therefore, the user must have the required permissions to perform the action for the API call to succeed.
Attributes of the Element
Attribute Name	Required?	Value	Example
login	Y	The sign-in name of the user invoking the API method. This user must have the required permissions to invoke the method.	sampleuser@company.com
password	Y	The password of the user invoking the API method.	my_password
locale	N	Specify the locale to use to interpret incoming numbers and dates. Also, to format outgoing numbers and dates (using the proper thousands separator, time period names, and date formatting). The locale also specifies the language in which any system messages in the response should display. If not specified, en_US (American English) is used.	fr_FR
instanceCode	N	If the user specified in the credentials has access to more than 1 instance of Adaptive Planning, this attribute can specify that the user intends to access an instance other than their default instance. If not specified, the default instance of the user is used. To determine the available instance codes, use the exportInstances API.	MYINSTANCE1
Contents of the Element
None

group element
Tag Name		group
Description		Specifies a set of user groups to create or update.
Attributes of the Element
Attribute Name	Required?	Value	Example
externalID	Y	The external identifier of the user group.	user_group_1
name	Y	The name of the user group.	Security Admins
Contents of the Element
Users element

user element
Tag Name		user
Description		Specifies a user or users to add to the user group.
Attributes of the Element
Attribute Name	Required?	Value	Example
userGUID	Y (provided the user identifier specified by the API caller is userGUID)	The global identifier of the user.	B9ADBCB81AA2F9BAE040307F02092C2
userName	Y (provided the user identifier specified by the API caller is userName)	The user name of the user.	updateMail@company.com
wid	Y (provided the user identifier specified by the API caller is wid)	The Workday ID of the user.	A9ADBCB81AA2F9BAE040307F02092C2E
Contents of the Element
In case of invalid user (i.e. invalid userGUID/userName/wid), specific invalid user will be skipped and request will be processed for the group for rest of the valid users. However, for the following <user> element related scenarios the whole group will be rejected in the payload. Missing user identifier: <user/> <user userName=""/> <user userName/userGUID/wid=" "/> Error Message; User identifier is missing. Specify a valid userName/userGUID/wid for all users. WID not valid format: Length of WID less than or greater than 32 characters. Error Message: Specify a valid userWID for all users. userGUID not valid format: Length of userGUID less or greater than 32 characters. userGUID is not alphanumeric. Error Message: Specify a valid userGUID for all users.

Response Format

<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
  <output>
      <result>
          <imported_groups>
              <group success="true" externalID="ID_1" id="33" name="New Group 1" />
          </imported_groups>
      </result>
  </output>
</response>

response element
Tag Name		response
Attributes of the Element
Attribute Name	Required?	Value	Example
success	Y	Either true or false, indicating whether the API call was successful or not. Even successful calls can contain warning messages in their response.	true
Contents of the Element
Depending on whether you made the create or update call, a single result element with created_usergroup or updated_usergroup status elements.

imported_groups element
Tag Name		imported_groups
Attribute Name	Required?	Value	Example
group success	Y	The status returned, true or false.	"true"
message	Y	The status message.	"user group new user group was created successfully." "Payload partially successful in clearing user memberships. Try again and if issue persists, contact support."
Contents of the Element
None.