Publish Data API v2

This document describes the v2 SourcingData endpoints for publishing data to the DataService input queue.

Overview

The v2 API provides an improved interface for publishing data to the input queue. The key differences from v1:

Uses agentId query parameter instead of sourceId path parameter for agent identification
Supports optional clientId query parameter for client-specific filtering
Simplified URL structure without BySourceId suffix
Enhanced authorization with 401 Unauthorized and 403 Forbidden responses

For general concepts like status flow, data types, and input queue events, see Publish Data v1 Documentation.

Base URL

https://{hostname}/api/asol/ds

Endpoints

1. Get Input Queue Status

Retrieves the status of input queue items sorted from the latest to history.

Endpoint: GET /api/v2/SourcingData/EnqueueData

Query Parameters:

Parameter	Type	Required	Description
`agentId`	`IntegrationAgentId`	No	The identifier of the integration agent
`clientId`	`string`	No	The client identifier for filtering
`offset`	`int`	No	Number of records to skip (default: 0)
`limit`	`int`	No	Maximum number of records to return (default: 100)

Response Statuses:

Status Code	Description
`200 OK`	Successfully retrieved collection
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Authentication required
`403 Forbidden`	Access denied
`404 Not Found`	Agent not found

Response Body:

Property	Type	Description
`queueItemId`	`Guid`	The identifier of queue-item
`operationId`	`Guid`	The identifier of virtual operation, see Operating log
`createdOn`	`DateTime`	The datetime in UTC when queue-item was created
`completedOn`	`DateTime`	The datetime in UTC when queue-item was completed and ready to process
`finishedOn`	`DateTime`	The datetime in UTC when processing of queue-item was finished
`status`	`string`	The status of queue-item
`wasSuccess`	`bool`	The flag if queue-item was successfully processed and data has been updated
`wasFailure`	`bool`	The flag if queue-item was unsuccessfully processed (i.e. failed or canceled)
`errorMessage`	`string`	The error message with failure details (available for `Failed` and `Canceled` statuses)

{
  "totalCount": 49,
  "items": [
    {
      "queueItemId": "35d5d447-b500-4828-8099-a26845c85cb8",
      "operationId": "4ca3fe2c-d164-4621-bb6c-b8da412e43b5",
      "createdOn": "2023-07-25T20:20:33.919Z",
      "completedOn": "2023-07-25T20:20:33.919Z",
      "finishedOn": "2023-07-25T20:21:09.718Z",
      "status": "Success"
    }
  ]
}

Example Request:

GET /api/v2/SourcingData/EnqueueData?agentId=my-agent&offset=0&limit=10

2. Add New Item to Input Queue

Creates a new item in the input queue with data records.

Endpoint: POST /api/v2/SourcingData/EnqueueData/start

Query Parameters:

Parameter	Type	Required	Description
`agentId`	`IntegrationAgentId`	Yes	The identifier of the integration agent
`operationId`	`string`	No	The identifier of virtual operation, see Operating log
`clientId`	`string`	No	The client identifier

Request Body Properties:

Property	Type	Required	Description
`entityMappingId`	`string`	No	The identifier for entity mapping of transformation, the `entityId` is used when not defined
`entityId`	`string`	Yes	The identifier of source entity (e.g. table name/id), used to build `externalId`
`recordId`	`string`	Yes	The identifier of source record (e.g. primary key), used to build `externalId`
`referenceId`	`Guid`	No	The reference identifier of original record from primary data-source
`mandantCode`	`string`	No	The code of organization representing mandant in tenant context (or null for non-mandant data-record)
`fields`	`array`	No	The data (i.e. payload) of data-record, array of key(string)+value(any) pairs processed by data-transformation(s). Only one of the `fields` or `data` can be set at the same time.
`data`	`object`	No	The data (i.e. payload) of data-record, object containing fields and their values processed by data-transformation(s). Only one of the `fields` or `data` can be set at the same time.
`customData`	`object`	No	The data (i.e. payload) of data-record specific for the current tenant and organization, object containing fields and their values processed by data-transformation(s), Only one of the `fields` or `data` can be set at the same time.
`isDeleted`	`bool`	No	The flag if data-record will be upserted or deleted
`incompleteData`	`bool`	No	The flag if data are complete or incomplete, see Status Flow

Request Body:

{
  "items": [
    {
      "entityMappingId": "OrganizationUnit-Deps",
      "entityId": "ORG_DEPT",
      "recordId": "1234",
      "referenceId": "4998966b-d957-4bab-97e0-33863b322d19",
      "mandantCode": "64949541|CZ",
      "isDeleted": false,
      "data": {
        "Code": "Montovna",
        "Name": "Montážní hala",
        "Type": "Workroom.OrganizationUnitType.00000000-0000-0000-0000-000000000000"
      },
      "customData": {
        "CEO": "Robert Vrátník"
      }
    }
  ],
  "incompleteData": false
}

Response Statuses:

Status Code	Description
`201 Created`	Queue-item created and processed synchronously
`202 Accepted`	Queue-item created and will be processed asynchronously
`400 Bad Request`	Invalid request parameters or body
`401 Unauthorized`	Authentication required
`403 Forbidden`	Access denied
`404 Not Found`	Agent not found

Response Body:

{
  "sourceId": "6a06af09-3d17-4bae-a9f4-37ebcaf7a873",
  "queueItemId": "35d5d447-b500-4828-8099-a26845c85cb8",
  "operationId": "4ca3fe2c-d164-4621-bb6c-b8da412e43b5",
  "createdOn": "2023-07-25T20:20:33.919Z",
  "completedOn": "2023-07-25T20:20:33.919Z",
  "finishedOn": "2023-07-25T20:21:09.718Z",
  "status": "Success",
  "wasSuccess": true,
  "wasFailure": null,
  "errorMessage": null
}

Example Request:

POST /api/v2/SourcingData/EnqueueData/start?agentId=my-agent&operationId=4ca3fe2c-d164-4621-bb6c-b8da412e43b5

3. Append Records to Existing Queue Item

Appends additional records to an existing item in the input queue. The queue-item must be in Pending state.

Endpoint: POST /api/v2/SourcingData/EnqueueData/append/{queueItemId}

Path Parameters:

Parameter	Type	Required	Description
`queueItemId`	`string`	Yes	The identifier of queue-item (obtained by `start` method)

Query Parameters:

Parameter	Type	Required	Description
`agentId`	`IntegrationAgentId`	Yes	The identifier of the integration agent
`clientId`	`string`	No	The client identifier

Request Body Properties:

Property	Type	Required	Description
`entityMappingId`	`string`	No	The identifier for entity mapping of transformation, the `entityId` is used when not defined
`entityId`	`string`	Yes	The identifier of source entity (e.g. table name/id), used to build `externalId`
`recordId`	`string`	Yes	The identifier of source record (e.g. primary key), used to build `externalId`
`referenceId`	`Guid`	No	The reference identifier of original record from primary data-source
`mandantCode`	`string`	No	The code of organization representing mandant in tenant context (or null for non-mandant data-record)
`fields`	`array`	No	The data (i.e. payload) of data-record, array of key(string)+value(any) pairs processed by data-transformation(s). Only one of the `fields` or `data` can be set at the same time.
`data`	`object`	No	The data (i.e. payload) of data-record, object containing fields and their values processed by data-transformation(s). Only one of the `fields` or `data` can be set at the same time.
`customData`	`object`	No	The data (i.e. payload) of data-record specific for the current tenant and organization, object containing fields and their values processed by data-transformation(s), Only one of the `fields` or `data` can be set at the same time.
`isDeleted`	`bool`	No	The flag if data-record will be upserted or deleted
`incompleteData`	`bool`	No	The flag if data are complete or incomplete, see Status Flow

Request Body:

{
  "items": [
    {
      "entityMappingId": "OrganizationUnit-Deps",
      "entityId": "ORG_DEPT",
      "recordId": "1234",
      "referenceId": "d16ef9d6-c0c6-4ac6-8140-4608531b4e99",
      "mandantCode": "64949541|CZ",
      "isDeleted": true,
      "fields": null
    }
  ],
  "incompleteData": false
}

Response Statuses:

Status Code	Description
`201 Created`	Last chunk processed synchronously
`202 Accepted`	Chunk appended and will be processed asynchronously
`400 Bad Request`	Invalid request parameters or body
`401 Unauthorized`	Authentication required
`403 Forbidden`	Access denied
`404 Not Found`	Queue-item or agent not found

Response Body:

{
  "sourceId": "6a06af09-3d17-4bae-a9f4-37ebcaf7a873",
  "queueItemId": "35d5d447-b500-4828-8099-a26845c85cb8",
  "operationId": "4ca3fe2c-d164-4621-bb6c-b8da412e43b5",
  "createdOn": "2023-07-25T20:20:33.919Z",
  "completedOn": "2023-07-25T20:20:33.919Z",
  "status": "Completed"
}

Example Request:

POST /api/v2/SourcingData/EnqueueData/append/35d5d447-b500-4828-8099-a26845c85cb8?agentId=my-agent

4. Get Queue Item Status

Retrieves the status of a specific queue-item in the input queue.

Endpoint: GET /api/v2/SourcingData/EnqueueData/status/{queueItemId}

Path Parameters:

Parameter	Type	Required	Description
`queueItemId`	`string`	Yes	The identifier of queue-item (obtained by `start` method)

Query Parameters:

Parameter	Type	Required	Description
`agentId`	`IntegrationAgentId`	Yes	The identifier of the integration agent
`clientId`	`string`	No	The client identifier

Response Statuses:

Status Code	Description
`200 OK`	Successfully retrieved queue-item status
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Authentication required
`403 Forbidden`	Access denied
`404 Not Found`	Queue-item or agent not found

Response Body:

{
  "sourceId": "f74f0f97-c999-42ce-8e96-b74daeceaf5c",
  "queueItemId": "b6f450c3-46de-4e8c-85de-b9ab11b221ab",
  "operationId": "478661db-5567-4d99-b484-cb405d29d327",
  "createdOn": "2023-09-04T16:51:29.61Z",
  "completedOn": "2023-09-04T16:51:29.61Z",
  "finishedOn": "2023-09-04T16:51:31.728Z",
  "status": "Failed",
  "wasFailure": true,
  "errorMessage": "Value 'None,Branch,Department,Team,,Workshop,Workroom' doesn't fit to expected format. (Parameter 'value')"
}

Example Request:

GET /api/v2/SourcingData/EnqueueData/status/b6f450c3-46de-4e8c-85de-b9ab11b221ab?agentId=my-agent

5. Cancel Queue Item

Cancels a queue-item in the input queue.

Endpoint: DELETE /api/v2/SourcingData/EnqueueData/cancel/{queueItemId}

Path Parameters:

Parameter	Type	Required	Description
`queueItemId`	`string`	Yes	The identifier of queue-item (obtained by `start` method)

Query Parameters:

Parameter	Type	Required	Description
`agentId`	`IntegrationAgentId`	Yes	The identifier of the integration agent
`clientId`	`string`	No	The client identifier

Response Statuses:

Status Code	Description
`204 No Content`	Successfully canceled the queue-item
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Authentication required
`403 Forbidden`	Access denied
`404 Not Found`	Queue-item or agent not found

Example Request:

DELETE /api/v2/SourcingData/EnqueueData/cancel/35d5d447-b500-4828-8099-a26845c85cb8?agentId=my-agent

Migration from v1 to v2

Key Changes

Aspect	v1	v2
Agent Identification	Path parameter `sourceId` (Guid)	Query parameter `agentId` (IntegrationAgentId)
Client Support	Not available	Optional `clientId` query parameter
URL Structure	`/EnqueueDataBySourceId/{sourceId}/...`	`/EnqueueData/...`
Authorization	Basic authorization responses	Enhanced with `401` and `403` responses

Example Migration

v1 Request:

POST /api/v1/SourcingData/EnqueueDataBySourceId/6a06af09-3d17-4bae-a9f4-37ebcaf7a873/start

v2 Request:

POST /api/v2/SourcingData/EnqueueData/start?agentId=my-agent

Notes

It is recommended to send larger data using multiple requests (e.g. use approximately 500 data-records in a single request) to avoid timeouts. You can use start/append methods to create and append data into a single queue-item.
Each queue-item represents a unit of work which is processed together, i.e. all data must be successfully transformed first, then data-records are stored. Otherwise the complete queue-item is finished with failure and no data are updated.
There is a technical limit for maximal size of data in queue-item: approximately 3000-4000 items (depending on JSON size).
When a queue-item contains less than 500 data-records, the queue-item can be processed synchronously (depending on statuses of other queue-items and current workload of processing engine). Otherwise the queue-item will be processed asynchronously. Check the response status code (201/202).

Publish Data v1 API - v1 API documentation with data types and status flow details
Operating Log - Virtual operation tracking
Data Transformation - Input data transformation configuration
Data Integration Examples - AMQP messaging integration

Overview​

Base URL​

Endpoints​

1. Get Input Queue Status​

2. Add New Item to Input Queue​

3. Append Records to Existing Queue Item​

4. Get Queue Item Status​

5. Cancel Queue Item​

Migration from v1 to v2​

Key Changes​

Example Migration​

Notes​

Related Documentation​

Overview

Base URL

Endpoints

1. Get Input Queue Status

2. Add New Item to Input Queue

3. Append Records to Existing Queue Item

4. Get Queue Item Status

5. Cancel Queue Item

Migration from v1 to v2

Key Changes

Example Migration

Notes

Related Documentation