Skip to content
Support Portal
Request Demo
  • There are no suggestions because the search field is empty.

Defining API Mappings

When data is retrieved into Business Central from an external platform as part of an API call, it is necessary instruct the system how to process this data. The API Engine provides you with the ability to define mappings between the data that an API function retrieves from an external system and corresponding objects in Business Central. In this way, retrieved 
data can be entered and processed according to Business Central’s standard functionality.


For example, suppose we were creating an API integration between Business Central and an external product information management (PIM) system. As part of this integration, we define and API function to retrieve product information from the PIM system into Business Central and then create a new item record. In this scenario, we would define API mappings between the data we retrieved from the external system and fields in the Item table. When the API 
function retrieves information, a new item record is created and its values are populated according to these mappings.


You can view an API function’s API mappings from the API Functions page by selecting the relevant API function line, then choosing the API Mappings action in the ribbon. You can manually define API mappings for an API function, but a more efficient way of performing this setup activity is to first generate an API message for the API function, then using that message’s data buffer as the basis for the function’s API mapping definition:

  1. After configuring an API function on the API Functions page, choose the Execute action in the ribbon. A notification will ask if you want to open the new API message that was created.
  2. Choose the Yes button to open the API message.
  3. Choose the Related ribbon, then choose the Message Data Buffer action.
  4. On the API Data Buffer page, choose the Update API Mapping action in the ribbon.
    The API Engine will use the API message’s data buffer to build mappings for the related API function.
  5. Close the API data buffer and API message to return to the API Functions page.
  6. Choose the relevant API message, then choose the API Mappings action in the ribbon.
  7. The first API mapping line that is created from the data buffer is the top-level process that serves as the root parent to all subsequent mappings, and should be edited as follows:
    1. Place a check mark in the Function Root Node field to identify this mapping as the root process.
    2. In the Source Type field, choose the TableNode option.
    3. Enter or use the AssistButton in the Table No. field to assign the table to which all API mappings that exist within this root mapping will write their data. This could be a standard Business Central table, or a custom one that has been created for a specific organization.
  8. You then must indicate which API mapping line represents the starting point for a record’s mappings. As the API Engine processes an API call’s response, this API mapping will instruct it to create a new record in the specified table. Subsequent mappings will enter data against that record.
    1. In the Source Type field, choose the RecordNode option.
    2. Enter or use the AssistButton in the Table No. field to assign the table to which all API mappings that exist within this record will write their data. This could be a standard Business Central table, or a custom one that has been created for a specific organization. Note that it is possible to build API mapping structures that feature record nodes within record nodes, allowing for a single API function to enter data in a given table as well as one or more sub-tables.
    3. If the API function retrieves data as a single array enter or use the AssistButton in the Field No. field to assign the field from the specified table to which you want to map the relevant piece of information represented by the API mapping line. If the data is not retrieved as part of a single array but rather through multiple elements, you will perform this field mapping for the API mapping lines that represent these elements, as described in the next step.
Once you have defined the table and record nodes, it is then necessary for you to map the different values that are retrieved as part of the API call’s response to corresponding fields in Business Central. On each line that you want to map to a Business central field:
  1. In the Source Type field, choose the Element option.
  2. Enter or use the AssistButton in the Table No. field to assign the table to which you want to map the relevant piece of information represented by the API mapping line. This could be a standard Business Central table, or a custom one that has been created for a specific organization.
  3. Enter or use the AssistButton in the Field No. field to assign the field from the specified table to which you want to map the relevant piece of information represented by the API mapping line.

    If the selected field is a part of the assigned table’s primary key, the IsKeyField field will be automatically checked by the API Engine.

You can also manually enter API mappings, if desired. This is especially useful if it is necessary to create a mapping beyond the scope of what the API Engine can generate from an API message’s data buffer. In addition to the Table Node, Record Node, and Element source types described above, you can create mappings for the following source types:

Record Node Value: the API mapping is included as part of the record, as identified by the Record Node mapping, but does not have a dedicated element as retrieved from the external system. This is useful in scenarios where you retrieve a single value from the external platform and want to enter it in a Business Central table that requires a code and description. In such a scenario, you would map the Record Node level line to the table’s Code field, then manually create a separate Record Node Value line that maps the same piece of data to the table’s Description field.

When you are manually entering API mapping lines, you must assign a value in the Sequence field to indicate how it should be processed in relation to other mappings. The API mapping lines that are automatically created from a message’s data buffer are incremented in values of 10, making it easy to insert a new API mapping line wherever desired.


Next: Copying API Functions