updateAssociations

Adaptive Planning

updateAssociations

Category	Metadata modification
Description	Update the ownership / association for entities (e.g. Level). Multiple associations with multiple values can be updated in one call. If successful, the API returns a success message. If the API fails, a comprehensive list of errors and their causes are returned.
Permissions Required To Invoke	Model Management : Model Model Management : Organization Structure : All Levels Admin Access : Users
Parameters Required On Request	Credentials

See Concept: Associations and Import Associations.

These conditions apply to updateAssociations:

Each association has a type, an optional operation, and a set of dim value ids (entity ids).

To create a new association, specify the entity id (e.g. level id) to which we want to give ownership and the list of user identifiers (id, WID or username).

For an association, if the same entity id is mentioned multiple times, the last one is used.

User(s) specified in the request but not present in the system will be ignored. The remaining valid users in the request will be processed and have their association details updated.

For custom dimension associations, code, name, and dimId are required fields.

The request can contain zero or only one association for level ownership. Any other level associations require the additional fields of code, name, and dimId.

Request Format


<?xml version='1.0' encoding='UTF-8'?>
<call method="updateAssociations" callerName="me">
<credentials login="sampleuser@greenco.com" password="my_pwd"/>
<associations>
  <association type="level" operation = "update">
   <dimValueIds>
     <dimValueId id = "2">
         <users>
             <id> 1, 2, 3 , 87654</id>
         </users>        
     </dimValueId>
     <dimValueId id = "24">
         <users>
             <WID>23,12</WID>
             <username>stevec@grEENco.com</username>
         </users>
     </dimValueId>
     <dimValueId id = "6">
         <users>
             <id> 1, 2, 3 </id>
             <username>johno@greenco.com, johnstevec@greenco.com</username>
             <WID> ABC, CSD </WID>
         </users>
     </dimValueId>
     <dimValueId id = "12">          
     </dimValueId>      
   </dimValueIds>
 </association>
 <association type="customdimension" code= "CD1" name="CustomDim1" operation="replaceAll" dimId="8">
   <dimValueIds>
     <dimValueId id = "86">
         <users>
             <id> 14, 45</id>
         </users>        
     </dimValueId>
     <dimValueId id = "92">
         <users>
             <id>20, 21</id>
             <WID>ABCD</WID>
             <username>stevec@grEENco.com</username>
         </users>
     </dimValueId>
   </dimValueIds>
 </association>
 <association type="customdimension" code= "CD2" name="CustomDim2" operation="update" dimId="4">
   <dimValueIds>
     <dimValueId id = "16">
         <users>
             <id> 20, 21</id>
         </users>        
     </dimValueId>
   </dimValueIds>
 </association>
 <association type="level" code= "TL2" name="TestLevels2" operation="update" dimId="-1">
   <dimValueIds>
     <dimValueId id = "1">
         <users>
             <id> 15</id>
         </users>        
     </dimValueId>
   </dimValueIds>
 </association>
</associations>
</call>

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 will show that this user performed the action), and therefore the user must have the required permissions to perform the action in order for the API call to succeed.
Attributes of the Element
Attribute Name	Required?	Value	Example
login	Y	The login 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 be used to interpret incoming numbers and dates, and to format outgoing numbers and dates (using the proper thousands separator, month names, and date formatting). The locale is also used to specify the language in which any system messages in the response should appear. 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 one instance of Adaptive Planning, this attribute can be used to specify that the user is intending to access an instance other than their default instance. If not specified, the user's default instance will be used. To determine the available instance codes, use the exportInstances API.	MYINSTANCE1
Contents of the Element
(none)

associations element
Tag Name		associations
Description		Only 1 associations element request is allowed per payload. It contains one or more association elements.
Attributes of the Element
Attribute Name	Required?	Value	Example

Contents of the Element
Contains one or more association elements.

association element
Tag Name		association
Description		Specifies the association to be created/updated for the list of entities.
Attributes of the Element
Attribute Name	Required?	Value	Example
type	y	The type of the entity for which the association is to be created / updated. It can take only these values: level customdimension	level
operation	N	The operation mode for this association. It can take only these values - (update or replaceAll) If operation="replaceAll", all existing ownership entries for that association type will be deleted and only the ownership details mentioned in the request will be saved. If operation="update", only the entity ids (eg. level ids) mentioned in the request will be updated. If operation is not mentioned it will default to "update" behavior.	update
code	Conditionally	The code of the the association being be created / updated. The only case when it is not required is in the case of level ownership. Required for all other cases.	TL1
name	Conditionally	The name of the the association being be created / updated. The only case when it is not required is in the case of level ownership. Required for all other cases.	TestLevels1
dimId	Conditionally	The id for whose dimValueIds will have the ownership details updated. Required in case of custom dimension.	12
Contents of the Element
Contains one dimValueIds element.

dimValueIds element
Tag Name		dimValueIds
Description		Specifies the list of dimValueId.
Attributes of the Element
Attribute Name	Required?	Value	Example

Contents of the Element
Contains one or more dimValueId elements.

dimValueId element
Tag Name		dimValueId
Description		Specifies
Attributes of the Element
Attribute Name	Required?	Value	Example
id	Y	The internal system ID number for the entity.	23
Contents of the Element
Contains at most one users element. If the users element is not mentioned, all of the existing ownership for the dmiValueId will be removed.

users element
Tag Name		users
Description		Specifies the user identifiers in the id, WID, or username elements.
Attributes of the Element
Attribute Name	Required?	Value	Example

Contents of the Element
Contains the list of user identifiers which are comma separated. Users not present in the system will be ignored / skipped. If none of the user identifiers are mentioned, all of the existing ownership for the entity (dimValueId) will be removed. If the same identifier tag is provided multiple times in a particular users tag, the call will return an error condition. <id> 1, 2, 3 </id> : This specifies that the ownership is to be given for users with ids 1, 2 and 3. <username>johno@greenco.com</username> : This specifies that the ownership is to be given for user with username johno@greenco.com . <WID> ABC, CSD </WID> : This specifies that the ownership is to be given for users with Workday ID ABC and CSD.

Response Format


<?xml version="1.0" encoding="UTF-8"?>
<response success="true">
 <messages>
     <message type="INFO">Associations were saved successfully.</message>
 </messages>
</response>

Response element
Tag Name		response
Description		Specifies
Attributes of the Element
Attribute Name	Required?	Value	Example
success	Y	Either "true" or "false", indicating whether the API call was successful or not.	true
Contents of the Element
A single optional messages element.

Messages element
Tag Name		messages
Description		Container for one or more message elements
Attributes of the Element
Attribute Name	Required?	Value	Example

Contents of the Element
Contains one or more message elements.

Message element
Tag Name		message
Description		Represents a message being sent from the system back to the caller. Messages are used for error messages with requests do not succeed, and for confirmation messages on success.
Attributes of the Element
Attribute Name	Required?	Value	Example
type	N	Specifies the type for the message.	INFO ERROR WARNING
Contents of the Element

Error Message Descriptions

Type	Message	Example/Description
Error	error: element "Y" incomplete; missing required element "Y"	The request is missing the required element - e.g. association, dimValueId
Error	value of attribute "type" is invalid; must be equal to "level"	Association has an incorrect type attached to it.
Error	DimValueId can have at most one users element.	The dimValueId can have at most one users element.
Warning	User Id -5 not present in system. WID -98A not present in system. Username Id stevec@comp not present in system.	The user identifier values are incorrect. They have been skipped and remaining valid users have been processed.
Error	DimValue Id -123 not present in system.	The dim value id is incorrect.