Mapping app

Purpose

The Mapping app is designed to guide developers through the integration process with the Wair Connector App, covering a range of essential tasks. Its purpose includes:

• Filling and Passing Proxy Tables: Example of how to correctly populate proxy tables and pass them to the connector app for processing.

• Mapping Custom Solutions: Example of how to map a custom solution to the Wair API, aligning it with the specific requirements of the integration.

• Extending and Mapping Standard Business Central Functionality: Example of how to extend and map existing Business Central features to work with the Wair Connector App.

• Retrieving and Parsing Results: Guides on how to retrieve results from Wair to the custom solution.

• Syncing Deleted Records: This shows the process of syncing deleted records from your solution with Wair.

• Using Job Queues for Record Processing: Examples of using job queues to automate the processing of records.

• Using Actions for Record Processing: Example of how to use actions within Business Central to manually process records as needed.

Example Scenarios

This section will provide more detailed examples focusing on specific areas of the mapping app.

Mapping Entities to Proxy Tables

Mapping values with proxy tables from the Wair Connector app is straightforward. Start by assigning the fields and inserting the record. It is important to use Insert(true) as this trigger ensures that all mandatory fields are filled. If the trigger is not executed, potential issues may arise. After populating the proxy table, call the API handler’s Send procedure (e.g., the Brand API Handler). Pass the filled proxy table as a parameter to this procedure. Since the Brands endpoint supports a full load, you can specify this parameter to send the payload as a full load.

Picture 19: Brands mapping and sending using Wair Connector App

If the request is successful, mark the records in the custom solution as populated in Wair. This can be achieved by adding an indication field to the custom table to show that the record has been sent to Wair.

Picture 20: Marking brands successfully sent to Wair

Handling Partially Successful Results

When mapping endpoints with limits, the Send procedure may return false, which, as previously described, does not necessarily indicate that the entire request failed. More details about the limits can be found here: UI Overview and configuration. To accurately determine which records were successfully sent, the Is Successful field must be checked. The process is as follows:

1. Send the request:

Picture 21: Send procedure mapping

2. Next, filter the returned 'Purchase Order WRS' record to display only records where 'Is Successful' equals true. This will show only the successfully processed records:

Picture 22: How to check partially successful results

Retrieving and Parsing Results

When handling recommendations, the Retrieve procedure of the desired handler must be called to receive them, and the proxy recommendation table should be passed.

Picture 23: How to retrieve recommendations

This procedure sends a GET request to Wair and inserts all recommendations into the provided proxy table.

Syncing Deleted Records

When data is removed from Business Central, it should also be removed from Wair. This can be done by creating a Wair Delete Log Entry, which will be processed later. Use the CreateWairDeleteLogEntry procedure from the Delete Log Management codeunit, passing the correct type and record ID (a GUID, such as the SystemId). This process can be implemented in the OnDelete trigger of the table or in other places like actions or other triggers.

Picture 24: Deleted entries synchronization with Wair

Using Job Queues for Record Processing

To process data asynchronously, Job Queues can be used. For example, to automatically send all Item endpoints every 24 hours, create a job queue codeunit that handles this task. The Mapping App provides an example of how to do this—call each desired API handler within the job queue codeunit.

Picture 25: Job Queue to send all Items

Using Actions for Record Processing

This process can also be done using Actions. Create an action that populates the proxy table with custom or standard record information, then call the appropriate API Handler. A simple action can be implemented to recreate items, such as Brands (using FullLoad), and the action would look something like this:

Picture 26: Action example that sends Brands to Wair

Picture 27: Brands mapping functionality

It simply calls the implementation codeunit of your solution and sends all the brands to Wair using FullLoad.

Batch Processing

Starting batch processing involves calling the batch start endpoint, and upon completion, the batch stop endpoint is called. This mechanism informs the API that the batch is complete, ensuring that incomplete data sets are not processed. More information and examples can be found here: Batch stop and start process.

To use batch processing, simply call the BatchStart() procedure (which is managed by the 'Batch API Handler WRS' codeunit), followed by the desired handlers, and conclude with the BatchStop() procedure.

Picture 28: Batch process

Batch API documentation can be found here: POST /Batch/start.

Summary

For additional examples, the full Mapping App is available for reference (TODO: maybe reference to a public mapping app repo?). However, the fundamental process of integrating a custom solution with the Wair Connector App can be summarized as follows:

1. Populate the proxy table with the relevant data.

2. Send the request using the appropriate API Handler.

3. Insert deleted entries to synchronize with Wair.

4. Integrate received recommendation data into the solution.

The Wair Connector App manages all other aspects, including the correct JSON structure, appropriate endpoint selection, logging mechanisms, etc. This streamlined process ensures that integration is both efficient and reliable, reducing the need for extensive custom development.