¶ Connections
¶ Basic Information
Connections are the place where RESTwithUS stores all links between records in Business Central and records in an external system. You can access them from a provider list by clicking on any connections number:
Or you can go to entities by selecting Entities in the menu and click the connection numbers on selected entity:
In the example you have 2 healthy connections and 1 broken connection for the Customer entity. Let's click on the number in Total Connections to view them:
- Healthy Connections are records that were successfully matched between both Business Central and an external system (e.g. Customers existing in both systems).
- Broken Connections are records returned by the API service – but RESTwithUS was not able to match the data with any record in Business Central (e.g. the Customer is missing in Business Central or has a wrong number in an external system). These connections are marked with red color.
All connections contain the following information:
- The Entity Description – Connections are always tracked on Entity level. E.g. you have one Customer entity and you are using the POST operation to create the customer, the PUT operation to update his data, the DELETE operation to delete him – and all these operations are working with the same connections.
- The External ID is the unique id of the record in an external system. When you are working with the record in an external system, this is the identifier to use.
- The Ext. Description (optional) is the description of the record in an external system. This is not required but helps when searching for a particular record.
- The Record is the related record in Business Central identified by its primary key.
Plus there are some interesting options in Details menu:
- Batch Entries will show you all Batch Entries related to selected connection.
- Show Record will point you directly to the related record in Business Central.
¶ How to Maintain Connections
¶ In Operation Response
Connections can be created, updated or deleted by the Operations JSON response. The setup is always very similar, so let's have an example of a POST operation on a Customer which creates a new record. Response JSON body is following:
- The connections are done for a table in Business Central, so they are always managed on nodes with Type
Table. - The node must be associated with some Entity in the field Entity ID. This entity will be used for storing the connections through multiple operations.
- You can set up the connections in node details – select the node and choose Home / Details from the menu.
In the details window pay attention to Connections tab. First you need to set the mapping operation:
- In the Connection Operation field select what this operation should do with the connection. This setup is different for each type of operation and below you can find the usual settings:
- GET operation:
Create or Update - POST operation:
Create - PUT/PATCH operation:
Update Only(or not needed at all, this will update the mapping description only) - DELETE operation:
Delete(this will only work if the operation returns some kind of JSON body; if it doesn't, you need to delete the mapping with code)
- GET operation:
- Create Connection if No Match – Check this option if you want to create a connection, even if no matching record in Business Central was found. The connection would be created as broken.
- Create Connection if No Unique – Check this option if you want to create a connection, even if more than one record was found by the table view filter (e.g. two contacts with the same e-mail). The connection will be created for the first record found.
Second important setting is the Table View which defines, how should RESTwithUS search for related record in Business Central:
This is a standard Business Central table view expression and you can update it in any way you want (i.e. use any field or combination of fields for the filtering).
You can even use helper function Generate Table View to generate the table view with it. Just select the table index that suits you the most (e.g. if you match the records by Business Central Customer No. select the no. primary key.) – and RESTwithUS will create the table view for you.
Note the {{Field1}} variable in the expression. During the operation run, this expression will be replaced by data from JSON response. You just have to tell RESTwithUS where to find the value:
¶ With Code
DELETE operations sometimes don't return any meaningful JSON body. If they do, you can use the Connection Operation settings as usual – but otherwise, you need to delete the mapping with code after the operation run. Use following line of code using API Script RWU codeunit:
//Select provider and entity by enum ID (recommended)
var
APIScriptRWU: Codeunit "API Script RWU";
EntityID: Enum "Entity ID RWU";
ProviderID: Enum "Provider ID RWU";
ApiScriptRWU.DELETE_MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer,Customer);
//Select the mapping by record SystemId (recommended for BC 18 and newer)
APIScriptRWU.DELETE_MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer,Customer.SystemId);
//Select provider and entity by description (for testing purposes)
ApiScriptRWU.DELETE_MAPPING('Test Provider','Customer',Customer);
Parameters are: Provider name, entity name and a Business Central record, whose connection you want to delete.
Tip: For more API Script functions see guideline API Script Functions Reference.
¶ How to Get Information From Connections
¶ External ID
Mostly you want to look into the connections for a record External ID (the unique id in an external system).
For example, let's have a Customer 01121212. You want to make an action on the Business Central page, that will create the customer in an external system – or update his data if he already exists.
To make such a function you first need to know, if the record was already created in an external system. But you are saving the information into connections, so if a POST operation was done on the record, you should have a trace there. Plus you have saved the External ID there, too – and you will need that to make a PUT/PATCH call.
To get the id write one line of code using API Script RWU codeunit:
//Select provider and entity by enum ID (recommended)
MappingId := APIScriptRWU.MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer, Customer);
//For BC 18 and newer use record SystemId instead
MappingId := APIScriptRWU.MAPPING(ProviderID::TestProvider,EntityID::TestProvider_Customer, Customer.SystemId);
//Select provider and entity by description (for testing purposes)
MappingId := APIScriptRWU.MAPPING('Test Provider','Customer', Customer);
- Parameters are: Provider name, entity name and a Business Central record, whose external id you want to get.
Mapping Idis a Text variable. The function will return an empty string, if no connection was found, and the record External ID othewise.
You can then use the result to find out, which operation you should call:
if MappingId = '' then begin
//Call POST operation to create the Customer
end
else begin
//Call PUT/PATCH operation to update the Customer
end
Tip: For more API Script functions see guideline API Script Functions Reference.
¶ How to Fix Broken Connections
If you have a red broken connections in the list, there are more ways to fix them. Probably the easiest way is to create a GET Multiple Records operation, that will get all records from an external system and Create or Update the connections. If there are still some errors after the operation run, you can easily track them in Batch Entries and find out, what happened.
Common issues are following:
- The connection management in response table node details is not set up correctly:
Please ensure you have filled in Connection Operation and Table View fields – and that the Table View is correct and all{{!Field*}}variables can be found in the response body (e.g. in the example, the JSON response should contain Business Central table field number1). - The record in Business Central or in an external system is missing some vital information. For example if you match the records by e-mail (e.g.
E-mailfield in Business Central andemailnode in an external system), you must have the same values in both fields for the records to match.
Second option how to fix the connection is to select the broken connection and use Connection / Fix Connection action:
This action will show you the list of all records in the table and you can select the right one and press OK:
Just confirm the selection and the connection will be fixed.