Skip to main content

Integration profiles

Overview​

The integration profile provides automated mechanism to configure integrated data-agent/data-source providers based on customer's business processes. The integration definitions (like scenarios and features) provide integration metadata for business processes. The integrated applications provide their integration capabilities. The most important is customer who provides user consent with data manipulation when buing application or managing subscriptions. The customer decides which business processes are enabled/disabled among bought applications.

Integration definitions​

  • Integration map - unified collection of business areas containing related integration scenarios and assigned activation keys
  • Integration scenario - definition of elementary business scenario (i.e. representing data usage), each scenario has single input feature (or none) and single output feature (or none)
  • Integration feature - definition of elementary business feature (i.e. representing data structure and behavior), each feature provides access to list of data-models and can be composed from included features
  • Integrated application - definition of integrated application obtained from PDM, each application contain list of supported features and their usage (i.e. integration capabilities)

Integration profile​

  • Integration request - represents customer's request to change integration profile, e.g. to activate or deactivate integrated applications or integration scenarios
  • Integration profile - represents effective settings for all applications activated in tenant context (i.e. for given customer)

See also: Registration and configuration of MessageGateway consumer

Integration profile API endpoints​

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

Current integration profile​

1. Get a filtered collection of active items in the current integration-profile​

GET /api/v2/IntegrationProfiles/Current

  • sourceId - the data-source identifier (i.e. filter to specific data-source)
  • sample response (shortened):
{
  "isSelected": true,
  "items": [
    {
      "dataSourceId": "0eb2bab6-fe8b-4a13-be1e-2db877c4b455",
      "applicationId": "db3a0729-2ca3-451a-b0db-93068bc664a4",
      "application": {
        "id": "db3a0729-2ca3-451a-b0db-93068bc664a4",
        "code": "ASOLEU-HeliosInuvio-AP-",
        "name": {
          "values": [
            {
              "locale": "en-US",
              "value": "Helios iNuvio"
            }
          ]
        }
      },
      "featureId": "d3e49a3e-d7e8-41ea-a8d6-d9bbc0176023",
      "feature": {
        "id": "d3e49a3e-d7e8-41ea-a8d6-d9bbc0176023",
        "code": "EmployeeAttendances",
        "name": {
          "values": [
            {
              "locale": "en-US",
              "value": "Employee attendances"
            }
          ]
        }
      },
      "applicationUsage": "Input",
      "inputModelIds": [
        "570d4279-20b5-4d9b-a53f-b0c5e1b88790",
        "af804776-e3a4-4f32-ab40-33b57f129978",
        ...
      ]
    },
    ...
  ],
  "id": "f4eb6e58-cb8d-40fe-8cf1-d56b2e3234f7",
  "released": true,
  "deleted": false
}

2. Get a filtered collection of active features and their usage in the current integration-profile​

GET /api/v2/IntegrationProfiles/Current/AvailableFeatures

  • sourceId - the data-source identifier (i.e. filter to specific data-source)
  • sample response (shortened):
{
  "totalCount": 2,
  "items": [
    {
      "id": "d3e49a3e-d7e8-41ea-a8d6-d9bbc0176023",
      "code": "EmployeeAttendances",
      "usage": "Input",
      "inputSourceIds": [
        "d1b7d9b1-b8b7-4b06-828a-0a7f617a7e12"
      ],
      "inputModelIds": [
        "570d4279-20b5-4d9b-a53f-b0c5e1b88790",
        ...
      ]
    },
    {
      "id": "e65fed2f-509d-4ae8-a8b1-86578d71d8ad",
      "code": "EmploymentsWithPayrollComponents",
      "usage": "Output",
      "outputModelIds": [
        "af804776-e3a4-4f32-ab40-33b57f129978",
        ...
      ]
    }
  ]
}

3. Get a filtered collection of active data-models in the current integration-profile​

GET /api/v2/IntegrationProfiles/Current/AvailableModels

  • sourceId - the data-source identifier (i.e. filter to specific data-source)
  • sample response (shortened):
{
  "totalCount": 20,
  "items": [
    {
      "id": "570d4279-20b5-4d9b-a53f-b0c5e1b88790",
      "code": "EmployeeAttendance",
      "usage": "Input",
      "inputSourceIds": [
        "d1b7d9b1-b8b7-4b06-828a-0a7f617a7e12"
      ]
    },
    {
      "id": "af804776-e3a4-4f32-ab40-33b57f129978",
      "code": "PayrollComponent",
      "usage": "Output"
    },
    ...
  ]
}

Publish data changes​

Publishing data in the context of integration profile is based on featureId and scenarioId parameters. See sourcing endpoints to send data to virtual datastores to understand basic principles.

Note: Each queue-item in the data-source input queue must be assigned to a single integration feature/scenario. Publisher must split and send data with respect to their assignment, see integration profile.

Consume data changes​

Consumimg data in the context of integration profile is based on featureId and scenarioId parameters. Consumer must read data with respect to their assignment, see integration profile. See querying endpoints to read data from virtual datastores to understand basic principles.

Note: Publisher data-sources are automatically filtered with respect to integration profile. You can use selfSourceId and selfSourceOnly for testing purposes to read data from virtual datastores published by your data-source.

1. Get a filtered collection of data-changes results sorted by creation datetime in descending order​

GET /api/v1/QueryingData/ProcessedDataResults

  • sourceId - the publisher data-source identifier
  • operationId - the identifier of virtual operation
  • scenarioId - the identifier of integration scenario
  • profileId - the identifier of integration profile
  • featureId - the identifier of integration feature
  • offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
  • createdFrom + createdTo - datetime range to filter data results by creation datetime
  • sample response (shortened):
{
  "totalCount": 126,
  "items": [
    {
      "id": "fdc213c5-36ca-4b98-af21-9a62643d569d",
      "createdOn": "2024-01-25T08:15:19.279Z",
      "modifiedOn": "2024-01-25T08:15:20.411Z",
      "releasedOn": "2024-01-25T08:15:20.411Z",
      "sourceId": "aaef66df-377f-45fe-96e9-74372a17450c",
      "operationId": "1bdd0c21-0d69-4dc3-bfe6-835876925bb1"
      "profileId": "f4eb6e58-cb8d-40fe-8cf1-d56b2e3234f7",
      "scenarioId": "01517659-612d-4356-b96f-e68a547a8c8e",
      "featureId": "d3e49a3e-d7e8-41ea-a8d6-d9bbc0176023"
    },
    ...
  ]
}

Note: The identifier of data-changes result matches the identifier of publisher input-queue item.

2. Get a filtered collection of affected data-records (i.e. created, updated or deleted) in the data-changes result​

GET /api/v1/QueryingData/ProcessedDataResults/{resultId}/Items

  • resultId - (mandatory) the identifier of data-changes result
  • sourceId - (optional) the consumer data-source identifier to filter items with respect to integration profile
  • useCurrentProfile - (optional) the flag to specify if current or original integration profile will be used (true = current, false = original)
  • offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
  • sample response:
{
  "totalCount": 1,
  "items": [
    {
      "id": "aa9b9dbd-69ec-48a7-8971-c78b47dc9032",
      "resultId": "fdc213c5-36ca-4b98-af21-9a62643d569d",
      "changeType": "Created",
      "modelId": "42f5b47b-a31e-4ee1-9e61-7143ba0fca4b",
      "recordId": "36bd19c0-0475-4bcf-ba89-db5ce2f1266e",
      "externalId": "4e0ca8b7-8367-46e9-a6bf-17f91ef393dd.BankPaymentAck.aaef66df-377f-45fe-96e9-74372a17450b",
      "referenceId": "f4b9722d-7f37-42c6-838e-3e1f47bfedcb",
      "mandantCode": "64949541|CZ"
    }
  ]
}

Note: This endpoint provides system properties (i.e. metadata) of the affected data-records only, not the data-records itself.

Integration profile events​

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

Flow for changing profile​

Messages for notification that changes of integration-profile started / completed (i.e. notifications for data consumer and publisher).

ASOL.DataService.IntegrationProfileChangeStarted​

Event definitions

  • messageType: ASOL.DataService.IntegrationProfileChangeStarted
    • contractType: IntegrationProfileChangeStarted
    • exchange: ASOL.DataService.Edge.Contracts.Events:IntegrationProfileChangeStarted
    • queueName: ``

Event headers

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

Event classes

  • ASOL.DataService.Edge.Contracts.Events.IntegrationProfileChangeStarted

Event properties

  • sourceId - the data-source identifier
  • requestId - the integration-request identifier
  • currentProfileId - the currently active integration-profile
  • targetProfileId - the integration-profile which will be applied

Description: The change of integration-profile was started and will be applied in short time, data-source should pause running operations like publish/consume data as soon as possible (i.e. keep data consistent) and wait until the new integration-profile will be applied.

ASOL.DataService.IntegrationProfileChangeCompleted​

Event definitions

  • messageType: ASOL.DataService.IntegrationProfileChangeCompleted
    • contractType: IntegrationProfileChangeCompleted
    • exchange: ASOL.DataService.Edge.Contracts.Events:IntegrationProfileChangeCompleted
    • queueName: ``

Event headers

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

Event classes

  • ASOL.DataService.Edge.Contracts.Events.IntegrationProfileChangeCompleted

Event properties

  • sourceId - the data-source identifier
  • requestId - the integration-request identifier
  • requestStatus - the final status of integration-request (Success, Failed, Canceled)
  • currentProfileId - the currently active integration-profile
  • wasSuccess - true when requested operation was succesfull otherwise false

Description: The change of integration-profile was completed, data-source should check final status and reconfigure, then can continue with operations like publish/consume data with respect the new integration-profile.

Note: The started/completed notifications are paired (even in case of failure), so check the final status or wasSuccess flag. Reconfigure when success or continue without reconfiguration when not. The only affected data-sources are notified.

Flow for data changes​

Message for notification that data-changes was processed in the scope of data-integration profile (i.e. notification for data consumer).

ASOL.DataService.IntegrationDataChanged​

Event definitions

  • messageType: ASOL.DataService.IntegrationDataChanged
    • contractType: IntegrationDataChanged
    • exchange: ASOL.DataService.Events:IntegrationDataChanged
    • queueName: ``

Event headers

  • X-SourceId - the data-source identifier of publisher
  • X-FeatureId - the integration-feature identifier
  • X-ScenarioId - the integration-scenario identifier
  • X-Tenant-Id - the tenant identifier of customer

Event classes

  • ASOL.DataService.Events.IntegrationDataChanged

Event properties

  • sourceId - the data-source identifier of publisher (Guid)
  • resultId - the result identifier of published data changes (i.e. the queue-item identifier of publisher)
  • operationId - the identifier of virtual operation, see Operating log
  • profileId - the integration-profile identifier (i.e. the current integration profile when processed)
  • featureId - the integration-feature identifier (Guid)
  • scenarioId - the integration-scenario identifier (Guid)