Connector registration

Connector registration for multi-tenant cloud services

Use DevOps application for connector management (e.g. client credentials).

Use Product App or DevOps App to register your application
Use Application agent catalogue in Integration section to get clientId and reset secrets
Use REST API for registration and configuration of data-agent, see below

Register integration-agent using REST API

The registration process of data-agent/data-source for multi-tenant cloud services using DataService backend service. The data-agent and data-source must be registered once for each tenant.

Important: Use GUID generator to generate unique identifier of your data-agent and data-source. Use the same GUIDs for all tenants.

Note: don't forget to enable data-agent and data-source to turn on data-integration processing.

DataService API base URL: https://{hostname}/api/asol/ds

V2.1 IntegrationAgents API endpoints for multi-instance integration agents - New

Important: The V2.1 API endpoints supplement and improve the V2 API endpoints and will probably replace them in the future. The integration agent instance is identified by agentCode (= clientId of the agent's service account) instead of sourceId. The integrated application can be served by several instances of the multi-tenant integration agent (e.g. private clouds). The identifiers (agentId, sourceId) are always generated by DataService, they can't be specified. The identifiers of already registered integration agents are preserved.

Note: The agentCode parameter is optional for the integration agent, the calling integration agent (clientId of its service account) is used by default and an explicitly specified value must match it. The agentCode parameter is mandatory for support user(s) to specify the integration agent explicitly. The same applies to the applicationCode parameter of SupportedFeatures endpoints (the application of the calling integration agent by default).

The rules of agentCode for multi-tenant (cloud) integration agents:

the default instance - agentCode equals to applicationCode, e.g. ASOLEU-DataIntegrationExample-AP-
the additional instance - agentCode is composed of applicationCode, separator - and suffix, e.g. ASOLEU-DataIntegrationExample-AP--eu2
- the suffix contains ASCII letters, digits and single hyphens (max. 32 characters)
the agentCode of single-tenant (on-premise) integration agents isn't composed of applicationCode, the applicationCode must be specified

The server responses common for V2.1 API endpoints:

400 - means invalid request (e.g. invalid or missing agentCode / applicationCode, invalid request body); the commands (PATCH, POST) return 400 also when integration-agent isn't registered
404 - means that integration-agent isn't registered (yet) or was unregistered (GET Settings, GET OnPremiseSettings and DELETE)
409 - means that integration-agent with the same agentCode is already registered (registration only), including the integration-agent registered without agentCode (e.g. by V1 API endpoints)
412 - means that a prerequisite isn't met:
- the integrated application isn't registered in advance (applicationCode isn't available)
- the integration-agent is registered without agentCode (e.g. by V1 API endpoints), so it doesn't meet the criteria of V2.1 API endpoints; complete the registration by V1 API endpoints first (agentCode of V1 ImportDataAgent or clientId of V1 IntegrationSettings)

List endpoint

Get the list of registered integration-agents
GET /api/v2.1/IntegrationAgents

query parameters for filtering (optional):
- offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
- applicationCode - the code of integrated application, e.g. ASOLEU-DataIntegrationExample-AP-
- agentCode - the code of integration-agent instance (clientId of its service account), e.g. ASOLEU-DataIntegrationExample-AP--eu2
- tenantId - the tenant where the single-tenant integration-agent was created (i.e. the owner tenant)
- registeredTenantId - the tenant where the integration-agent is registered for data integration
- isOnPremise - the flag to get single-tenant (=true) or multi-tenant (=false) integration-agents only
server response:
- 200 - the integration-agent gets its own registration only, the support user gets all registrations
sample response body:

{
  "totalCount": 1,
  "items": [
    {
      "agentCode": "ASOLEU-DataIntegrationExample-AP--eu2",
      "applicationCode": "ASOLEU-DataIntegrationExample-AP-",
      "agentId": "0b6f3c1e-7d4a-4f2b-9a51-3c8e2d1f4a60",
      "sourceId": "5d2a9e7c-1b3f-4c8d-a6e2-9f0b7c4d3e21",
      "tenantId": null,
      "isOnPremise": false,
      "isDefaultInstance": false,
      "registeredTenants": [
        {
          "tenantId": "ASOLEU-TENANT",
          "enabled": true
        }
      ],
      "createdOn": "2026-10-16T07:30:36.365Z",
      "modifiedOn": "2026-10-16T07:30:36.365Z"
    }
  ]
}

Settings endpoints

The Settings endpoints can be used by multi-tenant integration agent(s) only. The registration is shared per all tenants.

Try get definition of the multi-tenant integration-agent
GET /api/v2.1/IntegrationAgents/Settings

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
server response:
- 200 - means that integration-agent is already registered
- 404 - means that integration-agent isn't registered yet
sample response body:

{
  "agentCode": "ASOLEU-DataIntegrationExample-AP--eu2",
  "applicationCode": "ASOLEU-DataIntegrationExample-AP-",
  "tenantId": null,
  "isOnPremise": false,
  "agent": {
    "agentId": "0b6f3c1e-7d4a-4f2b-9a51-3c8e2d1f4a60",
    "agentCode": "ASOLEU-DataIntegrationExample-AP--eu2",
    "enabled": true
  },
  "source": {
    "sourceId": "5d2a9e7c-1b3f-4c8d-a6e2-9f0b7c4d3e21",
    "sourceCode": "ASOLEU-DataIntegrationExample-AP--eu2",
    "applicationCode": "ASOLEU-DataIntegrationExample-AP-",
    "enabled": true,
    "consumerCode": "ASOLEU-DataIntegrationExample-AP--eu2",
    "consumerType": "Grpc"
  },
  "consumer": {
    "consumerCode": "ASOLEU-DataIntegrationExample-AP--eu2",
    "consumerChannel": "gRPC",
    "consumerIsConnected": false,
    "consumerStatus": "Healthy"
  }
}

agentCode - (optional) the code of new integration-agent instance, i.e. clientId of its service account: ASOLEU-DataIntegrationExample-AP- (default instance) or ASOLEU-DataIntegrationExample-AP--eu2 (additional instance with suffix), the calling integration-agent by default (mandatory for support user)
applicationCode - (optional) the code of integrated application, derived from agentCode by default (the application must be registered in advance)
request body properties: the same as for V2 POST /api/v2/IntegrationAgents/Settings
server response:
- 201 - means that integration-agent was registered (in the tenant context it is registered also in the current tenant)
- 409 - means that integration-agent is already registered (use PATCH to update registration)
- 412 - means that integrated application isn't registered in advance

Update registration of the multi-tenant integration-agent (it never registers new integration-agent)
PATCH /api/v2.1/IntegrationAgents/Settings

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 POST /api/v2/IntegrationAgents/Settings
server response:
- 200 - means that registration of integration-agent was updated
- 400 - means that integration-agent isn't registered

Note: you can call this endpoint with empty request body {} to verify (ensure) the registration of integration-agent when integration-agent was started - nothing is changed, the server response 200 returns the current settings with status and 400 means that integration-agent isn't registered yet (use POST to register it).

Unregister the multi-tenant integration-agent
DELETE /api/v2.1/IntegrationAgents/Settings

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
server response:
- 204 - means that integration-agent was unregistered including its transformations and registrations in all tenants
- 404 - means that integration-agent isn't registered

Important: The unregistered integration-agent can't be restored. A new registration with the same agentCode gets new identifiers (agentId, sourceId) and its own history.

OnPremiseSettings endpoints

The OnPremiseSettings endpoints can be used by single-tenant integration agent(s) only. The registration is available in the current tenant only.

Try get definition of the single-tenant integration-agent
GET /api/v2.1/IntegrationAgents/OnPremiseSettings

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
server response:
- 200 - means that integration-agent is already registered
- 404 - means that integration-agent isn't registered yet
response body: the same as for GET /api/v2.1/IntegrationAgents/Settings (tenantId = current tenant, isOnPremise = true)

Register the single-tenant integration-agent in the current tenant (registration only)
POST /api/v2.1/IntegrationAgents/OnPremiseSettings

applicationCode - (mandatory) the code of integrated application, it can't be derived from agentCode of single-tenant integration-agent (the application must be registered in advance)
agentCode - (optional) the code of new integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 POST /api/v2/IntegrationAgents/Settings
server response:
- 201 - means that integration-agent was registered
- 409 - means that integration-agent is already registered (use PATCH to update registration)
- 412 - means that integrated application isn't registered in advance

Update registration of the single-tenant integration-agent (it never registers new integration-agent)
PATCH /api/v2.1/IntegrationAgents/OnPremiseSettings

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 POST /api/v2/IntegrationAgents/Settings
server response:
- 200 - means that registration of integration-agent was updated
- 400 - means that integration-agent isn't registered

Unregister the single-tenant integration-agent
DELETE /api/v2.1/IntegrationAgents/OnPremiseSettings

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
server response:
- 204 - means that integration-agent was unregistered including its transformations and registration in the current tenant
- 404 - means that integration-agent isn't registered

Transformations endpoints

The input transformations are defined per integration-agent instance.

Get input transformations the integration-agent
GET /api/v2.1/IntegrationAgents/Transformations

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
response body: the same as for V2 GET /api/v2/IntegrationAgents/Transformations

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 PATCH /api/v2/IntegrationAgents/Transformations

Note: the removed transformations are never restored, a new definition with the same customCode gets a new identifier.

ConfigureConsumer endpoint

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 PATCH /api/v2/IntegrationAgents/ConfigureConsumer

Note: in the tenant context the integration-agent is registered also in the current tenant.

Statuses endpoints

Get status history of the integration-agent
GET /api/v2.1/IntegrationAgents/Statuses

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
query parameters for filtering (optional): the same as for V2 GET /api/v2/IntegrationAgents/Statuses
response body: the same as for V2 GET /api/v2/IntegrationAgents/Statuses

Create new status of the integration-agent
POST /api/v2.1/IntegrationAgents/Statuses

agentCode - (optional) the code of integration-agent instance, i.e. clientId of its service account, the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 POST /api/v2/IntegrationAgents/Statuses

SupportedFeatures endpoints

The supported features are defined per integrated application, i.e. shared by all instances of integration-agent.

Try get supported features of the integrated application
GET /api/v2.1/IntegrationAgents/SupportedFeatures

applicationCode - (optional) the code of integrated application, the application of the calling integration-agent by default (mandatory for support user)
response body: the same as for V2 GET /api/v2/IntegrationAgents/SupportedFeatures

applicationCode - (optional) the code of integrated application, the application of the calling integration-agent by default (mandatory for support user)
request body properties: the same as for V2 PATCH /api/v2/IntegrationAgents/SupportedFeatures

V2 IntegrationAgents API endpoints for data integration - Preferred

Important: The identification of integration agent is primarily driven by service account. The multi-tenant integration agent is registered once and the registration is shared per all tenants. The sourceId parameter is used to specify data-source identifier for compatibility reasons when necessary. The clientId parameter is used by support user(s) to specify service account explicitly for diagnostic purposes only.

Note: These V2 API endpoints (except Settings) can be used by both: the multi-tenant and single-tenant integration agents.

Settings endpoints

The Settings endpoints can be used by multi-tenant integration agent(s) only.

Try get definition of the multi-tenant integration-agent
GET /api/v2/IntegrationAgents/Settings

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
server response:
- 200 - means that integration-agent is already registered
- 404 - means that integration-agent isn't registered yet
sample response body:

{
  "agent": {
    "agentId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
    "agentCode": "ASOLEU-DataIntegrationExample-AP-",
    "enabled": true
  },
  "source": {
    "sourceId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
    "sourceCode": "ASOLEU-DataIntegrationExample-AP-",
    "applicationCode": "ASOLEU-DataIntegrationExample-AP-",
    "enabled": true,
    "consumerCode": "ASOLEU-DataIntegrationExample-AP-",
    "consumerType": "Grpc"
  },
  "consumer": {
    "consumerCode": "ASOLEU-DataIntegrationExample-AP-",
    "consumerChannel": "gRPC",
    "consumerIsConnected": false,
    "consumerStatus": "Healthy"
  }
}

Register the multi-tenant integration-agent or update registration of integration-agent if not registered
POST /api/v2/IntegrationAgents/Settings

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
request body properties:
- agentDefinition
  - description - (optional) the description of data-agent
  - customProperties - (optional) the custom properties to customize data-agent behavior
    - Important: set AutoRefreshStatusInterval when the refreshSourceStatus notification is turned on by message consumer
- sourceDefinition
  - description - (optional) the description of data-source
  - customProperties - (optional) the custom properties to customize data-source behavior
  - consumerType - the type of used message consumer (values: Grpc, Webhook or None)
    - Important: mandatory to specify the Grpc or Webhook type for message consumer of external application
  - consumerWebhookUrl - (optional) the webhook URL of external application (mandatory for Webhook consumer)
sample request body:

{
  "agentDefinition": {
    "description": "Example of multi-tenant integration agent",
    "customProperties": [
      {
        "key": "AutoRefreshStatusInterval",
        "value": "0.01:00:00"
      }
    ]
  },
  "sourceDefinition": {
    "description": "Example of multi-tenant integration agent",
    "consumerType": "Grpc",
    "consumerWebhookUrl": null
  }
}

Ensure that registration of integration-agent is ok (note: you should call this endpoint when integration-agent was started)
POST /api/v2/IntegrationAgents/Settings

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
request body:

{
}

sample response body:

{
  "agent": {
    "agentId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
    "agentCode": "ASOLEU-DataIntegrationExample-AP-",
    "enabled": true,
    "customProperties": [
      {
        "key": "AutoRefreshStatusInterval",
        "value": "0.01:00:00"
      }
    ]
  },
  "source": {
    "sourceId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
    "sourceCode": "ASOLEU-DataIntegrationExample-AP-",
    "applicationCode": "ASOLEU-DataIntegrationExample-AP-",
    "enabled": true,
    "consumerCode": "ASOLEU-DataIntegrationExample-AP-",
    "consumerType": "Grpc"
  },
  "consumer": {
    "consumerCode": "ASOLEU-DataIntegrationExample-AP-",
    "consumerChannel": "gRPC",
    "consumerIsConnected": false,
    "consumerStatus": "Healthy"
  }
}

Transformations endpoints

Get input transformations the integration-agent
GET /api/v2/IntegrationAgents/Transformations

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
server response:
- 200 - means that integration-agent is already registered
- 404 - means that integration-agent isn't registered yet
sample response body:

{
  "sourceId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
  "transformations": {
    "totalCount": 1,
    "items": [
      {
        "customCode": "Example-Entities",
        "mappings": [
          {
            "entityId": "ExampleAuthor",
            "priority": 0,
            "modelId": "6ec3c414-02e5-48a8-81e0-0e120bb9909b",
            "transformationType": "Default",
            "autoMapFields": false,
            "mappings": [
              {
                "sourceFieldName": "NAME",
                "targetFieldName": "Name",
                "transformationType": "Default",
                "aggregateFunction": "None"
              },
              {
                "sourceFieldName": "DESCR",
                "targetFieldName": "Biography",
                "transformationType": "Default",
                "aggregateFunction": "None"
              }
            ],
            "isSupplementary": false
          }
        ]
      }
    ]
  }
}

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
request body properties:
- upsert - the collection of definitions for insert or update
- remove - the custom codes of definitions to remove (if not preserved by upsert)
- removeAll - the flag to remove all definitions (except ones preserved by upsert)
sample request body:

{
  "upsert": [
    {
      "customCode": "Example-Entities",
      "description": "Transformation for Example entities like (ExampleAuthor, ExampleBook and ExampleGenre)",
      "mappings": [
        {
          {
            "entityId": "ExampleAuthor",
            "modelId": "6ec3c414-02e5-48a8-81e0-0e120bb9909b",
            "mappings": [
              {
                "sourceFieldName": "NAME",
                "targetFieldName": "Name"
              },
              {
                "sourceFieldName": "DESCR",
                "targetFieldName": "Biography"
              }
            ]
          }
        }
      ]
    }
  ],
  "remove": [
    "Example-Entities"
  ],
  "removeAll": false
}

ConfigureConsumer endpoint

id - (mandatory) the GUID identifier of data-source
request body properties:
- enqueueDataStatus - (optional) the flag to enable/disable 'ASOL.DataService.EnqueueDataStatusChanged' message type
- integrationDataChanges - (optional) the flag to enable/disable 'ASOL.DataService.IntegrationDataChanged' message type with multi-tenant filter
- integrationProfileStatus - (optional) the flag to enable/disable 'ASOL.DataService.IntegrationProfileChangeStarted' and 'ASOL.DataService.IntegrationProfileChangeCompleted' message types
- dataRecordChanges - (optional) the flag to enable/disable 'ASOL.DataService.RecordCreated', 'ASOL.DataService.RecordUpdated' and 'ASOL.DataService.RecordDeleted' message types with multi-tenant filter
- refreshSourceConfig - (optional) the flag to enable/disable 'ASOL.DataService.RefreshSourceConfig' message type
- refreshSourceStatus - (optional) the flag to enable/disable 'ASOL.DataService.RefreshSourceStatus' message type
- refreshTenants - (optional) the flag to replace(=true) all existing tenant filters or add/remove(=false) current tenant filter for message types with multi-tenant filter (default: false)
sample request body:

{
  "enqueueDataStatus": false,
  "integrationDataChanges": true,
  "integrationProfileStatus": true,
  "dataRecordChanges": false,
  "refreshSourceConfig": true,
  "refreshSourceStatus": true
}

Note: you can setup flags together or independently (i.e. PATCH method), null means no change.

Statuses endpoints

Get status history of the integration-agent
GET /api/v2/IntegrationAgents/Statuses

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
query parameters for filtering (optional):
- offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
- operationId - the identifier of virtual operation, see Operating log
- statusItemId - the identifier of specific status record
server response:
- 200 - means that integration-agent is already registered
- 404 - means that integration-agent isn't registered yet
sample response body:

{
  "sourceId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
  "statuses": {
    "totalCount": 1,
    "items": [
      {
        "statusItemId": "ccc93db6-5813-469d-97bc-f89f4b719c6d",
        "operationId": "2055f48c-9470-47e8-b809-c16d37742350",
        "isLive": true,
        "isReady": true,
        "verboseStatus": [
          "TEST"
        ],
        "utcTimestamp": "2025-04-10T07:30:36.365Z",
        "createdOn": "2025-04-10T07:31:39.199Z"
      }
    ]
  }
}

Create new status of the integration-agent
POST /api/v2/IntegrationAgents/Statuses

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
request body properties:
- operationId - (optional) the identifier of virtual operation, see Operating log
- isLive - the flag if the integration-agent is healthy and connected to AVAplace platform
- isReady - the flag if the integration-agent is healthy and ready to communicate with 3rd-party application
- verboseStatus - (optional) the verbose status
- utcTimestamp - the status timestamp in UTC of the integration-agent
sample request body:

{
  "operationId": "2055f48c-9470-47e8-b809-c16d37742350",
  "isLive": true,
  "isReady": true,
  "verboseStatus": [
    "TEST"
  ],
  "utcTimestamp": "2025-04-10T07:30:36.365Z"
}

SupportedFeatures endpoints

Try get supported features of the integration-agent
GET /api/v2/IntegrationAgents/SupportedFeatures

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
server response:
- 200 - means that integration-agent is already registered
- 404 - means that integration-agent isn't registered yet
sample response body:

{
  "sourceId": "1a83fde1-8cdb-4481-a503-bf7a22afeafe",
  "application": {
    "id": "3f5e77b1-fb25-4b11-b00d-fc195ca18ca1",
    "code": "ASOLEU-DataIntegrationExample-AP-",
    "name": "DataIntegration Example",
    "isNative": false,
    "isOnPremise": false,
    "released": true,
    "deleted": false
  },
  "supportedFeatures": {
    "totalCount": 1,
    "items": [
      {
        "applicationUsage": "Input",
        "featureUsage": "Input",
        "featureId": "ee9ec8a4-b3ab-4395-8197-4924ca3bb2b4",
        "feature": {
          "id": "ee9ec8a4-b3ab-4395-8197-4924ca3bb2b4",
          "code": "Employments",
          "name": "Employments",
          "released": true,
          "deleted": false
        }
      }
    ]
  }
}

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
request body properties:
- upsert - the collection of definitions for insert or update
- remove - the feature codes of definitions to remove (if not preserved by upsert)
- removeAll - the flag to remove all definitions (except ones preserved by upsert)
sample request body:

{
  "upsert": [
    {
      "featureCode": "Employments",
      "featureUsage": "Input"
    }
  ],
  "remove": [
    "Employments"
  ],
  "removeAll": false
}

V1 DataAgents and DataSources API endpoints for data integration - Obsolete

Important: These V1 API endpoints were kept for compatibility reasons only and will be removed in future releases.

Try get the data-agent definition using identifier
GET /api/v1/DataAgents/{id}

id - (mandatory) the data-agent identifier
server response:
200 - means that data-agent is already registered
404 - means that data-agent isn't registered yet

allowUpdate - (optional) flag if update of existing definition is allowed or not
request body properties:
- id - the GUID identifier of data-agent
- code - (mandatory) the unique code of data-agent "<app-vendor>.<agent-name>", e.g. "ASOL.DataIntegrationExternalAgent"
- description - the description of data-agent
- enabled - the flag if data-agent is enabled or disabled
- agentCode - (optional) the code of integration-agent instance (clientId of its service account), otherwise it is assigned by clientId of IntegrationSettings of data-source; the assigned value can't be changed
- applicationCode - (optional) the code of integrated application, otherwise it is derived from agentCode of multi-tenant integration-agent or assigned by IntegrationSettings of data-source; the assigned value can't be changed
sample request body:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa5",
  "code": "ASOL.DataIntegrationExternalAgent",
  "enabled": true
}

Try get the data-source definition using identifier
GET /api/v1/DataSources/{id}

id - (mandatory) the data-source identifier
server response:
200 - means that data-source is already registered
404 - means that data-source isn't registered yet

allowUpdate - (optional) flag if update of existing definition is allowed or not
request body properties:
- id - the GUID identifier of data-source
- agentId - (mandatory) the GUID identifier of data-agent
- name - (mandatory) the unique code of data-source, the code of your data-agent can be used here for simplicity
- description - the description of data-source
- enabled - the flag if data-source is enabled or disabled
sample request body:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa4",
  "agentId": "3fa85f64-5717-4562-b3fc-2c963f66afa5",
  "name": "ASOL.DataIntegrationExternalAgent",
  "enabled": true
}

Register MessageGateway consumer for data-agent using REST API

The MessageGateway is service encapsulating message broker and AMQP protocol. The MessageGateway supports two types of communication: gRPC and Webhook.

Configure data-source for message-gateway consumer and integration scenarios
PATCH /api/v1/DataSources/{id}/IntegrationSettings

id - (mandatory) the GUID identifier of data-source
request body properties:
- applicationCode - the global application code of application integrated by data-agent/data-source
- clientId - the clientId of service account used by data-agent/data-source
- consumerCode - the unique code of MessageGateway consumer used by data-agent/data-source
- consumerType - the type of consumer ("Grpc", "Webhook")
- consumerWebhookUrl - the consumer webhook URL used by data-agent/data-source
- useIntegrationProfile - the flag if integration profile is used or not (false = legacy mode, true = business scenarios)
- useConsumerSettings - the flag if legacy consumer settings is used when integration profile isn't used
sample request body:

{
  "applicationCode": "ASOLEU-TEST-AP-",
  "clientId": "ASOLEU-TEST-AP-",
  "consumerCode": "ASOLEU-TEST-AP-",
  "consumerType": "Grpc",
  "useIntegrationProfile": false,
  "useConsumerSettings": false
}

Note: you can setup properties together or independently (i.e. PATCH method), null means no change, empty string means clear value.

id - (mandatory) the GUID identifier of data-source
request body properties:
- enqueueDataStatus - (optional) the flag to enable/disable 'ASOL.DataService.EnqueueDataStatusChanged' message type
- integrationDataChanges - (optional) the flag to enable/disable 'ASOL.DataService.IntegrationDataChanged' message type with multi-tenant filter
- integrationProfileStatus - (optional) the flag to enable/disable 'ASOL.DataService.IntegrationProfileChangeStarted' and 'ASOL.DataService.IntegrationProfileChangeCompleted' message types
- dataRecordChanges - (optional) the flag to enable/disable 'ASOL.DataService.RecordCreated', 'ASOL.DataService.RecordUpdated' and 'ASOL.DataService.RecordDeleted' message types with multi-tenant filter
- refreshSourceConfig - (optional) the flag to enable/disable 'ASOL.DataService.RefreshSourceConfig' message type
- refreshSourceStatus - (optional) the flag to enable/disable 'ASOL.DataService.RefreshSourceStatus' message type
- refreshTenants - (optional) the flag to replace(=true) all existing tenant filters or add/remove(=false) current tenant filter for message types with multi-tenant filter (default: false)
sample request body:

{
  "enqueueDataStatus": true,
  "integrationDataChanges": true,
  "integrationProfileStatus": true,
  "dataRecordChanges": true,
  "refreshSourceConfig": true,
  "refreshSourceStatus": true
}

Note: you can setup flags together or independently (i.e. PATCH method), null means no change.

Data-agent metadata events

Messages remotely commanding data-agent/application. The remote commands have a limited durability (= 1 hour expiration).

These events can be consumed via messaging, see The 1st method of communication - Message Publisher / Consumer.

ASOL.DataService.RefreshSourceStatus

Remote command to refresh/reload configuration of data-source.

Event definitions

messageType: ASOL.DataService.RefreshSourceStatus
- contractType: RefreshStatusEvent
- exchange: ASOL.DataService.Edge.Contracts.Events:RefreshStatusEvent
- queueName: DS.Commands
- queueArguments: { "x-message-ttl": "3600000" }

Event headers

X-DataSourceId - the requested data-source identifier
X-Tenant-Id - the tenant identifier of customer

Event classes

ASOL.DataService.Edge.Contracts.Events.RefreshStatusEvent

Event properties

sourceId - the requested data-source identifier

ASOL.DataService.RefreshSourceConfig

Remote command to provide current health-status of data-source.

Event definitions

messageType: ASOL.DataService.RefreshSourceConfig
- contractType: RefreshConfigEvent
- exchange: ASOL.DataService.Edge.Contracts.Events:RefreshConfigEvent
- queueName: DS.Commands
- queueArguments: { "x-message-ttl": "3600000" }

Event headers

X-DataSourceId - the requested data-source identifier
X-Tenant-Id - the tenant identifier of customer

Event classes

ASOL.DataService.Edge.Contracts.Events.RefreshConfigEvent

Event properties

sourceId - the requested data-source identifier

Migration between message broker and message gateway

Upgrade from Message Broker to Message Gateway

Use IntegrationSettings api endpoint to setup ConsumerCode and ConsumerType

example of request body for gRPC:

{
  "consumerCode": "ASOLEU-TEST-AP-",
  "consumerType": "Grpc"
}

example of request body for Webhook:

{
  "consumerCode": "ASOLEU-TEST-AP-",
  "consumerType": "Webhook",
  "consumerWebhookUrl": "https://yourwebhookapi.com/webhook"
}

Use ConfigureConsumer api endpoint to configure consumer in MessageGateway

Important: register only such message-types which are consumed by your data-agent
example of request body:

{
  ...
  "integrationDataChanges": true,
  "integrationProfileStatus": true,
  "refreshSourceConfig": true,
  "refreshSourceStatus": true
  ...
}

Inform AVAplace DevOps team to remove your public IP address registered in firewall and let consumer queues on Message Broker to expire (expires policy configured on the broker by DevOps)

Revert to Message Broker from Message Gateway

Use ConfigureConsumer api endpoint to reconfigure consumer in MessageGateway and unregister all message-types from consumer queues

example of request body:

{
  "enqueueDataStatus": false,
  "integrationDataChanges": false,
  "integrationProfileStatus": false,
  "dataRecordChanges": false,
  "refreshSourceConfig": false,
  "refreshSourceStatus": false
}

Use IntegrationSettings api endpoint to switch ConsumerType

example of request body:

{
  "consumerType": "None"
}

Inform AVAplace DevOps team to register your public IP address in firewall

Note: AMQP consumer queues on Message Broker are created automatically when your data-integration agent is connected again

Connector registration for single-tenant on-premise systems

Use Connector Catalogue application for connector management and registration of data-agent. Currently the on-premise connectors and agents for external applications (e.g. ERP IS) are supported.

images/cc-app-tile.png

Prerequisites:

valid license for Connector Catalogue application
Admin app role ASOLEU-CONCATAPP-AP-.Admin or TenantAdmin platform role

Choose and configure connector

Connector represents the business level configuration. Each connector can have the single registration per tenant.

Register connector for your product (per tenant), if not already done
Note: don't forget to Enable connector to turn on data-integration processing.

Register and configure data-agent

On-premise agent represents the technical level configuration. Each agent is associated to the specific connector and can have the multiple registrations per tenant. Each instance typically represents the on-premise installation of external application (e.g. ERP IS).

Register agent for your agent instance
Copy AgentCode, DataSourceId, TenantId and MandantCode settings and paste into appsettings.json
=> registered agent has dataAgentId and dataSourceId automatically assigned and ready to use
Note: don't forget to Enable data-agent to turn on data-integration processing.

Generate secrets for data-agent

images/cc-agent-secrets.png

Copy secrets and paste into appsettings.json / secrets.json

Register data-agent using REST API

The registration process of data-agent/data-source for single-tenant on-premise systems using Connector Catalogue backend service.

Prerequisites:

Admin app role ASOLEU-CONCATAPP-AP-.Admin or TenantAdmin platform role

ConnectorCatalogue API base URL: https://{hostname}/api/asol/cc

Get available providers in connector catalogue
GET /api/v1/Providers

offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)

request body properties:
- providerId - (mandatory) the GUID identifier of provider in connector catalogue
- enabled - the flag if connector is enabled or disabled
sample request body:

{
  "providerId": "5e6203ab-2422-4aba-b65b-d1a33d5aab32",
  "enabled": true
}

Note: Connector must be released and enabled to be ready. Use Release and Enable actions if necessary using application or API.

allowUpdate - (optional) flag if update of existing definition is allowed or not
request body properties:
- connectorId - (mandatory) the GUID identifier of connector in connector catalogue
- integrationTokenClientId - (optional) the clientId of existing integration token, otherwise the clientId is autogenerated
- name - (mandatory) the human readable name of agent, the unique agentCode is autogenerated
- enabled - the flag if agent is enabled or disabled
sample request body:

{
  "connectorId": "680e7f17-dd36-402e-aa2b-7edf4c6c3c2b",
  "integrationTokenClientId": null,
  "name": "Demo",
  "enabled": true
}

Note: Agent must be released and enabled to be ready. Use Release and Enable actions if necessary using application or API.

Connector registration for multi-tenant cloud services​

Register integration-agent using REST API​

V2.1 IntegrationAgents API endpoints for multi-instance integration agents - New​

List endpoint​

Settings endpoints​

OnPremiseSettings endpoints​

Transformations endpoints​

ConfigureConsumer endpoint​

Statuses endpoints​

SupportedFeatures endpoints​

V2 IntegrationAgents API endpoints for data integration - Preferred​

Settings endpoints​

Transformations endpoints​

ConfigureConsumer endpoint​

Statuses endpoints​

SupportedFeatures endpoints​

V1 DataAgents and DataSources API endpoints for data integration - Obsolete​

Register MessageGateway consumer for data-agent using REST API​

Data-agent metadata events​

ASOL.DataService.RefreshSourceStatus​

ASOL.DataService.RefreshSourceConfig​

Migration between message broker and message gateway​

Upgrade from Message Broker to Message Gateway​

Revert to Message Broker from Message Gateway​

Connector registration for single-tenant on-premise systems​

Choose and configure connector​

Register and configure data-agent​

Generate secrets for data-agent​

Register data-agent using REST API​

Connector registration for multi-tenant cloud services

Register integration-agent using REST API

V2.1 IntegrationAgents API endpoints for multi-instance integration agents - New

List endpoint

Settings endpoints

OnPremiseSettings endpoints

Transformations endpoints

ConfigureConsumer endpoint

Statuses endpoints

SupportedFeatures endpoints

V2 IntegrationAgents API endpoints for data integration - Preferred

Settings endpoints

Transformations endpoints

ConfigureConsumer endpoint

Statuses endpoints

SupportedFeatures endpoints

V1 DataAgents and DataSources API endpoints for data integration - Obsolete

Register MessageGateway consumer for data-agent using REST API

Data-agent metadata events

ASOL.DataService.RefreshSourceStatus

ASOL.DataService.RefreshSourceConfig

Migration between message broker and message gateway

Upgrade from Message Broker to Message Gateway

Revert to Message Broker from Message Gateway

Connector registration for single-tenant on-premise systems

Choose and configure connector

Register and configure data-agent

Generate secrets for data-agent

Register data-agent using REST API