Create and Process External Sync Tasks
Vault Connector is an integration component in Vault that connects Vault data and business events with external systems. In practice, a connector-specific workflow (for example, syncing an item to another system) is executed through an external sync task.
This walkthrough explains the background and a practical API flow for creating and tracking external sync tasks. Task execution is handled by the Vault Connector agent workflow after task creation. It is aligned with the desktop sample app demo tab, where these APIs are exposed so you can extend your own integration workflow.
For an overview of Vault Connector, see Vault Connector Overview.
When to Use External Sync Tasks
Use external sync tasks when you need:
- Asynchronous integration with external systems.
- Retry capability for failed sync operations.
- A task record that can be queried by ID or entity IDs while it remains in task storage.
Typical flow:
- Get available external sync configurations for the vault.
- Create one or more external sync tasks.
- Poll task status until it reaches a terminal state.
- Read external sync info on items or item versions for integration results.
- Resubmit failed tasks if needed.
Prerequisites
- Vault server and Vault Data API v2 are available.
- You can authenticate and call API endpoints with a bearer token.
- A connector configuration exists in your target vault.
For authentication details, see Create session with Vault credentials.
Step 1: Inspect External Sync Configs
Before creating a task, confirm the connector config ID and workflow type.
Use: Get all external sync configs
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/vault-options/ext-sync-configs' \
-X 'GET' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {token}'
From the response, identify:
configId(for example:Adsk.Vault.ExternalSyncTask.FusionManage)- Supported workflow type (for example:
Adsk.UploadItem)
Step 2: Create an External Sync Task
Use: Create an external sync task
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/ext-sync-tasks' \
-X 'POST' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
-d '{
"entityId": "127",
"entityClassId": "ITEM",
"configId": "Adsk.Vault.ExternalSyncTask.FusionManage",
"workflowType": "Adsk.UploadItem",
"description": "Sync item 127 to external system"
}'
entityId: The item version ID to sync.entityClassId: Must beITEMfor item sync workflows.
Store the returned task id for status tracking.
Step 3: Track Task Progress
Use one of these APIs:
- Get an external sync task for a specific task.
- Get all external sync tasks with filters for workflow/entity.
curl -v '{VaultServerAddress}/AutodeskDM/Services/api/vault/v2/vaults/{vaultId}/ext-sync-tasks/{taskId}' \
-X 'GET' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer {token}'
Task status indicates processing state. Poll until the task reaches a terminal state:
- Terminal (stop polling):
Succeeded,Failed,PartiallySucceeded,Skipped - Non-terminal (keep polling):
Pending,Running
Step 4: Read Sync Result from Item Info
After processing, read external sync info from the corresponding item or item version.
For item-level APIs, use the item master ID (not the item version ID). The item master ID is available on the item version object as the parent item’s id field.
Item APIs:
Item version APIs:
Two commonly used names:
Adsk.FusionManage.Details: JSON payload with synchronized object details and error fields.Adsk.FusionManage.Status: Numeric status code.
Adsk.FusionManage.Status values:
0: Unknown1: Succeeded2: Failed3: PartiallySucceeded4: Skipped
Step 5: Handle Failures and Scale Out
For retries:
For deleting a task:
For querying by known entities:
For bulk creation:
Recommended Integration Pattern
- Query configs at startup and cache allowed
configId+workflowTypepairs. - Create tasks from your app event (manual action, lifecycle milestone, or batch trigger).
- Persist returned task IDs in your own system for later reconciliation.
- Poll task status and read external sync infos to determine business outcome.
- Resubmit only failed tasks after root-cause checks (auth, mapping, payload quality). Delete tasks that are no longer needed.
Notes
- External sync task APIs provide the building blocks for implementing custom integration behavior on top of Vault Connector workflows.
- Prefer idempotent handling in your client logic to avoid duplicate processing during retries.
- Use task querying and entity-based lookup APIs to build observability dashboards or reconciliation jobs.