API system behavior and design

The Anaplan Integration API v2.0 has predefined behaviors and processes based on the type of requests that are carried out. For example, large imports and exports should be chunked for efficiency and resilience, given the amount of data that is transferred. Another example is a long-running task that needs to be polled to move on to the next step of the integration.

Files are model-level objects used by import and export workflows. Upload files can be split into chunks and loaded sequentially. Export files may also be downloaded in chunks.

Chunking helps avoid timeout and payload-size issues for large files.

Actions that take time to complete return a taskId. You use the taskId to poll the task endpoint.

A task response can include:

• Current task state.
• Current step.
• Progress.
• Result information.
• Failure counts.
• Whether a dump file is available.

Read endpoints return metadata, list data, view data, or file content. Some read requests return JSON. Others return CSV or file streams.

For view data, read the metadata first when you need to map the grid output to dimensions, rows, columns, line items, and page selectors.

Dump files contain details about records or steps that failed during an import or process. Dump files are not the same as export output files.

• Import dumps are associated with import tasks.
• Process dumps are associated with process tasks.
• Export output is downloaded from file chunk endpoints.

Some actions can make a model busy or lock parts of model execution while Anaplan prepares data, runs calculations, loads data, or creates files. Avoid launching conflicting tasks against the same model in parallel unless the workflow has been tested for concurrency.

When the model is busy, retry according to the retry guidance in this guide.

An integration user must be able to authenticate and must have access to the target workspace and model. The user must also have model permissions for the action, module, list, file, view, or process being used.

Some transactional endpoints, such as list maintenance and calendar updates, can require Workspace Administrator permission.

Access to an export action does not guarantee that all data is visible. Selective Access, Dynamic Cell Access, model roles, and module permissions can affect returned data.