Skip to main content

logoCorrectSize.png

Adaptive Insights LLC.

Metadata Bulk Update

Supported in API v17 +

The key benefit of metadata bulk update APIs is that they allow synchronizing levels, dimensions, and GL accounts within Adaptive Insights with counterparts in an external system on a regular, scheduled basis. Instead of calling out individual elements one by one, these APIs let you submit a raw XML file or compressed (zipped) XML to update, reorder, and create elements.

With metadata bulk APIs, the new version of the tree of existing elements imports into Adaptive Insights.

Metadata bulk update APIs:

  • Never delete. Elements missing from the uploaded version remain untouched.
  • Create any new elements found in the upload, if they can.
  • Update the properties of any elements being uploaded, including their parentage properties.
  • Update the attribute assignments being uploaded.
  • They specifically allow partial tree upload (since deletion is never performed, partial uploads are non-destructive).
  • They allow identifying the existing elements in a tree either by their internal ID number or their "original" (pre-update) unique identifier field.
  • Halt on catastrophic errors and roll back. Catastrophic errors include:
    • Attempts to create a cycle in a hierarchy
    • Attempts to create a new element whose identifying field collides with one already in the system (e.g. creating a new account with a code that is in use)
    • Attempts to update an element's identifying field such that it collides with one already in the system.
  • Proceed on ignorable errors that do not halt the import, and report in the result response as warnings. Ignorable errors include those unlikely to produce any cascading effect, such as:
    • Attempts to change an attribute assignment to a value that does not exist.
    • Attempts to set a level name to something that is too long for the field.

Bulk upload using compressed XML (zipped) 

For large payloads, you can upload compressed content as a ZIP file containing only the xml of the updates without any subdirectories, folders or other content. If folders or subdirectories get detected in the ZIP at post, the request is rejected.

Attach a Compressed XML (zipped) File Curl Example

curl -i -X POST -H "Content-Type: multipart/form-data" -F "request=<C:/temp/requestUpdateDimVal.xml" -F "content=@C:/temp/updateDimensions.zip" https://api.adaptiveinsights.com/api/v20

requestUpdateDimVal.xml content

<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
    <credentials login="sampleuser@company.com" password="my_password"/>
</call>

updateDimVal.zip/content.xml

<?xml version='1.0' encoding='UTF-8'?>
 <dimensions>
     <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0">
       <dimensionValue id="32" name="Graduate" description="Modified Graduate degree" />
     </dimension>
 </dimensions>

You can still make API requests in the body of an API call without using attachments.

<?xml version='1.0' encoding='UTF-8'?>
<call method="updateDimensions" callerName="Steve C">
    <credentials login="sampleuser@company.com" password="my_password"/>
<dimensions>
     <dimension id="7" name="Education" shortName="" autoCreate="0" listDimension="1" keepSorted="0" useOnLevels="0">
       <dimensionValue id="32" name="Graduate" description="Modified Graduate degree" />
     </dimension>
</dimensions>
</call>
  • Was this article helpful?