¶ Working with Entities
If you plan to use RESTwithUS only for simple API requests like let's say fetching search results from Bing, you can skip entities altogether. But when you need to connect data from Business Central with data from an external system, using entities is almost mandatory.
¶ What Are Entities?
Let's say you are connecting to an external system via REST API and you want to work with Customers. You have the data of your customers in Business Central and you would like to program functions that will export the data of your customer to an external system, update the data or delete the customer there, if it's not needed anymore.
In this example, Customer is an entity. This entity exists in two systems – in Business Central and in an external system. But it can have totally different structure in each system (different field names, ids etc.) and you may not export all customers, so the records can be different too.
To properly connect those two systems, you need to:
- Establish a connection between record in Business Central and in an external system (e.g. know, that Customer
10000in Business Central is a record with GUID2022df81-49e6-4ae9-84f5-202aec47efa6in an external system). - Call some operations on this entity (e.g. create new customer with POST operation, update this data with PUT/PATCH etc.). All these operations are working with the same data and the same entity.
- Usually, the JSON structure of an entity is very similar in all operations (POST, GET, PUT, etc.). This means you can use entities to define the JSON schema in one place and use it in all operations.
If you are creating your own AL extension that should implement connection with some API provider, the recommended way to start is to add your entity to Entity ID RWU enum:
enumextension 50001 "Test Entity ID RWU" extends "Entity ID RWU"
{
value(50000; "TestProvider_Customer")
{
Caption = 'Customer (Test Provider)';
}
}
Tip: You can skip this step for testing purposes and select your entities by entity description instead of enum ID. However, this is not recommended for production applications.
To open the list of entities, select your API provider from the list and open Entities:
Create a new entity called Customer and select the enum ID in Entity ID field:
The entity has the status
Openand can be updated now. Use function Release to move the entity to aReleasedstatus where it can be used in API requests.
¶ Connections
When you actually start to use the entity in operations, RESTwithUS will track connections between Business Central records and data in an external system:
- Healthy Connections are records that were successfully matched between both systems (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).
You can click on any number to view the connection details for selected entity:
- External ID is the ID of the record in an external system (can be a number, GUID, etc.).
- Ext. Description is the description of the record in an external system.
- Record column holds the information about related record in Business Central, defined by a
Primary key.
Tip: For more details about connections see guideline Connections.
¶ Entity Schema Definition
The operations (GET, POST, PUT, etc.) working with one entity usually share the same or very similar JSON body structure. Let's have a very simple example of a JSON body for a Customer entity:
- The field
idholds the ID of a record in an external system (External Id). - For the sake of simplicity, let's assume you have a Business Central Customer No. in field
no(but you can match the records by any field or a combination of fields). - And there are more fields that can be matched to existing Customer fields in Business Central.
The same or very similar JSON body will be used in GET operations to retrieve data, POST operation to create a new customer, or PUT operation to update data of the existing customer. You can take advantage of that and define the JSON body structure in one place.
To define JSON body schema select your entity and open Schema Definition:
¶ Import JSON Payload
When starting from an empty schema, the best way is to use function Payload / Import Payload, paste an example of JSON body and press OK:
RESTwithUS will parse the JSON data and prepare schema lines that you can easily modify:
Tip: You can use the same feature in the request and response body too.
¶ Map the JSON Body to Business Central Tables and Fields
Now let's tell RESTwithUS, how the JSON structure relates to Business Central data:
- Whole JSON object relates to
Customertable in Business Central:
In therootnode select TypeTableand selectCustomertable in Object ID field. Note that RESTwithUS automatically sets JSON Data Type toObject, which means that this node contains a record with some fields.
Tip: For more details about JSON Data Types see guideline JSON Data Types.
- You need to mark a field which contains record unique ID in an external system (this is required for making connections):
In this example the ID is inidnode. Select the node and setExternal IDin Type column.
Tip: If you set MinOccurs to
Zero, you can use the same JSON schema in both request (where the id node is usually missing) and response. In node details, Empty Value on Zero Occurs must be set toSkip(default value).
Note that RESTwithUS is automatically attaching this node to the current entity (column Entity ID). No need to change that now, but later you may want to embed an entity inside another entity etc.
-
In the same way, mark a field containing a record description. This is not required, but it helps when looking for a particular record in connections:
Selectnamenode and set the Mapping Type toDescription. -
Set up fields which are both in Business Central record and a record in an external system:
For each such field (no,name,address, etc.) set Type toFieldand select matching Business Central field in Object ID column.
Tip: You don't need to match all fields, just those you are interested in. Plus you can always control which data and fields are updated in Business Central via RapidStart package settings (see guideline Updating Data in Business Central).
- Let's say that the node
phonesis optional – if a Customer in an external system does not have any phone number, the node will be missing in JSON body. With default settings this may throw an error, but you can mark the node as optional by setting MinOccurs toZero:
And that's it, you have your first simple entity. Just don't forget to Release it before using it in API operations.
Tip: For more details about setting JSON body structure see guideline Importing and Setting up JSON Body Structure
¶ Set Node Details
Each node in JSON body schema can have its own detailed settings. To access it, select the node from the list (for example node phones) and open Home / Details:
In these details you can for example change following settings:
- Empty Value on Zero Occurs – Specifies the behavior of a JSON node with MinOccurs = Zero (node is optional), if the node has no value. Select a)
Skipfor removing the node from resulting JSON, b)Empty Objectto include the node in resulting JSON and set the value to empty object. - Conflict in Child Nodes – Specifies processing behavior if real response JSON differs from the schema (e.g. the JSON node contains some children which are missing in the schema). Select a)
Errorto end such request with error, b)Ignore Missing Schemato ignore missing nodes in schema.
¶ Using Entity Schema in Request/Response
Let's say you now want to load the list of Customers from an external system which returns following JSON data:
You can set each API operation individually, but you can simplify the work using your predefined entity schema too.
Select your API Provider from the list and open Operations. Now create a simple GET operation that should work with your Customer entity:
GET operations usually do not have a request JSON body, but they are returning JSON data in a response. You can access response body settings by selecting Response Body. For a new operation the body is still empty.
Let's first import a JSON payload with Payload / Import Payload function – just paste an example of JSON response and RESTwithUS will create response lines for you.
As you can see, the JSON body structure is very similar to the Customer entity structure, just the result node has now JSON Data Type Complex Array, meaning that it can contain multiple Customers, not just one (MaxOccurs field is now set to Unbounded):
You can now start to map the JSON body to Business Central tables and fields, but since you did that work already when defining the Customer entity schema, you can take advantage of it. Select all Customer entity nodes save the first line and delete them:
Now change the Type of the result node to Schema and select your predefined Customer entity in field Object ID. After you're done, use function Schema / Expand Schema to load the entity definition:
Note that all lines with expanded schema have the entity name in column Expanded Schema. You won't be able to modify such lines directly (you can only set some additional Details for them) – if you want to change their JSON body schema, update it in the entity schema and use function Refresh Operations:
Tip: If you really need to modify the expanded entity schema, you can use function Schema / Forget Schema. However, you won't be able to use Refresh Operations function on the lines anymore and all changes will have to be done manually.
¶ Refresh Operations
Let's say that the API JSON data structure undergoes some changes with a new patch – provider is adding a new zip field containing Post Code and for some reason he sometimes does not send countryCode node at all, making it optional. The API response now looks like this:
That can of course break your API operations, plus you may need to incorporate the zip field somehow. But you have multiple operations for a Customer now – GET, POST, PUT, etc. – all using very similar JSON body structure. So you can either go through the operations one by one and update their structure – or with entities you can make the changes in one place and use Refresh Operations feature.
Let's get back to your Customer entity and open the schema definition:
The changes are quite straightforward:
- Create a new line for the
zipnode and match it with correct field in Business Central. - Make the
countryCodenode optional by setting MinOccurs toZero.
Don't forget to Release the entity after making changes and then use the function Refresh Operations on your entity:
RESTwithUS will tell you, how many operations were updated by the action:
And you can check the results in the example GET operation response body:
