Custom Repositories

  • How can I upload and process a custom XML file using COSMO Data Integration Framework?
  • How can I upload and process a custom JSON file using COSMO Data Integration Framework?
  • What is the process for pushing data from an external application to Business Central?
Tip

Summary: The article describes how to create and process Received Messages in the COSMO Data Integration Framework using the Partner Message Queue, a REST endpoint that allows users to upload custom XML or JSON repositories for processing. The process involves creating a message queue entry by providing basic information such as the type, sender, and mapping, followed by sending the repository data to create a partner received message and delete the message queue entry. The article also provides examples of how to use the Partner Message Queue for SaaS and OnPrem scenarios.

The Partner Message Queue is a REST endpoint used for uploading custom XML or JSON repositories to be processed by COSMO Data Integration Framework. This is achieved by creating Received Partner Messages through a two-step process:

  1. Create a message queue entry entry based on the repository type.
  2. Send the repository data to create a partner received message and delete the message queue entry.

Creating a Message Queue Entry

To create a message queue entry, you need to provide the following basic information: type, sender, and mapping.

Request
POST <bc-service-odata-url>/api/cosmoconsult/dataintegrationframework/v1.0/companies(<company-id>)/messages
Header: {
    "Content-Type": "application/json"
}
Body: {
    "sender": "<sender-code>",
    "mapping": "<(received-)mapping-code>",
    "type": "<repository-type>"
}

These are the possible types:

  • XmlRepository: Upload only XML file content as a mapping repository in the next step.
  • JsonRepository: Upload only JSON file content as a mapping repository in the next step.

It is also possible to use the Message type, but it is not recommended because it requires additional execution steps and is only used internally.

The sender should be a unique partner code [20] from your external application that identifies the correct partner mapping to execute the received message with. The mapping should be a code [20] and is used as a Received Mapping Code filter, together with the Partner Code (sender), to identify the partner mapping that needs to be executed. For the XmlRepository and JsonRepository types, the sender and mapping fields are mandatory.

Response

The response includes the ID of the created message queue entry and other relevant information. You will require this ID for the next step.

Status: 200
Body: {
    "id": "<system-id>",
    ...
}

Sending the repository data

To send the actual XML or JSON data and complete the process for XmlRepository and JsonRepository types, a second request is necessary. This request will create a Received Partner Message from a message queue entry and delete the partner message queue entry.

Request
PUT <bc-service-odata-url>/api/cosmoconsult/dataintegrationframework/v1.0/companies(<company-id>)/messages(<message-system-id>)/data
Header: {
    "If-Match": "*"
}
Body: <data> (the XML repository or JSON repository)
Response

After a positive response with a status of No Content (204), the corresponding message queue entry will be deleted and cannot be accessed.

Status: 204 (no content)

Deleting of the message queue entry

For the XmlRepository and JsonRepository types, the message queue entry will be deleted automatically after the data has been sent. For the Message type, the message queue entry will not be deleted automatically. You can delete the message queue entry manually by using the following request:

DELETE <bc-service-odata-url>/api/cosmoconsult/dataintegrationframework/v1.0/companies(<company-id>)/messages(<message-system-id>)

Status: 204 (no content)

Examples

Example SaaS

POST https://api.businesscentral.com/fa8bbabb-f0d6-45b9-83f9-5bfa6c036aed/production/api/cosmoconsult/dataintegrationframework/v1.0/companies(ba0f0202-e8af-42af-b2b7-226825a0bc00)/messages
"Content-Type": "application/json"
"Authentication": "Bearer ..."
{
    "sender": "COMPANY A",
    "mapping": "ITEM2XML",
    "type": "XmlRepository"
}

Status: 200
{
    "id": "65adc1d2-e7ae-47fd-bbaa-5255454c7d80"
}


PUT https://api.businesscentral.com/fa8bbabb-f0d6-45b9-83f9-5bfa6c036aed/production/api/cosmoconsult/dataintegrationframework/v1.0/companies(ba0f0202-e8af-42af-b2b7-226825a0bc00)/messages(65adc1d2-e7ae-47fd-bbaa-5255454c7d80)/data
"Content-Length": 121
"Content-Type": "application/xml"
"Authentication": "Bearer ..."
"Body": <database><items><item><number>1000</number><description>Item</description></item></items></database>

Status: 204

Example OnPrem

POST http://local-container:7048/BC/api/cosmoconsult/dataintegrationframework/v1.0/companies(ba0f0202-e8af-42af-b2b7-226825a0bc00)/messages
"Content-Type": "application/json"
"Authentication": "Basic ..."
{
    "sender": "COMPANY A",
    "mapping": "ITEM2XML",
    "type": "JsonRepository"
}

Status: 200
{
    "id": "65adc1d2-e7ae-47fd-bbaa-5255454c7d80"
}


PUT https://api.businesscentral.com/fa8bbabb-f0d6-45b9-83f9-5bfa6c036aed/production/api/cosmoconsult/dataintegrationframework/v1.0/companies(ba0f0202-e8af-42af-b2b7-226825a0bc00)/messages(65adc1d2-e7ae-47fd-bbaa-5255454c7d80)/data
"Content-Length": 68
"Content-Type": "application/json"
"Authentication": "Basic ..."
"Body": { "items": [{ "no": "1000", "name": "Test" }] }

Status: 204
Tip

This scenario uses basic authentication for OnPrem. Create the header value by 'Basic: ' + Convert::ToBase64String("userid:webservicekey"), or use different authentication methods.

Feedback

Submit feedback for this page .