Consume data

Overview

The consumer can read data from virtual datastores. Data are organized by integration datamodels which are referenced by association relationships (see LookupEntity field type). Each data-record is identified by internal identifier (i.e. recordId) provided by DataService and by external identifier (i.e. externalId) provided by publisher. The externalId represents the fully qualified identifier able to get original record in application which data-record published. The consumer can use several GET methods to obtain data, see QueryingData API endpoints. The data are always returned sorted by modifiedOn property in descending order (i.e. the latest changes first).

Consume data by integration-agent using REST API

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

V2 QueryingData 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 can be used by both: the multi-tenant and single-tenant integration agents.

Get a collection of data-records in descendant order sorted by modification datetime
/api/v2/QueryingData/GetData

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context

Get a collection of data-records which are referenced by the foreign key (i.e. property of LookupEntity datatype)
/api/v2/QueryingData/GetData/ReferencedByFK

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context
fkName - (mandatory) the name of property representing foreign key
akValue - (mandatory) the value of foreign key (i.e. recordId of referenced data-record)

Get a collection of data-records which are referenced by the alternate key (i.e. property of Text datatype)
/api/v2/QueryingData/GetData/FilteredByAK

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context
akName - (mandatory) the name of property representing alternate or natural key
akValue - (mandatory) the value of alternate or natural key (note: the equals condition is used to filter data)

Get a collection of data-records provided by processed data-results
/api/v2/QueryingData/GetData/{resultId}

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context
resultId - (mandatory) the identifier of processed data-result (i.e. processed queue-item identifier)

Get a single data-record provided by processed data-results and item identifier
/api/v2/QueryingData/GetData/{resultId}/{itemId}

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context
resultId - (mandatory) the identifier of processed data-result (i.e. processed queue-item identifier)
itemId - (mandatory) the identifier of data-result item

Get a collection of processed data-results (i.e. successfully processed queue-items)
/api/v2/QueryingData/ProcessedDataResults/{resultId}

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context
resultId - (mandatory) the identifier of processed data-result (i.e. processed queue-item identifier)

Get a collection of processed data-result items (i.e. results of successfully processed queue-item)
/api/v2/QueryingData/ProcessedDataResults/{resultId}/Items

sourceId - (optional) the identifier of data-source (e.g. DataSourceId/SourceId of data-integration agent)
modelId - the data-model identifier of data-records
mandantCode - the identifier of organization representing mandant in given tenant context filters data records by mandant context
resultId - (mandatory) the identifier of processed data-result (i.e. processed queue-item identifier)
itemId - (mandatory) the identifier of data-result item

Additional query parameters

offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
includeDeleted - flag to include data marked as deleted (note: deleted data are available for limited time only after their deletion)
recordId - (guid) the internal data-record identifier
externalId - fully qualified identifier of data record provider by publisher filters data records to single data record or empty collection
referenceId - (guid) the reference identifier of original record from primary data-source, it can return multiple data records when data are synchronized across multiple data-sources
publisherSourceId - (optional) the identifier of publisher data-source (it filters data records to specific publisher), used in "legacy mode" only and forbidden in "integration profile" mode
selfSourceOnly - the flag to apply self-source filter, the source bypass is used for testing purposes in "integration profile" mode
scenarioId - the integration-scenario identifier used in "integration profile" mode
featureId - the integration-feature identifier used in "integration profile" mode
modifiedFrom + modifiedTo - datetime range to filter data records by modification datetime
includeLookupProperties - comma separated list of properties (or navigation paths) to include (i.e. properties of LookupEntity datatype)
options - comma separated list of options to tune format of returned data (e.g. 'CN1')

Data-record system properties

id - (mandatory) the internal identifier of data-record
- modelId - (mandatory) the data-model identifier (Guid)
- recordId - (mandatory) the data-record identifier (Guid)
externalId - the external identifier of data-record provided by publisher ('<recordId>.<entityId>.<sourceId>')
sourceId - (guid) the identifier of publisher data-source
referenceId - (guid) the reference identifier of original record from primary data-source
mandantCode - the mandant identifier (i.e. the code of organization representing mandant in given tenant context) or null for non-mandant data
utcModifiedOn - the datetime of last modification
deleted - (optional) flag that the data-record was recently deleted

Sample response of collection result (shortened):

{
  "totalCount": 145,
  "items": [
    {
      "Id": {
        "ModelId": "ad7b68b7-90e2-4de4-81f6-18fa325e5ee1",
        "RecordId": "0accec93-ff52-4cc4-85e7-35fa7ac50c17"
      },
      "ExternalId": "1.1519f11b-339a-4262-ac4f-77c33aba10a8.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "SourceId": "0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "ReferenceId": "bb114374-816d-47f3-a2bc-3f37d9796555",
      "MandantCode": "64949541|CZ",
      "UtcCreatedOn": "2022-05-26T14:45:53.685Z",
      "UtcModifiedOn": "2023-02-13T13:55:30.942Z",
      "Code": "01",
      "Name": {
        "values": [
          {
            "locale": "cs-CZ",
            "value": "Ekonomický ředitel"
          }
        ]
      }
    },
    ...
  ]
}

Sample response of single result:

{
  "Id": {
    "ModelId": "ad7b68b7-90e2-4de4-81f6-18fa325e5ee1",
    "RecordId": "cfd4885a-9c40-4462-8f19-2e2c1b9133c5"
  },
  "ExternalId": "2.1519f11b-339a-4262-ac4f-77c33aba10a8.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
  "SourceId": "0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
  "ReferenceId": "c442f35b-13a8-499d-8d43-048af757c764",
  "MandantCode": "64949541|CZ",
  "UtcCreatedOn": "2022-05-26T14:45:53.685Z",
  "UtcModifiedOn": "2023-02-13T13:55:30.942Z",
  "Code": "02",
  "Name": {
    "values": [
      {
        "locale": "cs-CZ",
        "value": "Personální ředitel"
      }
    ]
  }
}

V1 QueryingData API endpoints for data integration - Obsolete

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

Get a filtered collection of data records in descendant order sorted by modification datetime
GET /api/v1/QueryingData/FindDataByModelId/{modelId}

modelId - (mandatory) the data-model identifier

Get a filtered collection of data records which are referenced by the foreign key (i.e. property of LookupEntity datatype)
GET /api/v1/QueryingData/FindDataByModelId/{modelId}/ReferencedBy/{fkName}/{fkId}

modelId - (mandatory) the data-model identifier
fkName - (mandatory) the name of property representing foreign key
akValue - (mandatory) the value of foreign key (i.e. recordId of referenced data-record)

Get a filtered collection of data records which are referenced by the alternate key (i.e. property of Text datatype)
GET /api/v1/QueryingData/FindDataByModelId/{modelId}/FilteredBy/{akName}/{akValue}

modelId - (mandatory) the data-model identifier
akName - (mandatory) the name of property representing alternate or natural key
akValue - (mandatory) the value of alternate or natural key (note: the equals condition is used to filter data)

Get a single data record using primary key (i.e. Id.RecordId)
GET /api/v1/QueryingData/GetDataByModelId/{modelId}/{recordId}

modelId - (mandatory) the data-model identifier
recordId - (mandatory) the internal identifier of data-record (Guid)

Additional query parameters

offset + limit - the client paging parameters (default values: offset = 0 and limit = 100)
sourceId - the identifier of publisher data-source (it filters data records to specific publisher), used in "legacy mode" only and forbidden in "integration scenario" mode
selfSourceId - (mandatory) the identifier of consumer data-source, it identifies data-source which is querying data
selfSourceOnly - the flag to apply self-source filter, the source bypass is used for testing purposes in "integration scenario" mode
includeDeleted - flag to include data marked as deleted (note: deleted data are available for limited time only after their deletion)
mandantCode - identifier of organization representing mandant in given tenant context filters data records by mandant context
externalId - fully qualified identifier of data record provider by publisher filters data records to single data record or empty collection
referenceId - (guid) the reference identifier of original record from primary data-source, it can return multiple data records when data are synchronized across multiple data-sources
modifiedFrom + modifiedTo - datetime range to filter data records by modification datetime
includeLookupProperties - comma separated list of properties (or navigation paths) to include (i.e. properties of LookupEntity datatype)
options - comma separated list of options to tune format of returned data (e.g. 'CN1')

Data-record system properties

id - (mandatory) the internal identifier of data-record
- modelId - (mandatory) the data-model identifier (Guid)
- recordId - (mandatory) the data-record identifier (Guid)
externalId - the external identifier of data-record provided by publisher ('<recordId>.<entityId>.<sourceId>')
sourceId - (guid) the identifier of publisher data-source
referenceId - (guid) the reference identifier of original record from primary data-source
mandantCode - the mandant identifier (i.e. the code of organization representing mandant in given tenant context) or null for non-mandant data
utcModifiedOn - the datetime of last modification
deleted - (optional) flag that the data-record was recently deleted

Sample response of collection result (shortened):

{
  "totalCount": 145,
  "items": [
    {
      "Id": {
        "ModelId": "ad7b68b7-90e2-4de4-81f6-18fa325e5ee1",
        "RecordId": "0accec93-ff52-4cc4-85e7-35fa7ac50c17"
      },
      "ExternalId": "1.1519f11b-339a-4262-ac4f-77c33aba10a8.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "SourceId": "0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "ReferenceId": "bb114374-816d-47f3-a2bc-3f37d9796555",
      "MandantCode": "64949541|CZ",
      "UtcCreatedOn": "2022-05-26T14:45:53.685Z",
      "UtcModifiedOn": "2023-02-13T13:55:30.942Z",
      "Code": "01",
      "Name": {
        "values": [
          {
            "locale": "cs-CZ",
            "value": "Ekonomický ředitel"
          }
        ]
      }
    },
    ...
  ]
}

Sample response of single result:

{
  "Id": {
    "ModelId": "ad7b68b7-90e2-4de4-81f6-18fa325e5ee1",
    "RecordId": "cfd4885a-9c40-4462-8f19-2e2c1b9133c5"
  },
  "ExternalId": "2.1519f11b-339a-4262-ac4f-77c33aba10a8.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
  "SourceId": "0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
  "ReferenceId": "c442f35b-13a8-499d-8d43-048af757c764",
  "MandantCode": "64949541|CZ",
  "UtcCreatedOn": "2022-05-26T14:45:53.685Z",
  "UtcModifiedOn": "2023-02-13T13:55:30.942Z",
  "Code": "02",
  "Name": {
    "values": [
      {
        "locale": "cs-CZ",
        "value": "Personální ředitel"
      }
    ]
  }
}

Features

Include feature

You can use Include feature to get data-records decorated with included referenced data-records by a single REST API call. By default the properties marked with IsPublished flag are included automatically and you don't need to use include feature to get them. The query parameter includeLookupProperties can contain comma separated list of LookupEntity properties or whole navigation paths. Let's see the examples:

'LegalForm' ... organization with legal form
'LegalForm,Addresses.Type' ... organization with legal form and addresses with address type descriptions
'EmploymentType,Employee.Contacts.Type' ... employment with employment type description and employee detail with contacts with contact type descriptions
The result of referenced data-record contains included flag to determine if data-record was succesfully included:
true - when requested and succesfully included
false - requested, but not included due some problem, you can try to get single data-record to determine the reason of failure
null - included wasn't requested (default)

Deleted feature

You can use Deleted feature to get data-records recently deleted, e.g. to get alternate or natural keys or other properties to synchronize your data after DataRecordDeleted event. The query parameter includeDeleted disables filter to get non-deleted data only which is the default behavior. The returned data-records which are marked as deleted are decorated with deleted flag.

Options feature

You can use Options feature to tune a format of returned data. By default the simplified format is used. For example you can choose between string representation or typed contracts, see CurrencyNumber datatype. Options:

CC1 or cc1 = use camelCase formatter v1 (by default the data-model codes of properties in PascalCase format are used)
CN1 or cn1 = use CurrencyNumber contract v1 (by default the string representation of currency number is used)

More examples

Example 1: Get organizations

GET https://{platform-hostname}/api/asol/ds/api/v1/QueryingData/FindDataByModelId/b6530960-bb27-4980-b1bf-80ba28e78e0e?MandantCode=64949541|CZ

response (shortened):

{
  "items": [
    {
      "Id": {
        "ModelId": "b6530960-bb27-4980-b1bf-80ba28e78e0e",
        "RecordId": "9da0f816-8ed1-452b-98a2-575becc39ef3"
      },
      "ExternalId": "62.1ab4b321-c9dd-4c2b-8ddb-58e799f37205.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "SourceId": "0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "ReferenceId": "c442f35b-13a8-499d-8d43-048af757c764",
      "MandantCode": "64949541|CZ",
      "UtcCreatedOn": "2023-02-13T13:50:22.916Z",
      "UtcModifiedOn": "2023-02-27T13:27:34.209Z",
      "Code": "12345678|CZ",
      "IdentificationNumber": "12345678",
      "CountryCode": "CZ",
      "Name": "Odběratel 4",
      "TaxId": null,
      "VatIn": null,
      "Addresses": [
        {
          "Line1": "Slanečková 1061/9"
          "StreetName": "Slanečková",
          "HouseNumber": "9",
          "RegistryNumber": "1061",
          "City": "Praha 8",
          "PostalCode": "18600",
          "Type": {
            "Id": {
              "ModelId": "dd232be6-489d-49b5-8d90-ff245a4de93d",
              "RecordId": "aae86714-b3fb-409c-a91c-28a0a41f2d3c"
            },
            "ExternalId": "Main.AddressType.00000000-0000-0000-0000-000000000000",
            "SourceId": "00000000-0000-0000-0000-000000000000",
            "MandantCode": null,
            "Code": "Main"
          }
        }
      ],
      "Contacts": [
        {
          "SysIndexKey": "0",
          "ReferenceId": "537d6fef-3df8-4989-b48c-9ad2af325971",
          "Value": "+420123456789",
          "Type": {
            "Id": {
              "ModelId": "79d701ae-0463-4fd0-8430-009ce3b879dc",
              "RecordId": "5a35c01e-3446-41b2-8f1f-ce6a2616ffb4"
            },
            "ExternalId": "CellPhone.ContactType.00000000-0000-0000-0000-000000000000",
            "SourceId": "00000000-0000-0000-0000-000000000000",
            "MandantCode": null,
            "Code": "CellPhone",
            "ValueType": "PhoneNumber"
          }
        },
        {
          "SysIndexKey": "1",
          "ReferenceId": "2bf9588f-b9d4-4f79-8828-6fc01fa16906",
          "Value": "+420987654321",
          "Type": {
            "Id": {
              "ModelId": "79d701ae-0463-4fd0-8430-009ce3b879dc",
              "RecordId": "0e06d900-b2e7-4bcf-b11e-f2f67085d8a2"
            },
            "ExternalId": "MobilePhone.ContactType.00000000-0000-0000-0000-000000000000",
            "SourceId": "00000000-0000-0000-0000-000000000000",
            "MandantCode": null,
            "Code": "MobilePhone",
            "ValueType": "PhoneNumber"
          }
        },
        {
          "SysIndexKey": "2",
          "ReferenceId": "0bae65ef-e876-481f-8ab0-8bf57d995467",
          "Value": "dummy@kontakt.cz",
          "Type": {
            "Id": {
              "ModelId": "79d701ae-0463-4fd0-8430-009ce3b879dc",
              "RecordId": "b84890ab-0c52-4d2b-a033-d9ef7a29c178"
            },
            "ExternalId": "PrimaryEmail.ContactType.00000000-0000-0000-0000-000000000000",
            "SourceId": "00000000-0000-0000-0000-000000000000",
            "MandantCode": null,
            "Code": "PrimaryEmail",
            "ValueType": "Email"
          }
        }
      ],
      "BankAccounts": [
        {
          "BBAN": "222 555 444",
          "IBAN": null,
          "SWIFT": "CEKOCZPP",
          "Type": {
            "Id": {
              "ModelId": "3b497bc3-c377-4171-af66-fe3edcb40c2a",
              "RecordId": "eb113cf5-fe9e-4483-ae4b-d96b581f2584"
            },
            "ExternalId": "Main.BankAccountType.00000000-0000-0000-0000-000000000000",
            "SourceId": "00000000-0000-0000-0000-000000000000",
            "MandantCode": null,
            "Code": "Main"
          }
        }
      ]
    },
    ...
  ]
}

Example 2: Get organizations and include their legal forms

GET https://{platform-hostname}/api/asol/ds/api/v1/QueryingData/FindDataByModelId/b6530960-bb27-4980-b1bf-80ba28e78e0e?MandantCode=64949541|CZ&IncludeLookupProperties=LegalForm

response (shortened):

{
  "items": [
    {
      "Id": {
        "ModelId": "b6530960-bb27-4980-b1bf-80ba28e78e0e",
        "RecordId": "07c8962c-453b-4129-a52a-35072b67bc94"
      },
      "ExternalId": "organization_fx|||1|||64949541|CZ.Organization.0994970c-47f1-41c1-b979-f1c47aa2bd57",
      "MandantCode": "64949541|CZ",
      "UtcCreatedOn": "2023-07-27T06:52:18.7Z",
      "UtcModifiedOn": "2023-07-27T07:56:05.925Z",
      "IdentificationNumber": "69797111",
      "CountryCode": "CZ",
      "Code": "69797111|CZ",
      "Name": "Úřad pro zastupování státu CZ",
      "LegalForm": {
        "Included": true,
        "Id": {
          "ModelId": "6a763172-3b82-4074-8ee6-0bfa86f15e50",
          "RecordId": "d2e78254-e83c-4166-a500-b7b459c1b612"
        },
        "ExternalId": "123456.LegalFormType.0994970c-47f1-41c1-b979-f1c47aa2bd57",
        "MandantCode": "64949541|CZ",
        "UtcCreatedOn": "2023-06-29T08:42:49.77Z",
        "UtcModifiedOn": "2023-06-29T08:42:49.77Z",
        "Code": "960|CZ",
        "Name": {
          "values": [
            {
              "locale": "cs-CZ",
              "value": "Právnická osoba zřízená zvláštním zákonem"
            }
          ]
        },
        "Description": null
      },
      "DateOfFoundation": "2023-07-26T00:00:00Z",
      "TaxId": "0",
      "VatIn": "69797111",
      "Addresses": [
        {
          "SysIndexKey": "0",
          "StreetName": "Hlavní",
          "HouseNumber": "0 ",
          "RegistryNumber": "13",
          "City": "Praha",
          "PostalCode": "11000",
          "CountryCode": "CZ",
          "Type": {
            "Id": {
              "ModelId": "dd232be6-489d-49b5-8d90-ff245a4de93d",
              "RecordId": "aae86714-b3fb-409c-a91c-28a0a41f2d3c"
            },
            "ExternalId": "Main.AddressType.00000000-0000-0000-0000-000000000000",
            "MandantCode": null,
            "Code": "Main"
          }
        }
      ]
    },
    ...
  ]
}

Example 3: Get organization units of specified organization

GET https://{platform-hostname}/api/asol/ds/api/v1/QueryingData/FindDataByModelId/fbd72d37-fa38-4174-987e-f70729f585e2/ReferencedBy/Organization/4c7e615c-fc70-495b-a4fb-e44444d8a7dd?MandantCode=64949541|CZ

response (shortened):

{
  "items": [
    {
      "Id": {
        "ModelId": "fbd72d37-fa38-4174-987e-f70729f585e2",
        "RecordId": "2d8e3806-3c0d-45d4-b250-c28786fdf690"
      },
      "ExternalId": "3.0af6a6a4-2dc3-4e72-9de0-d556cc4cda43.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
      "MandantCode": "64949541|CZ",
      "UtcCreatedOn": "2022-05-26T14:45:26.144Z",
      "UtcModifiedOn": "2023-02-27T13:28:07.59Z",
      "Code": "100",
      "Name": "Kovovýroba",
      "Type": {
        "Id": {
          "ModelId": "86203b07-1d6b-4831-aca4-db052a26c5fd",
          "RecordId": "3bc503b0-467a-44cb-9c3b-6978971947a5"
        },
        "ExternalId": "Branch.OrganizationUnitType.00000000-0000-0000-0000-000000000000",
        "MandantCode": null,
        "Code": "Branch"
      },
      "Organization": {
        "Id": {
          "ModelId": "b6530960-bb27-4980-b1bf-80ba28e78e0e",
          "RecordId": "4c7e615c-fc70-495b-a4fb-e44444d8a7dd"
        },
        "ExternalId": "1.1ab4b321-c9dd-4c2b-8ddb-58e799f37205.0eb2bab7-fe8c-4a13-be1f-2db877c4b455",
        "MandantCode": "64949541|CZ",
        "Code": "64949541|CZ",
        "IdentificationNumber": "64949541",
        "CountryCode": "CZ",
        "Name": "Asseco Solutions, a.s."
      }
    },
    ...
  ]
}

Example 4: Get employee attendance of specified employee

GET https://{platform-hostname}/api/asol/ds/api/v1/QueryingData/FindDataByModelId/570d4279-20b5-4d9b-a53f-b0c5e1b88790/ReferencedBy/Employee/5088a4ba-6ec3-4495-93af-4d746f431617?MandantCode=64949541|CZ

response (shortened):

{
  "items": [
    {
      "Id": {
        "ModelId": "570d4279-20b5-4d9b-a53f-b0c5e1b88790",
        "RecordId": "07adda8b-0b0d-4a27-a059-d02a58b64515"
      },
      "ExternalId": "123456.AttendanceExport.6a06af09-3d17-4bae-a9f4-37ebcaf7a873",
      "MandantCode": "64949541|CZ",
      "UtcCreatedOn": "2022-11-21T09:22:42.421Z",
      "UtcModifiedOn": "2022-11-22T14:33:01.09Z",
      "EmployeeCode": "10",
      "PayrollComponentCode": "11",
      "MonthCode": "2022-11",
      "Amount": 20.5,
      "AmountUnit": {
        "Id": {
          "ModelId": "13045ebc-57cf-4aee-974c-52b8cf56882b",
          "RecordId": "86a9c30b-d638-462b-9051-1e6942acd1d4"
        },
        "ExternalId": "Day.PayrollComponentUnit.00000000-0000-0000-0000-000000000000",
        "MandantCode": null,
        "Code": "Day"
      },
      "Employee": {
        "Id": {
          "ModelId": "f2511f7d-1a54-4a39-8e34-625c51397bbd",
          "RecordId": "5088a4ba-6ec3-4495-93af-4d746f431617"
        },
        "ExternalId": "146451.321.10f10185-eaeb-4b60-bc09-b4fca4d8c738",
        "MandantCode": "64949541|CZ",
        "EmployeeCode": "10",
        "FirstName": "Petr",
        "Surname": "Vomáčka",
      }
    },
    ...
  ]
}

QueryingData events

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

ASOL.DataService.RecordCreated, ASOL.DataService.RecordUpdated and ASOL.DataService.RecordDeleted

Messages notify about data changes in virtual datastore (optional notification for data consumer).

The appropriate data event is published when data-record was changed (i.e. created, updated or deleted).

Event definitions

messageType: ASOL.DataService.RecordCreated
- contractType: DataRecordCreatedEvent
- exchange: ASOL.DataService.Events:DataRecordCreatedEvent
- queueName: DS.Data
messageType: ASOL.DataService.RecordUpdated
- contractType: DataRecordUpdatedEvent
- exchange: ASOL.DataService.Events:DataRecordUpdatedEvent
- queueName: DS.Data
messageType: ASOL.DataService.RecordDeleted
- contractType: DataRecordDeletedEvent
- exchange: ASOL.DataService.Events:DataRecordDeletedEvent
- queueName: DS.Data

Event headers

X-DataSourceId - the data-source identifier of publisher
X-DataModelId - the data-model identifier
X-Tenant-Id - the tenant identifier of customer

Event classes

ASOL.DataService.Events.DataRecordCreatedEvent
ASOL.DataService.Events.DataRecordUpdatedEvent
ASOL.DataService.Events.DataRecordDeletedEvent

Event properties

dataModelId - the data-model identifier (Guid)
dataRecordId - the data-record identifier (Guid)
dataSourceId - the data-source identifier of publisher (Guid)
operationId - the identifier of virtual operation, see Operating log

ASOL.DataService.IntegrationDataChanged

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

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
mapId - the integration-map identifier (i.e. current integration profile when processed)
featureId - the integration-feature identifier (Guid)
scenarioId - the integration-scenario identifier (Guid)

Data types

Text and MultilineText

name	isCollection	isLocalized	description	runtime type (C#)
Text	✘	✘	single-line text	`string`
	json example: `"Name": "Hello World"`
	✔	✘	array of single-line texts	`IEnumerable<string>`
	json example: `"Names": [ "Hello", "World" ]`
	✘	✔	multilingual single-line text	`ASOL.Core.Localization.LocalizedValue<string>`
	json example: `"Name": { "values": [ { "locale": "en-US", "value": "Hello" }, { "locale": "cs-CZ", "value": "Ahoj" } ] }`
	✔	✔	array of multilingual single-line texts	`IEnumerable<ASOL.Core.Localization.LocalizedValue<string>>`
	json example: `"Names": [ { "values": [ { "locale": "en-US", "value": "Hello" }, { "locale": "cs-CZ", "value": "Ahoj" } ] }, { "values": [ { "locale": "en-US", "value": "World" }, { "locale": "cs-CZ", "value": "Svět" } ] } ]`
MultilineText	✘	✘	multi-line text	`string`
	json example: `"Description": "Hello\r\nWorld"`
	✔	✘	array of multi-line texts	`IEnumerable<string>`
	json example: `"Descriptions": [ "Good\r\nbye", "World" ]`
	✘	✔	multilingual multi-line text	`ASOL.Core.Localization.LocalizedValue<string>`
	json example: `"Description": { "values": [ { "locale": "en-US", "value": "Hell\r\no" }, { "locale": "cs-CZ", "value": "Aho\r\nj" } ] }`
	✔	✔	array of multilingual multi-line texts	`IEnumerable<ASOL.Core.Localization.LocalizedValue<string>>`
	json example: `"Descriptions": [ { "values": [ { "locale": "en-US", "value": "Good\r\nbye" }, { "locale": "cs-CZ", "value": "Nashle\r\ndanou" } ] }, { "values": [ { "locale": "en-US", "value": "World" }, { "locale": "cs-CZ", "value": "Svět" } ] } ]`

TwoOptions, WholeNumber, DecimalNumber and UniqueIdentifier

name	isCollection	description	runtime type (C#)
TwoOptions	✘	two-value switch	`bool`
	json example: `"Enabled": true`
	✔	array of two-value switches	`IEnumerable<bool>`
	json example: `"Flags": [ true, false, true ]`
WholeNumber	✘	whole number	`long`
	json example: `"Capacity": 15`
	✔	array of whole numbers	`IEnumerable<long>`
	json example: `"Dimensions": [ 25, 15, 60 ]`
DecimalNumber	✘	decimal number	`decimal`
	json example: `"Temperature": 37.5`
	✔	array of decimal numbers	`IEnumerable<decimal>`
	json example: `"Temperatures": [ 37.5, 38.6, 36.9 ]`
UniqueIdentifier	✘	unique identifier	`Guid`
	json example: `"StatusId": "fde0caea-301c-4f5b-b041-9e1459c71bc4"`
	✔	array of unique identifiers	`IEnumerable<Guid>`
	json example: `"StatusIds": [ "82c1f094-bcbe-4b0d-a01f-b9b3291c8c5b", "dcfcf976-8ad3-4702-9790-08550361852c" ]`

Date and UtcDateTime

name	isCollection	description	runtime type (C#)
Date	✘	date without time	`DateTime`
	json example: `"ValidFrom": "2023-08-31T00:00:00Z"`
	✔	array of dates without time	`IEnumerable<DateTime>`
	json example: `"ActivationDates": [ "2023-08-01T00:00:00Z", "2023-08-31T00:00:00Z" ]`
UtcDateTime	✘	date and time in UTC	`DateTime`
	json example: `"FinishedOn": "2023-08-31T10:18:23Z"`
	✔	array of datetimes in UTC	`IEnumerable<DateTime>`
	json example: `"ActivationDateTimes": [ "2023-08-01T06:43:12Z", "2023-08-31T10:18:23Z" ]`

LookupEntity

name	isCollection	description	runtime type (C#)
LookupEntity	✘	reference to data record (i.e. association relationship to aggregate-root entity)	base contract: `ASOL.DataService.Contracts.Queries.DataServiceQueryExtendedResult`
	json example: `"LegalForm": { "Id": { "ModelId": "6a763172-3b82-4074-8ee6-0bfa86f15e50", "RecordId": "d2e78254-e83c-4166-a500-b7b459c1b612" }, "ExternalId": "112\|CZ.LegalFormType.0984970c-47f1-41c1-b979-f1c47aa2bd57", "MandantCode": "64949541\|CZ", "Code": "112\|CZ" }`
	✔	array of references to data records	`IEnumerable<T> where T : ASOL.DataService.Contracts.Queries.DataServiceQueryExtendedResult`
	json example: `"AddressTypes": [ { "Id": { "ModelId": "dd232be6-489d-49b5-8d90-ff245a4de93d", "RecordId": "a944b5a7-88c0-49db-8de5-c98f5a417964" }, "ExternalId": "Permanent.AddressType.00000000-0000-0000-0000-000000000000", "MandantCode": null, "Code": "Permanent" }, { "Id": { "ModelId": "dd232be6-489d-49b5-8d90-ff245a4de93d", "RecordId": "d135ed6d-5767-419f-8741-d8c2faf46e16" }, "ExternalId": "Temporary.AddressType.00000000-0000-0000-0000-000000000000", "MandantCode": null, "Code": "Temporary" } ]`

LookupEntity system properties

id - (mandatory) the internal identifier of data-record
- modelId - (mandatory) the data-model identifier (Guid)
- recordId - (mandatory) the data-record identifier (Guid)
externalId - the external identifier of data-record provided by publisher (<recordId>.<entityId>.<sourceId>)
mandantCode - the mandant identifier (i.e. the code of organization representing mandant in given tenant context) or null for non-mandant data
included - (optional) flag that the data-record was included or not included for some reason

NestedEntity

name	isCollection	description	runtime type (C#)
NestedEntity	✘	nested entity structure	base contract: `ASOL.DataService.Contracts.Queries.DataServiceNestedQueryResult`
	json example: `"BankAccount": { "BBAN": "2130000123", "IBAN": "CZ0607100000002130000123", "SWIFT": "CNBACZPP", "Type": { "Id": { "ModelId": "3b497bc3-c377-4171-af66-fe3edcb40c2a", "RecordId": "eb113cf5-fe9e-4483-ae4b-d96b581f2584" }, "ExternalId": "Main.BankAccountType.00000000-0000-0000-0000-000000000000", "MandantCode": null, "Code": "Main" } }`
	✔	array of nested entity structures	`IEnumerable<T> where T : ASOL.DataService.Contracts.Queries.DataServiceNestedQueryResult`
	json example: "Contacts": [ { "SysIndexKey": "0", "Value": null, "Type": { "Id": { "ModelId": "79d701ae-0463-4fd0-8430-009ce3b879dc", "RecordId": "5a35c01e-3446-41b2-8f1f-ce6a2616ffb4" }, "ExternalId": "CellPhone.ContactType.00000000-0000-0000-0000-000000000000", "MandantCode": null, "Code": "CellPhone", "ValueType": "PhoneNumber" } }, { "SysIndexKey": "1", "Value": "recepce@company.cz", "Type": { "Id": { "ModelId": "79d701ae-0463-4fd0-8430-009ce3b879dc", "RecordId": "b84890ab-0c52-4d2b-a033-d9ef7a29c178" }, "ExternalId": "PrimaryEmail.ContactType.00000000-0000-0000-0000-000000000000", "MandantCode": null, "Code": "PrimaryEmail", "ValueType": "Email" } } ]

NestedEntity system properties

sysIndexKey - the internal identifier of nested query-item (used to identify item in collection when externalId isn't used)
externalId - the external identifier of nested query-item (<recordId>.<entityId>.<sourceId>)

CurrencyNumber

name	isCollection	description	runtime type (C#)
CurrencyNumber	✘	currency number (decimal value with currency code of ISO 4217 - alphabetic)	`ASOL.DataService.Edge.Contracts.DataTypes.CurrencyNumber`
	json example: default: `"Total": "2833.2\|CZK"` options 'CN1': `"Total": { "_type": "CurrencyNumber", "value": 2833.2, "currencyCode": "CZK" }`
	✔	array of currency numbers	`IEnumerable<ASOL.DataService.Edge.Contracts.DataTypes.CurrencyNumber>`
	json example: default: `"Payments": [ "121\|EUR", "491.72\|CZK" ]` options 'CN1': `"Payments": [ { "_type": "CurrencyNumber", "value": 121, "currencyCode": "EUR" }, { "_type": "CurrencyNumber", "value": 491.72, "currencyCode": "CZK" } ]`

CurrencyNumber properties

value - (mandatory) the decimal value representing amount of money
currencyCode - (mandatory) the currency code (ISO 4217 - alphabetic)

FileReference

Note: Use the file reference to build URI to get a file content from Content Manager service,

e.g. https://{platform-hostname}/api/asol/cnt/api/v1/Files/{fileId}?accessLevel={accessLevel}

or https://{platform-hostname}/api/asol/cnt/api/v1/Files/Path/{filePath}?accessLevel={accessLevel}.

name	isCollection	description	runtime type (C#)
FileReference	✘	structured contract representing a reference to the file stored in Content Manager service	`ASOL.DataService.Edge.Contracts.DataTypes.FileReference`
	json example: `"Document": { "_type": "FileReference", "source": { "accessLevel": "Private", "fileId": "90ac37d8-302e-3c87-b2e4-720e5de005ec", "filePath": "asol/bk2004_123pr1.pdf", "folderId": "c6f12dba-9ffe-4a7b-bf84-f1753ff1e5b4" }, "fileName": "Doklad_1.pdf", "description": "doklad 1", "referenceId": "a6665a67-2d6e-45a2-9423-4117643c8564" }`
	✔	array of references to the files	`IEnumerable<ASOL.DataService.Edge.Contracts.DataTypes.FileReference>`
	json example: `"Documents": [ { "_type": "FileReference", "source": { "accessLevel": "Private", "fileId": "90ac37d8-302e-3c87-b2e4-720e5de005ec" } }, { "_type": "FileReference", "source": { "accessLevel": "Public", "filePath": "pub/eureka.png" } } ]`

FileReference properties

source - the source of file (i.e. file identifier to a file stored in the Content Manager)
- accessLevel - (mandatory) the data-access level (Private = tenant data / Public = shared data)
- fileId / filePath - (mandatory) the file identifier(s), the file can be identified by id or by path or both
- folderId - (optional) the source folder identifier
fileName - (optional) the preferred file name
description - (optional) the file description
referenceId - (guid) the reference identifier of original record from primary data-source

Custom Properties

Querying Data-response (shortened) with custom properties:

{
  "Id": {
    "ModelId": "1abd1bb5-af01-48ed-b91f-f94699a928f6",
    "RecordId": "d6149a9c-5b35-4cbf-afa0-fd53384da473"
  },
  "ExternalId": "myExternalId01",
  "MandantCode": "64949541|CZ",
  "UtcCreatedOn": "2022-05-26T14:45:26.144Z",
  "UtcModifiedOn": "2023-02-27T13:28:07.59Z",
  "MyProperty": "myValue",
  "Custom": {
    "MyCustomProperty": "myCustomValue",
  }
}

To extend your contract with custom properties, you can use the IDataServiceQueryCustomResult interface.

namespace ASOL.DataService.Contracts.Queries;

public interface IDataServiceQueryCustomResult<T>
{
    public T? Custom { get; set; }
}

public interface IDataServiceQueryCustomResult : IDataServiceQueryCustomResult<IDictionary<string, object?>>;

Example of contract implementation:

public class MyQueryExtendedResult : DataServiceQueryExtendedResult, IDataServiceQueryCustomResult<MyQueryCustomResult>
{
    public string? MyProperty { get; set; }
    public MyQueryCustomResult? Custom { get; set; }
}

public class MyQueryCustomResult
{
    public string? MyCustomProperty { get; set; }
}

Overview​

Consume data by integration-agent using REST API​

V2 QueryingData API endpoints for data integration - Preferred​

V1 QueryingData API endpoints for data integration - Obsolete​

Features​

Include feature​

Deleted feature​

Options feature​

More examples​

Example 1: Get organizations​

Example 2: Get organizations and include their legal forms​

Example 3: Get organization units of specified organization​

Example 4: Get employee attendance of specified employee​

QueryingData events​

ASOL.DataService.RecordCreated, ASOL.DataService.RecordUpdated and ASOL.DataService.RecordDeleted​

ASOL.DataService.IntegrationDataChanged​

Data types​

Text and MultilineText​

TwoOptions, WholeNumber, DecimalNumber and UniqueIdentifier​

Date and UtcDateTime​

LookupEntity​

NestedEntity​

CurrencyNumber​

FileReference​

Custom Properties​

Overview

Consume data by integration-agent using REST API

V2 QueryingData API endpoints for data integration - Preferred

V1 QueryingData API endpoints for data integration - Obsolete

Features

Include feature

Deleted feature

Options feature

More examples

Example 1: Get organizations

Example 2: Get organizations and include their legal forms

Example 3: Get organization units of specified organization

Example 4: Get employee attendance of specified employee

QueryingData events

ASOL.DataService.RecordCreated, ASOL.DataService.RecordUpdated and ASOL.DataService.RecordDeleted

ASOL.DataService.IntegrationDataChanged

Data types

Text and MultilineText

TwoOptions, WholeNumber, DecimalNumber and UniqueIdentifier

Date and UtcDateTime

LookupEntity

NestedEntity

CurrencyNumber

FileReference

Custom Properties