Request

Response

    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:

    1. Get available external sync configurations for the vault.
    2. Create one or more external sync tasks.
    3. Poll task status until it reaches a terminal state.
    4. Read external sync info on items or item versions for integration results.
    5. Resubmit failed tasks if needed.

    Prerequisites

    1. Vault server and Vault Data API v2 are available.
    2. You can authenticate and call API endpoints with a bearer token.
    3. 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"
      }'
    
    Show More
    • entityId: The item version ID to sync.
    • entityClassId: Must be ITEM for item sync workflows.

    Store the returned task id for status tracking.

    Step 3: Track Task Progress

    Use one of these APIs:

    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: Unknown
    • 1: Succeeded
    • 2: Failed
    • 3: PartiallySucceeded
    • 4: Skipped

    Step 5: Handle Failures and Scale Out

    For retries:

    For deleting a task:

    For querying by known entities:

    For bulk creation:

    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.