Async Tracking API

Submit tracking events to a staging database for later synchronization into Link. Use this when the sending application needs to continue without waiting for each tracking record to be created. Data is not immediately available in Link tracking.

Base path: /api/rest/operation/async-tracking. Here, asynchronous means deferred tracking, not external processing within a Link-managed itinerary. See the Tracking API overview for the distinction and Async Flow API for itinerary callbacks.

.NET clients

For .NET clients, we recommend using the Bizbrains.Link.Api.Proxy NuGet package. See .NET client library for the public NuGet feed, supported APIs, and shared guidance.

Setup and permissions

Configure an enabled scheduler task using Async tracking synchronization, its schedule, and access to the staging and tracking databases. Its configuration includes batch size and retention time; the defaults in this version are 100 requests and 24 hours. Without a running synchronization task, acceptance does not make the data visible in Link.

The operations use the API Tracking role and the same operation permissions as Tracking. Authentication and shared conventions are in [API conventions](api-conventions.md).

Identifiers and sequence

Generate and persist a distinct GUID for each incoming interchange and document before sending the first request. Reuse those entity GUIDs on subsequent events for that entity.

  • POST /initiate-single-document-tracking: supply interchangeIn.interchangeGuid and document.documentGuid.

  • POST /initiate-interchange-tracking, followed by POST /track-document: refer to the incoming interchange with interchangeGuid and give each document its own documentGuid inside document.

  • Status, outgoing-interchange, file, supplementary-file, and CDM events use a top-level documentGuid in place of synchronous Tracking's numeric documentId.

  • PATCH /update-document identifies the document inside document; include its existing GUID.

Submit creation before dependent events. The synchronizer groups creation and file operations ahead of other work within a batch and retries failed requests, but does not guarantee global arrival-order execution. In particular, do not queue competing metadata patches expecting strict last-write ordering.

Interchange updates are an exception: the queued /update-interchange-in and /update-interchange-out operations still delegate to an update that requires interchange.entityId. A GUID alone is insufficient in this implementation. Wait until the numeric ID is available or provide complete interchange metadata during creation instead.

Example: create a record, then record completion

Use the complete tracking-start.json request from Tracking, including its two entity GUIDs and agreed configuration names. Generate new GUIDs for your own records.

set -euo pipefail
LINK_API_BASE='https://<your-link-api-host>'
LINK_PAT='<your-personal-access-token>'

curl --silent --show-error --fail-with-body --include \
  --user ":${LINK_PAT}" --header 'Content-Type: application/json' \
  --data-binary '@tracking-start.json' \
  "${LINK_API_BASE}/api/rest/operation/async-tracking/initiate-single-document-tracking"

After the external processing succeeds, submit a status referencing the same document GUID. This extracts the GUID from the creation file to avoid substituting a numeric ID:

jq '{documentGuid:.document.documentGuid,status:{statusName:"Completed",source:"Contoso ERP",comment:"Order processed successfully"}}' \
  tracking-start.json > async-completed.json

curl --silent --show-error --fail-with-body --include \
  --user ":${LINK_PAT}" --header 'Content-Type: application/json' \
  --data-binary '@async-completed.json' \
  "${LINK_API_BASE}/api/rest/operation/async-tracking/set-document-status"

Both calls return 202 Accepted with no body after staging. They do not return numeric IDs or the eventual processing result. Retain the GUIDs and monitor Link tracking and synchronization-task logs for completion.

Deferred failures and retries

A 202 confirms staging, not full validation of configuration names, referenced records, or file data. Bad or missing references can therefore fail during synchronization rather than in the submission response.

Failed synchronization requests are deferred and retried with increasing delay. Successful requests are removed; expired failed requests are deleted according to the configured retention policy. This API has no per-request status/polling endpoint or completion callback. Monitor the scheduler and resolve failures before retention expires.

The staging save inserts each received request; GUID correlation does not deduplicate submissions. Do not resend accepted events merely because they are not visible yet. After a submission timeout, reconcile the staged/processed state with the environment operator before resending. After a synchronizer interruption, some effects can already exist before staging cleanup, so consumers must also tolerate repeated processing.

Moving from synchronous Tracking

Switch both the base path and the identifiers required by each request; replacing only the URL is insufficient. Remove code that expects immediate entity responses, use durable client-generated GUIDs, and add synchronization monitoring. The supported operation set also differs: this controller has no /set-partner-in or /set-partner-out operations. Test the required operations on the installed version before migration.