The Serialized Logistics V2 API channel is an extension of the Serialized Logistics application to send requests to the Serialized Logistics application over API.

Next to the Serialized Logistics V2 API, you can configure the webhook.

Webhook makes it possible to send updates to an external web application.
Give the endpoint URL of the subscribing system and optionally configure the security aspects.
When there is a change in the status of an order, Movilitas.Cloud sends the order details to that system.
To verify the webhook settings, you can manually execute a webhook.
A webhook log is also available to verify the success of the webhook and the order details sent to the external system.

When receiving an EPCIS file or an EPCIS string from a supplier over API, the request is logged on the channel. Verify that the requests sent from the external system are successful.

List of Procedures

Configuring a Serialized Logistics V2 API Channel
Configuring Webhook
Testing Webhook
Viewing Webhook Logs
Viewing EPCIS Logs

For more information on the general channel actions, see Managing Channels for a Tenant (Overview).

Configuring a Serialized Logistics V2 API Channel

Procedure

1. Go to Movilitas.Cloud Console --> My tenants.

2. Select the tenant or click Open tenant next to it.

3. On the Tenant Dashboard, select the Channels tab. The application displays the list of channels assigned to the tenant.

4. Click the + icon (Create channel). The application displays the Create channel dialog.

5. Select Shopfloor channel as the type and click Create. The application displays the Create Channel page with an empty form to give the parameters of the channel.

6. Enter a name for the channel and select Serialized Logistics V2 API as the source.

7. Click Create Channel.

The application informs you about the additional costs. After confirming the creation, the application displays the Edit Channel page.
The channel key is also generated that you will need when sending the API requests to the Movilitas.Cloud application. You can find and copy the channel key at the top of the Edit shopfloor channel panel.
Optionally, you can modify the name of the channel at any time.

Example:

Next Steps

To communicate over the Serialized Logistics V2 API:

Configure the Serialized Logistics application.
Obtain an authentication token after creating the API key and secret.
Copy and keep the channel key of the Serialized Logistics V2 API channel for the API communication.

For more information, see Before You Send Any API Request and Serialized Logistics V2 API.

Back to the list of procedures

Configuring Webhook

Webhook enables Movilitas.Cloud to send the order details to an external system when there is a change in the status of an order. Provide the endpoint URL of the subscribing system, configure security, and activate sending webhooks.

Procedure

1. Go to Movilitas.Cloud Console --> My tenants.

2. Select the tenant or click Open tenant next to it.

3. On the Tenant Dashboard, select the Channels tab. The application displays the list of channels assigned to the tenant.

4. To search for a Serialized Logistics V2 API channel, use the search field and the filters:

Enter the channel name in the search field.
Select the status.
Select Serialized Logistics V2 API as the source.
Select Shopfloor channel as the type.

5. To view the channel information, click on the channel name or the edit icon (Edit channel) next to the channel. The application displays the Serialized Logistics V2 API channel details, the Webhook Settings panel, and the Webhook Logs.

The following example illustrates the case when we are configuring webhook from scratch:

6. Provide the endpoint URL to receive the details of an inbound external order when there is a change in the status of the order.

7. If authorization is required to send messages to the specified endpoint, select the Authorization checkbox and configure the security settings. The required fields are marked with an asterisk (*) in the form.

Field	Description
Authorization Types	Select the type of authorization. API Key OAuth 1.0 The form dynamically changes depending on the selected type.
API Key
Key	Enter the key as expected by the subscribing system. For example, "API-Key".
Value	Enter the API key value that was generated in an external system, for example, the SAP client.
Add to	Specify where to add the credentials in the request. The supported value is Header.
OAuth 1.0
Signature Method	Select the signature method. The supported value is HMAC-SHA256.
Consumer Key	Enter the consumer key as expected by the external system.
Consumer Secret	Enter the consumer secret related to the consumer key.
Access Token	Enter the access token.
Token Secret	Enter the token secret.
Add to	Specify where to add the credentials in the request. The supported value is Header.

8. Activate webhook by selecting the Active checkbox.

The following example illustrates the case when API Key authorization is set for the webhook:

The following example illustrates the case when OAuth 1.0 authorization is set for the webhook:

9. Click Save.

The webhook is configured. If there is a change in the status of an order in the Serialized Logistics application, Movilitas.Cloud sends the order data to the configured endpoint.

Next Steps

Test the webhook settings manually by providing the order ID of an existing order.

Back to the list of procedures

Testing Webhook

To test the webhook settings, you can manually execute a webhook by providing the order ID of an existing order.

Before You Begin

Make sure that the order is existing in the Serialized Logistics application.

Procedure

1. Open the endpoint URL of the external system in your browser.

2. Go to Movilitas.Cloud Console --> My tenants.

3. Select the tenant or click Open tenant next to it.

4. On the Tenant Dashboard, select the Channels tab. The application displays the list of channels assigned to the tenant.

5. To search for a Serialized Logistics V2 API channel, use the search field and the filters:

Enter the channel name in the search field.
Select the status.
Select Serialized Logistics V2 API as the source.
Select Shopfloor channel as the type.

6. To view the channel information, click on the channel name or the edit icon (Edit channel) next to the channel. The application displays the Serialized Logistics V2 API channel details, the Webhook Settings panel, and the Webhook Logs.

7. On the Webhook Settings panel, enter the order ID in the Order ID field and click Execute.

Movilitas.Cloud sends the order data to the external system through a webhook.

Example:

8. Verify the order data in the webhook logs and in the external system.

If the log belonging to the order is in successful status (green checkmark icon) and you can see the order data in the external system, your webhook settings are correct. Next to the log, an indicator (i) icon is displayed to show that the webhook was manually executed.

The following example illustrates the case when the webhook was successful, and the webhook settings are correct:

Result:

When there is a change in the status of an order in the Serialized Logistics application, Movilitas.Cloud automatically sends the order details to the subscribed system through a webhook without human intervention.

Back to the list of procedures

Viewing Webhook Logs

A log is created each time the order details are sent through a webhook due to a status change. The logs are collected in a separate table. For each log, you can see the status of the request, the date and time when the update was sent, and the order ID. An indicator (i) icon next to the log helps you to identify the manually executed webhooks (manually sent messages).

You can search for a log by entering the order ID and filtering on the status (success or failed). You can expand the log to verify the order details sent in the webhook and the response from the external system (if any).

Procedure

1. Open the endpoint URL of the external system in your browser.

2. Go to Movilitas.Cloud Console --> My tenants.

3. Select the tenant or click Open tenant next to it.

4. On the Tenant Dashboard, select the Channels tab. The application displays the list of channels assigned to the tenant.

5. To search for a Serialized Logistics V2 API channel, use the search field and the filters:

Enter the channel name in the search field.
Select the status.
Select Serialized Logistics V2 API as the source.
Select Shopfloor channel as the type.

Example:

7. On the Webhook Logs panel, investigate the logs.

If you see a green checkmark icon next to the log, sending the order details for the status change was successful.
If you see a red exclamation mark icon next to the log, sending the order details for the status change failed.
If you see an (i) indicator icon next to the log, the message was manually sent to the endpoint URL.

8. Search for a log by entering the order ID in the search field and selecting the status of the log. The logs are filtered based on the search criteria.

9. To view the order details sent in the log, expand the log by clicking > (Expand).

In the following example, we are searching for all the logs for order ID "Order220125-2" and are viewing the details of the last log:

There were five status changes of the order (five logs). All of them were sent automatically because there is no indicator (i) icon next to them.
Each log was successful (green checkmark icon on the left).
Each log contains the order details for the specific status change.
The last log is expanded to view the order details sent in the webhook and the response from the external system.
The order details contain data related to the order, the line items, and the deliveries. Status is provided for the order, for the deliveries, and for the line items under a delivery. For each delivery, it is possible to verify the expected quantity versus the received quantity per line item.

Back to the list of procedures

Viewing EPCIS Messages

Each time the external system sends an EPCIS file or EPCIS string over API, a log is created. When receiving the EPCIS content as a string, the application saves the content into an XML file and the file name is a randomly generated UUID. The logs are collected in a separate table. For each log, you can see the status of the message, the date and time of creation, the supplier name (sender), and the file name.

You can search for a message by entering data from the payload. You can expand the message to verify the message and investigate errors (if any).

The messages are also logged on the related supplier's page in the Serialized Logistics application under the Site management --> Suppliers --> Uploads tab. The content of the EPCIS file (trade items, containers, hierarchy information, and shipping event) is stored in the Serialized Logistics application. For more information, see Managing Suppliers.

Before You Begin

To receive the EPCIS files from the supplier over API, the Serialized Logistics application must be configured:

Supplier (sender) - Supplier name and supplier SGLN as a minimum (master data).
Warehouse (receiver) - Warehouse name, warehouse SGLN, and country as a minimum.

Procedure

1. Open the endpoint URL of the external system in your browser.

2. Go to Movilitas.Cloud Console --> My tenants.

3. Select the tenant or click Open tenant next to it.

4. On the Tenant Dashboard, select the Channels tab. The application displays the list of channels assigned to the tenant.

5. To search for a Serialized Logistics V2 API channel, use the search field and the filters:

Enter the channel name in the search field.
Select the status.
Select Serialized Logistics V2 API as the source.
Select Shopfloor channel as the type.

Example:

7. On the EPCIS messages panel, investigate the messages.

If you see a checkmark icon (Success) next to the message, the EPCIS file is successfully processed.
If you see a red exclamation mark icon (Error) next to the message, the EPCIS file is processed with error(s).

8. Find a message by entering data from the EPCIS content or from the error description (if any) in the search field. For example, the document instance identifier, an SGTIN, or an error message.

The messages are filtered based on the search criteria.

IMPORTANT: If the EPCIS file is large or there is a large list of errors, searching is not effective meaning that this message is not included in the search results.

9. To view the message details, expand the message by clicking > (Expand):

Header of the log - Status, create datetime, supplier name, and file name.
Errors (if any) - The application lists the errors detected during processing one after the other. For a large list of errors, the application does not display the errors but you can download the error file.
EPCIS message. For a large EPCIS file, the application does not display the EPCIS content but you can download the EPCIS file.

In the following example, the search expression is the document instance identifier from the EPCIS file. The EPCIS file is successfully processed: