IBM Sterling Order Management Integration to Convey

This document describes:

Overview
Prerequisites
Integration
Order process
Deploying code
Configuring Sterling Order Management
Testing Convey integration
Extending Order Hub to add new fields

Overview

IBM Sterling Order Management integrates with Convey to provide the real-time shipment visibility with detailed in-transit status of the orders. This is a starter integration asset and is not a final integration. Take the sample code "as is, where is, with all faults" and no representations or warranties are made or responsibilities assumed by provider.

Prerequisites

General understanding of IBM Sterling Order Management development
IBM Sterling Order Management Developer Toolkit
Working relationship with Convey
- With a configured mock sample carrier for testing
IBM Sterling Order Management Store application
IBM Sterling Order Management Order Hub console to be provisioned

Integration

The integration of IBM Sterling Order Management with Convey provides an end-point implementation for the following order updates:

For updating Sterling Order Management Order or Shipment with ShipmentContainer update events that are published by an external delivery tracking system.
For publishing Order or Shipment data to an external delivery tracking system.

The following diagram helps you understand the high-level process of a sales order fulfillment and the points of integration with the external delivery tracking system.

Sales order fulfillment process:

A user places an order in an e-commerce store or a store associate creates an order for the user in the Call Center.

a. Inventory is managed in IBM Sterling Order Management Inventory Visibility.
b. Promising dates are managed in IBM Sterling Management OMS Promising.
c. The expected delivery date must be stamped to the Order Line requested delivery date field.
The order is placed or transferred to IBM Sterling Order Management (order is in confirmed state).
The order is handled by Sterling Order Management. The sample integration scenario supports b2c order flows.

a. You can automate or manually process the order sourcing and scheduling by using the Order Hub console.
b. New shipments that are created and sourced from a store must be placed in the Ready for Backroom Pick status.
c. The store agent picks and packs the order and a Tracking Number (TN) is generated by the store.
When a shipment is packed by the store agent, Sterling Order Management sends a message to Convey by calling the Create Order API of Convey. The message contains the shipment details along with the Tracking Number of the order.
When the order is in transit, Convey calls the Sterling Order Management APIs to synchronize order updates such as dates and order status by using the Shipment Event Push API.
You can verify the Sterling Order Management order status and the Convey shipment container status in the Order Hub console. Alternatively, you can configure IBM Sterling Call Center to link to the Convey Tracking Status page.
A Fulfillment Manager can use Order Hub to verify the order status for the last mile (stamped on the shipment container). A Fulfillment Manager can also log into the Convey user interface to get more details for all order shipments and statuses.

Order process

When an Order in IBM Sterling Order Management is released to a store for shipping or delivery fulfillment methods, it goes through a process of pick/pack activities. After the packing is complete, a print label is generated. The assigned carrier confirms the shipping and a manifest is created. When the shipment is confirmed, the carrier picks up the packages.

To track the packages in an external system, Sterling Order Management can publish the order data to the external system when shipment is packed and tracking number from the carrier is stamped on the shipment. The data is transferred through a REST API call by using the createOrder API that is provided by the external system.

The ShipmentContainer goes through different stages of delivery, and the external tracking systems sends change events to Sterling Order Management. Each event is processed in Sterling Order Management and the corresponding ShipmentContainer is updated for Status and the StatusDate as Estimated Delivery Date.

For each event, Sterling Order Management computes a RequestedDeliveryDate for a shipment as a minimum of StatusDate across all its containers. The shipment status moves to a minimum of statuses across all the containers. When the status for all the containers is moved to the delivered status, the ActualDeliveryDate of the shipment is updated with the Max(StatusDate) across all the containers and the shipment is moved to delivered status.

The following diagram displays the movement of statuses of a container and shipment in Sterling Order Management:

Shipment status mapping

The following table lists the Convey status values and their mapping with IBM Sterling Order Management container and shipment statuses.

Convey status	Convey value	Sterling Order Management shipment/container status	Sterling Order Management shipment base status	Sterling Order Management status name	Description
New	new	1100.70.06.70.1	1100.70.06.70 (Shipment Being Packed)	Shipment Created In External	The shipment is created in the external system after being packed in Sterling Order Management.
Quoted	quoted	1100.70.06.70.2	1100.70.06.70 (Shipment Being Packed)	Carrier Price Quoted	A price is quoted for the shipment but the shipment is not scheduled or picked up yet.
Scheduled	scheduled	1300.ex.10	1300 (Packed)	Delivery Scheduled	Delivery for the shipment is scheduled but is not picked up yet.
Pickup Appointment	pickup_appointment	1300.ex.20	1300 (Packed)	Carrier Pickup Appointment	An appointment must be scheduled for the carrier to pick up the shipment.
In Transit	in_transit	1400.ex.10	1400 (Shipment Shipped)	In Transit	The shipment is in transit with the carrier.
Out for Delivery	out_for_delivery	1400.ex.20	1400 (Shipment Shipped)	Out For Delivery	The shipment is out for delivery.
Returning to Sender	returning_to_sender	1400.ex.30	1400 (Shipment Shipped)	Returning To Sender	The shipment is returning to the sender.
Delivered to Sender	delivered_to_sender	1400.ex.40	1400 (Shipment Shipped)	Delivered To Sender	The shipment is delivered to the sender.
Undeliverable	undeliverable	1400.ex.80	1400 (Shipment Shipped)	Undeliverable	The shipment is not deliverable.
Unknown, aka Untrackable	unknown	1400.ex.85	1400 (Shipment Shipped)	Delivery Unknown	The shipment must be trackable but is not successfully tracked yet, either because it is too new to track or because it has a data issue that prevents tracking, such as an invalid tracking number.
Canceled	canceled	1400.ex.99	1400 (Shipment Shipped)	Delivery Cancelled	The shipment is canceled.
Delivered	delivered	1500	1500	Delivered	The shipment is delivered.

Inbound event attribute mapping

Here is a sample message when Convey calls Sterling Order Management to update the delivery status:

{
    "tracking_number": "PT0000110079",
    "event_type": "tracking",
    "shipment_info": {
        "estimated_delivery_date": "2021-08-06",
        "status": "delivered"
    },
    "event_details": {
        "description": "Your Shipment has been delivered",
        "local_date": "2021-07-29",
        "local_time": "13:50:01",
        "utc_offset": "Z"
    }
}

Tracking events

The following table describes the tracking information that is mapped to order data in Sterling Order Management.

Event Element/Attribute	Sterling Order Management Shipment/Container Element/Attribute	Used for Sterling Order Management update	Description
bill_of_lading_number	Shipment>BolNo	Yes	This value must not change during delivery.
carrier_scac	Shipment>SCAC	Yes	This value must not change during delivery.
event_details>local_date	Container>StatusDate	Yes	If event_type='tracking' and shipment_info.status='delivered', then in Sterling Order Management, Container.StatusDate='local_date+local_time+utc_offset'.
event_details>local_time	Container>StatusDate	Yes	If event_type='tracking' and shipment_info.status='delivered', then in Sterling Order Management, Container.StatusDate='local_date+local_time+utc_offset'.
event_details>utc_offset	Container>StatusDate	Yes	If event_type='tracking' and shipment_info.status='delivered', then in Sterling Order Management, Container.StatusDate='local_date+local_time+utc_offset'.
event_type		Yes	Possible values : tracking/exception/predictive We will use 'tracking' events to update the shipment
shipment_id	ShipmentContainerKey	Yes
shipment_info>	ShipmentContainer	Yes
shipment_info>estimated_delivery_date	Container>StatusDate	Yes	This date is used to compute Shipment>RDD or Shipment>ADD as MIN(container>statusDate) based on the status being 'delivered' or not.
shipment_info>status	Container>Status	Yes	This status is used to compute Shipment>BaseDropStatus as MIN(container>status). Sterling Order Management status is mapped with the event status.

Sterling Order Management properties

The following properties are added in Sterling Order Management to facilitate the configuration for integration with Convey.

Action	Property name	Description	Default value
Add	yfs.convey.integration.providerurl	Integration Provider URL	file:///var/oms/jndi
Add	yfs.convey.integration.qcf	Integration QCF	AGENT_QCF
Add	yfs.convey.integration.event.onsuccess.queue	Integraiton Queue	DEV.QUEUE.10
Add	yfs.convey.integration.event.external.queue	Integraiton Queue	DEV.QUEUE.9
Add	yfs.convey.integration.publish.url	Outbound API URL	https://api.getconvey.com/order/v1/order
Add	yfs.convey.integration.publish.auth.key	Bearer token to access Convey	Basic xYUDKFf
Add	yfs.convey.integration.pvft.tracking.number.last.used	Last used Tracking Number from the Convey pool which has been used for internal testing.	PT0000110079

Example for event tracking

A shipment that is packed into 4 Containers is published to the tracking system and is in the ‘Shipment Being Packed’ status. The following sequence of external push events are processed in Sterling Order Management.

Event-1.1

Event from the tracking system is triggered for container-1 with status=new when the order/shipment is created in the external system.

Status

tracking_number	shipment_info status	Container - Old status	Container - New status	Shipment - Old status	Shipment - New status
tn-container-1	new		1100.70.06.70.1	1100.70.06.70	1100.70.06.70

Date

tracking_number	shipment_info status	Container - Old status	Container - New status	Shipment - Old RDDate	Shipment - New RDDate
tn-container-1	new	2021-06-25T14:30:00	2021-06-26T10:00:00	2021-06-25T14:30:00	2021-06-25T14:30:00

Event-1.2

An event from the tracking system is triggered for remaining containers with status=new when the order/shipment is created in the external system. All the containers are updated with status of 1100.70.06.70.1 and Shipment status is not changed. However, Shipment RDD is moved to min(StatusDate) across all 4 containers.

Status

tracking_number	shipment_info status	Container - New status	Shipment - Old status	Shipment - New status
tn-container-1	new	1100.70.06.70.1	1100.70.06.70	1100.70.06.70
tn-container-2	new	1100.70.06.70.1	1100.70.06.70	1100.70.06.70
tn-container-3	new	1100.70.06.70.1	1100.70.06.70	1100.70.06.70
tn-container-4	new	1100.70.06.70.1	1100.70.06.70	1100.70.06.70

Date

tracking_number	shipment_info status	Container - Old status	Container - New status	Shipment - Old RDDate	Shipment - New RDDate
tn-container-1	new	2021-06-25T14:30:00	2021-06-26T10:00:00	2021-06-25T14:30:00	2021-06-25T14:30:00
tn-container-2	new	2021-06-25T14:30:00	2021-06-26T10:00:00	2021-06-25T14:30:00	2021-06-25T14:30:00
tn-container-3	new	2021-06-25T14:30:00	2021-06-26T10:00:00	2021-06-25T14:30:00	2021-06-25T14:30:00
tn-container-4	new	2021-06-25T14:30:00	2021-06-26T10:00:00	2021-06-25T14:30:00	2021-06-26T10:00:00

Event-1.3

When the shipment completes packing, the status is moved to Packed. The tracking system sends an event of ‘Scheduled’ for pickup by the carrier. The Sterling Order Management container status is updated accordingly. There is no change to the shipment status.

Status

tracking_number	shipment_info status	Container - Old status	Container - New status	Shipment - Old status	Shipment - New status
tn-container-1	Scheduled	1100.70.06.70.1	1300.ex.10	1100.70.06.70	No Change
tn-container-2	Scheduled	1100.70.06.70.1	1300.ex.10	1100.70.06.70	No Change
tn-container-3	Scheduled	1100.70.06.70.1	1300.ex.10	1100.70.06.70	No Change
tn-container-4	Scheduled	1100.70.06.70.1	1300.ex.10	1100.70.06.70	No Change

Event-n

When a shipment is confirmed in Sterling Order Management, the status is moved to Shipped. The tracking system sends an event of ‘out_for_delivery’ by the carrier. The Sterling Order Management container status and the shipment status is updated accordingly.

Status

tracking_number	shipment_info status	Container - Old status	Container - New status	Shipment - Old status	Shipment - New status
tn-container-1	out_for_delivery	1300.ex.10	1400.ex.20	1400	No change
tn-container-2	out_for_delivery	1300.ex.10	1400.ex.20	1400	No change
tn-container-3	out_for_delivery	1300.ex.10	1400.ex.20	1400	No change
tn-container-4	out_for_delivery	1300.ex.10	1400.ex.20	1400	1400.ex.20

Event-n+1

Similarly, when the tracking system sends an event with container status of ‘delivered’ for all containers, the shipment is updated for ActualDeliveryDate and the status is moved to ‘Delivered’.

Transaction events

To send the Sterling Order Management Order or Shipment to the external tracking system, the POST REST API calls are triggered based on the following options:

CHANGE_SHIPMENT.ON_SUCCESS – This transaction is triggered several times during the Store flow. So, when IsPackProcessComplete=Y on Container, data can be published. However, no Tracking Number is generated yet but the Container is created and the quantity is packed.
GET_TRACKING_NO.ON_PACKAGE_SUCCESS - This transaction assigns the Tracking Number to the container and the event root element is . The shipment status is retained as ‘Shipment Being Packed’.
CHANGE_SHIPMENT_STATUS.ON_SUCCESS - This transaction is triggered when packing is completed and status is changed to 1300.
CONFIRM_SHIPMENT.ON_SUCCESS – This transaction is triggered after a manifest is created and the shipment is shipped.

Note: Sterling Order Management publishes the order or shipment to the external tracking system only for the HANGE_SHIPMENT_STATUS.ON_SUCCESS option.

API / Service

The following APIs and services are implemented for third-party integration and processing.

IBMExternalDeliveryEvent.acceptEvent() - This API performs basic validations such as the container or order numbers in the event details exist in Sterling Order Management. After successful validation, the event data is posted to a JMS queue.
IBMExternalDeliveryEvent.processEvent() - This API updates the status and statusDate on the container. It retrieves the shipment details for the remaining container records and computes the minimum statuses across all containers. If the minimum status is more than 1400, the shipment status is moved to the Min status. When the shipment status is moved, the RDD is updated with Max(statusDate) on all containers.
IBMExternalDeliveryEvent.publishData() - This API translates the order or shipment details into the external order data and sends it via the REST API call by using their endpoint or authentication key that is configured in Sterling Order Management.

IBMExternalDeliveryEvent.acceptEvent()

Sample API request:

curl --location --request POST 'http://host:9080/smcfs/restapi/executeFlow/IBMExternalDeliveryEvent?_loginid=guest&_token=PE6m4EP5nkAVdH6fR3MovIE5lqAtxUw7KVCN2feRIIeQoMNNIOmAa5UFG4E2OIhi20' \
--header 'Content-Type: application/json' \
--header 'Accept: apptlication/json' \
--header 'Accept-Charset: UTF-8' \
--header 'X-XAPI-Tag: ShipmentEvent' \
--data-raw '{
 "shipment_id": "dd775ac4-f4b2-4b22-8619-3fa3abb75942",
 "carrier_scac": "upsn",
 "carrier_name": "UPS",
 "tracking_number": "1Z961A2R03159781273846",
 "event_type": "exception",
 "bill_of_lading_number": "XP73892",
 "reference_number": "H1234",
 "order_numbers": [
   "W0987"
 ],
 "event_details": {
   "description": "Revised Estimated Delivery Date to 02/16/18 - Later",
   "local_date": "2018-02-14",
   "local_time": "09:48:01",
   "type": "convey_revised_edd_later",
   "utc_offset": "Z",
   "revised_edd": "2018-02-16",
   "original_edd": "2018-02-14"
 },
   "shipment_info": {
   "estimated_delivery_date": "2018-02-16",
   "original_estimated_delivery_date": "2018-02-14",
   "status": "in_transit"
 },
 "delivery_appointment": {
   "delivery_appointment_required": true,
   "delivery_appointment_message": "Delivery appointment message",
   "delivery_appointment_date": "2017-11-07",
   "delivery_appointment_begin_time": "10:00:00",
   "delivery_appointment_end_time": "12:00:00",
   "delivery_appointment_begin_timestamp_info": {
     "local_date":"2017-11-07",
     "local_time":"10:00:00",
     "zone_offset":"+02:00"
    },
   "delivery_appointment_end_timestamp_info": {
     "local_date":"2017-11-07",
     "local_time":"12:00:00",
     "zone_offset":"+02:00"
    },
  "original_delivery_appointment_date": "2017-11-01"
 },
 "created_date_time": "2018-02-14T09:48:01Z"
}'

Sample input document to IBMExternalDeliveryEvent service - The Sterling Order Management framework accepts the above JSON and converts it into the following XML document.

<ShipmentEvent bill_of_lading_number="XP73892" carrier_name="UPS"
    carrier_scac="upsn" created_date_time="2018-02-14T09:48:01Z"
    event_type="exception" reference_number="H1234"
    shipment_id="dd775ac4-f4b2-4b22-8619-3fa3abb75942" tracking_number="1Z961A2R03159781273846">
    <shipment_info estimated_delivery_date="2018-02-16"
        original_estimated_delivery_date="2018-02-14" status="in_transit"/>
    <event_details
        description="Revised Estimated Delivery Date to 02/16/18 - Later"
        local_date="2018-02-14" local_time="09:48:01"
        original_edd="2018-02-14" revised_edd="2018-02-16"
        type="convey_revised_edd_later" utc_offset="Z"/>
    <delivery_appointment delivery_appointment_begin_time="10:00:00"
        delivery_appointment_date="2017-11-07"
        delivery_appointment_end_time="12:00:00"
        delivery_appointment_message="Delivery appointment message"
        delivery_appointment_required="true" original_delivery_appointment_date="2017-11-01">
        <delivery_appointment_end_timestamp_info local_date="2017-11-07"
            local_time="12:00:00" zone_offset="+02:00"/>
        <delivery_appointment_begin_timestamp_info
            local_date="2017-11-07" local_time="10:00:00" zone_offset="+02:00"/>
    </delivery_appointment>
    <order_numbers>W0987</order_numbers>
</ShipmentEvent>

IBMExternalDeliveryEvent.processEvent()

The following APIs are triggered for the Change Shipment and Change Shipment Status APIs, depending on the business scenario.

Input samples:

To change the shipment for container status and date:

<Shipment ShipmentKey="20210629214114392711" >
<Containers>
<Container Status="<mapping of shipment_info.status>" StatusDate="<shipment_info.edd/event_details.local_date>" ShipmentContainerKey="20210630184743393878" />
</Containers>
</Shipment>

To change the shipment status to ‘In Transit’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIPMENT_IN_TRANSIT.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change the shipment status to ‘Out For Delivery’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIPMENT_FOR_DELIVERY.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change the shipment status to ‘Returning To Sender’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIP_RETURNING_TO_SENDER.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change the shipment status to ‘Delivered To Sender’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIP_DELIVERED_TO_SENDER.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change the shipment status to ‘Undeliverable’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIPMENT_UNDELIVERABLE.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change the shipment status to ‘Delivery Unknown’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIP_DELIVERY_CANCELLED.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change the shipment status to ‘Delivery Cancelled’:

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="SHIP_DELIVERY_CANCELLED.0001.ex" AcceptOutOfSequenceUpdates="Y"/>

To change ActualDeliveryDate on shipment:

 <Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" ActualDeliveryDate="<event_details.local_date+time+offset>" />

To change shipment status to 'Delivered':

<Shipment SellerOrganizationCode="Matrix-R" ShipNode="Mtrx_Store_1" ShipmentNo="convey-10" TransactionId="DELIVER_SHIPMENT" AcceptOutOfSequenceUpdates="Y"/>

You can use the following table as a reference to the Transaction ID and statuses.

Transaction ID	Transaction Name	Pickup Statuses	Drop Status
SHIPMENT_IN_TRANSIT.0001.ex	Shipment In Transit	1400	1400.ex.10
SHIPMENT_FOR_DELIVERY.0001.ex	Shipment Out For Delivery	1400, 1400.ex.10	1400.ex.20
SHIP_RETURNING_TO_SENDER.0001.ex	Shipment Returning To Sender	1400, 1400.ex.10, 1400.ex.20	1400.ex.30
SHIP_DELIVERED_TO_SENDER.0001.ex	SHIP_DELIVERED_TO_SENDER.0001.ex	1400, 1400.ex.10, 1400.ex.20	1400.ex.40
SHIPMENT_UNDELIVERABLE.0001.ex	Shipment Undeliverable	1400, 1400.ex.10, 1400.ex.20	1400.ex.80
SHIP_DELIVERY_UNKNOWN.0001.ex	Shipment Delivery Unknown	1400, 1400.ex.10, 1400.ex.20	1400.ex.85
SHIP_DELIVERY_CANCELLED.0001.ex	Shipment Delivery Cancelled	1400, 1400.ex.10, 1400.ex.20	1400.ex.99
DELIVER_SHIPMENT	Deliver Shipment	1400, 1400.ex.10, 1400.ex.20	1500

IBM services

You must create the following custom services for the integration to work. Refer to the IBM Sterling Order Management documentation for defining new service

IBMExternalDeliveryEvent - This service calls the IBMExternalDeliveryEvent.acceptEvent() API and places a message in a JMS queue.
ProcessExternalDeliveryEvent - This service processes data from a JMS queue and calls the IBMExternalDeliveryEvent.processEvent() API.
SentShipmentForTracking - This service is called on the PACK_SHIP_ON_SUCCESS action as part of the store GET_TRACKING_NO transaction. It writes to a JMS queue.
PublishShipmentDataService - This service reads new messages on the JMS queue when packaging is successful and calls the PublishShipmentDataAPI service.
PublishShipmentDataAPI - This service retrieves the shipment details and calls IBMExternalDeliveryEvent.publishData().

Deploying code

You must first download the sample code from this Git project using the "Download Zip" option of GitHub. Compile the java source code from the src folder and create a .jar file. Deploy the .jar file as a customization to your IBM Sterling Order Management environments. If there are existing customizations, you must merge the sample code with the existing customization before deploying the code. Refer to the IBM Sterling Order Management documentation for details about managing customization. You must copy the files folder into the <runtime_sandbox>/extensions folder and update the resources.jar. For more details about updating the resources.jar refer to building resource extensions in IBM Sterling Order Management documentation.

Configuring Sterling Order Management

You must complete the following configurations to enable the integration. You can use the Configuration Deployment Tool to deploy your configurations from your Sterling Order Management master configuration to other environments. Refer to the IBM Sterling Order Management documentation for details about mananaging configuration deployment tool

Configuring Carriers

You must configure carriers in the system for the IBM Sterling Order Management and Convey integration to work successfully. Refer to the IBM Sterling Order Management documentation for details about the carrier setup. You must also setup the Carrier Adaptor for new carriers.

Configuring User Exit implementation for IBM Sterling Store Engagement

Refer to the IBM Sterling Order Management documentation for details about configuring the tracking number generation option for the IBM Sterling Store Engagement application. This integration uses the IBMDemoShipCartonUEImpl single store exit to generate tracking numbers.

Configuring extended status

You must create the following extended statuses. Refer to the IBM Sterling Order Management documentation for details about configuring [extended status] (https://www.ibm.com/docs/en/order-management?topic=statuses-creating-extended-status).

ProcessType	Base Status	Status	StatusName
ORDER_DELIVERY	1300(Shipment Packed)	1300.ex.10	Delivery Scheduled
ORDER_DELIVERY	1300(Shipment Packed)	1300.ex.20	Carrier Pickup Appointment
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.10	In Transit
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.20	Out For Delivery
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.30	Returning To Sender
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.40	Delivered To Sender
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.80	Undeliverable
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.85	Delivery Unknown
ORDER_DELIVERY	1400(Shipment Shipped)	1400.ex.99	Delivery Cancelled
ORDER_DELIVERY	1100.70.06.70(Shipment Being Packed)	1100.70.06.70.1	Shipment Created In External
ORDER_DELIVERY	1100.70.06.70(Shipment Being Packed)	1100.70.06.70.2	Carrier Price Quoted

Configuring Transactions

You must create the following extended transactions derived from abstract transaction. Refer to the IBM Sterling OMS Management documentation for details about creating [extended transactions] (https://www.ibm.com/docs/en/order-management?topic=dt-creating-extended-transaction-that-is-derived-from-abstract-transaction).

Transaction Type	Transaction ID	Transaction Name	Pickup Status	DropStatus
Derived from Change Shipment status abstract Transaction	SHIPMENT_IN_TRANSIT.0001.ex	Shipment In Transit	1400(Shipment Shipped)	1400.ex.10(In Transit)
Derived from Change Shipment status abstract Transaction	SHIPMENT_FOR_DELIVERY.0001.ex	Shipment Out For Delivery	1400(Shipment Shipped),1400.ex.10(In Transit)	1400.ex.20(Out For Delivery)
Derived from Change Shipment status abstract Transaction	SHIP_RETURNING_TO_SENDER.0001.ex	Shipment Returning To Sender	1400(Shipment Shipped),1400.ex.10(In Transit),1400.ex.20(Out For Delivery)	1400.ex.30(Returning To Sender)
Derived from Change Shipment status abstract Transaction	SHIP_DELIVERED_TO_SENDER.0001.ex	Shipment Delivered To Sender	1400(Shipment Shipped),1400.ex.10(In Transit),1400.ex.20(Out For Delivery)	1400.ex.40(Delivered To Sender)
Derived from Change Shipment status abstract Transaction	SHIPMENT_UNDELIVERABLE.0001.ex	Shipment Undeliverable	1400(Shipment Shipped),1400.ex.10(In Transit),1400.ex.20(Out For Delivery)	1400.ex.80(Undeliverable)
Derived from Change Shipment status abstract Transaction	SHIP_DELIVERY_UNKNOWN.0001.ex	Shipment Delivery Unknown	1400(Shipment Shipped),1400.ex.10(In Transit),1400.ex.20(Out For Delivery)	1400.ex.85(Delivery Unknown)
Derived from Change Shipment status abstract Transaction	SHIP_DELIVERY_CANCELLED.0001.ex	Shipment Delivery Cancelled	1400(Shipment Shipped),1400.ex.10(In Transit),1400.ex.20(Out For Delivery)	1400.ex.99(Delivery Cancelled)

Configuring Services

Refer to the IBM Sterling Order Management documentation for details about configuring Services. Create services with the following details.

Create the IBMExternalDeliveryEvent service with the following details.

Service Name	Service Group name	Asyn/sync mode
IBMExternalDeliveryEvent	IBM Delivery Integration	Synchronous Mode

Components of IBMExternalDeliveryEvent service 1.1. API Component

Type	API Name	Class Name	Method Name
Extented Api	acceptEvent	com.ibm.convey.integration.demo.business.IBMExternalDeliveryEventService	acceptEvent

1.2. JMS Queue Component

Name	Value
Destination Name	${yfs.convey.integration.event.external.queue}
Time To Live(seconds)	0
Provider URL	${yfs.convey.integration.providerurl}
Initial Context Factory	File
Connection Factory	${yfs.convey.integration.qcf}
Persistent/Non Persistent	Persistent
Commit Message	Check

Create the ProcessExternalDeliveryEvent service with the following details.

Service Name	Service Group name	Asyn/sync mode
ProcessExternalDeliveryEvent	IBM Delivery Integration	Asynchronous Mode

Components of ProcessExternalDeliveryEvent service

2.1. JMS Queue Component

Name	Value
Sub Service Name	ProcessExternalDeliveryEvent
Destination Name	${yfs.convey.integration.event.external.queue}
Provider URL	${yfs.convey.integration.providerurl}
Initial Context Factory	File
Connection Factory	${yfs.convey.integration.qcf}
Transactional/Non Transactional	Transactional
Initial Threads	1

Server tab Create an integration server with the IBMDeliveryIntegration name and select IBMDeliveryIntegration as the server.

Exception tab

Name	Value
Alert Type	Delivery_Integration_Exception
Alert Queue Name	DEFAULT
Is Reprocessible	checked

2.2. API Component

Type	API Name	Class Name	Method Name
Extented Api	processEvent	com.ibm.convey.integration.demo.business.IBMExternalDeliveryEventService	processEvent

Create the PublishShipmentDataAPI service with the following details.

Service Name	Service Group name	Asyn/sync mode
PublishShipmentDataAPI	IBM Delivery Integration	Synchronous Mode

Components of PublishShipmentDataAPI service

3.1. API Component

Type	API Name	Class Name	Method Name
Standard Api	getShipmentDetails

3.2. XSL Translator

Name	Value
XSL Name	template/service/xsl/TransformOrderXmlToExternalOrderJson.xsl

3.3. API Component

Type	API Name	Class Name	Method Name
Extented Api	publishData	com.ibm.convey.integration.demo.business.IBMExternalDeliveryEventService	publishData

Create the PublishShipmentDataService service with the following details.

Service Name	Service Group name	Asyn/sync mode
PublishShipmentDataService	IBM Delivery Integration	Asynchronous Mode

Components of PublishShipmentDataService service

4.1. JMS Queue Component

Name	Value
Sub Service Name	PublishShipmentDataService
Destination Name	${yfs.convey.integration.event.onsuccess.queue}
Provider URL	${yfs.convey.integration.providerurl}
Initial Context Factory	File
Connection Factory	${yfs.convey.integration.qcf}
Transactional/Non Transactional	Transactional
Initial Threads	1

Server tab Create an integration server with the IBMDeliveryIntegration name and select IBMDeliveryIntegration as the server.

Exception tab

Name	Value
Alert Type	Delivery_Integration_Exception
Alert Queue Name	DEFAULT
Is Reprocessible	checked

4.2. API Component

Type	API Name	Class Name	Method Name
Extented Api	InvokeService	com.yantra.ibmjda.business.integration.IBMJDAInvokeIntegrationService	InvokeService

Create the SendShipmentForTracking service with the following details.

Service Name	Service Group name	Asyn/sync mode
SendShipmentForTracking	IBM Delivery Integration	Synchronous Mode

Components of SendShipmentForTracking service

5.1. JMS Queue Component

Name	Value
Destination Name	${yfs.convey.integration.event.onsuccess.queue}
Time To Live(seconds)	0
Provider URL	${yfs.convey.integration.providerurl}
Initial Context Factory	File
Connection Factory	${yfs.convey.integration.qcf}
Persistent/Non Persistent	Persistent
Commit Message	Check

Configuring Conditions

You must create the following condition. Refer to the IBM Sterling Order Management documentation for details about [configuring conditions] (https://www.ibm.com/docs/en/order-management?topic=conditions-creating-condition).

ProcessTypeKey	ConditionName	ConditionID	ConditonGroup	ConditionType	ConditoinValue
ORDER_DELIVERY	Is Packed	Is Packed	Store	Static	Status Is '1300'

Configuring Action

You must create the following action. Refer to the IBM Sterling Order Management documentation for details about [configuring actions] (https://www.ibm.com/docs/en/order-management?topic=node-defining-actions).

Action Code	Action Name	Action Group
PACK_SHIP_ON_SUCCESS	Send Shipment On Pack Complete	Delivery Track Integration

Check Invoke following services as part of this action and include the following services.

Service name	Service Group
SendShipmentForTracking	IBM Delivery Integration

Configuring Events

Refer to the IBM Sterling Order Management documentation for details about configuring events.

Configure the ON_SUCCESS event of PACK_SHIPMENT_COMPLETE transaction under the ORDER_DELIVERY process type with the created condition and action.

2.Configure the GET_TRACKING_NO_SUCCESS event of GET_TRACKING_NO_SUCCESS transaction under the Manifesting process type with the created action.

Configuring Properties

You must create the following properties. Refer to the IBM Sterling OMS Management documentation for details about creating properties from SMA.

Category	Property Name	Property Type	Date Type	Modifiable	Modifiable at Runtime	User Overridable	Server Overridable	Description
yfs	yfs.convey.integration.providerurl	CUSTOM	String	Y	Y	N	N	convey integration providerurl
yfs	yfs.convey.integration.qcf	CUSTOM	String	Y	Y	N	N	convey integration qcf
yfs	yfs.convey.integration.event.onsuccess.queue	CUSTOM	String	Y	Y	N	N	convey integration queue
yfs	yfs.convey.integration.event.external.queue	CUSTOM	String	Y	Y	N	N	convey integration queue
yfs	yfs.convey.integration.publish.url	CUSTOM	String	Y	Y	N	N	convey integration queue
yfs	yfs.convey.integration.publish.auth.key	CUSTOM	String	Y	Y	N	N	convey integration queue
yfs	yfs.convey.integration.pvft.tracking.number.last.used	CUSTOM	String	Y	Y	N	N	convey integration carrier pvft tracking number last used

Testing Convey integration

When a shipment is confirmed as packed, a message is sent to the https://api.getconvey.com/order/v1/order Convey API along with order details. To verify if the order is communicated to Convey, you can issue the corresponding GET method:

curl --location --request GET 'https://api.getconvey.com/order/v1/order/results?client_request_id=<REPLACE_OMS_ORDER_NO>'
--header 'Content-Type: application/json'
--header 'Accept: application/json'
--header 'Authorization: Basic MjYzYWEY2YtZWRlt0NTdkLWFad3mVlYzg5NWJmF3mOg=='

Response: { "success": true, "result": [ { "id": "ccaa369f-db49-313b-bb7d-249afcaec45e", "messages": [ { "log_level": "debug", "message_code": "ORD105", "message": "Created order." } ], "status": "ORDER_PIPELINE_COMPLETE", "request_id": "b1aa5b27-377e-44b9-aee8-171139cfcb49", "client_request_id": "OM1000005" } ] }

After Convey has received the order information, a call back is simulated to Sterling Order Management to update the shipment status changes. You can use one of the following ways to simulate a call back:

If Convey is integrated to Sterling Order Management, then you can call APIs on Convey by simulating the PVFT carrier. Convey, in turn, calls Sterling Order Management to update the status.
If you do not have Convey integrated to call Sterling Order Management yet, you can directly call the Sterling Order Management APIs to update status. Here are the examples when you do not have Convey integrated to call Sterling Order Management.

Set package is 'in_transit':

curl --location --request POST 'https://<REPLACE_OMS_IP>:9443/smcfs/restapi/executeFlow/IBMExternalDeliveryEvent'
--header 'X-XAPI-Tag: ShipmentEvent'
--header 'Content-Type: application/json'
--data-raw '{ "tracking_number": "PT0000110056", "event_type": "tracking", "shipment_info": { "estimated_delivery_date": "2021-07-31", "status": "in_transit" } }'

Set package is 'out_for_delivery':

curl --location --request POST 'https://<REPLACE_OMS_IP>:9443/smcfs/restapi/executeFlow/IBMExternalDeliveryEvent'
--header 'X-XAPI-Tag: ShipmentEvent'
--header 'Content-Type: application/json'
--data-raw '{ "tracking_number": "PT0000110056", "event_type": "tracking", "shipment_info": { "estimated_delivery_date": "2021-07-31", "status": "out_for_delivery" } }'

Set package is 'delivered':

curl --location --request POST 'https://<REPLACE_OMS_IP>:9443/smcfs/restapi/executeFlow/IBMExternalDeliveryEvent'
--header 'X-XAPI-Tag: ShipmentEvent'
--header 'Content-Type: application/json'
--data-raw '{ "event_type": "tracking", "tracking_number": "PT0000110056", "shipment_info": { "estimated_delivery_date": "2021-07-31", "status": "delivered" }, "event_details": { "description": "Your Shipment has been delivered", "local_date": "2021-07-31", "local_time": "10:50:01", "utc_offset": "Z", "revised_edd": "2021-07-31", "original_edd": "2021-07-27" } }'

Extending Order Hub to add new fields

The integration maps IBM Sterling Order Management containers to Convey shipments. In Order Hub, by default, the following three fields are not available under the Shipment containers field for orders. You can add these fields as shown in the following image:

View this page for more detailed instructions about Order Hub field customization.

Download the customization repository as referenced in the above link.
Create a buc-table-config.json file to specify the new fields for mapping. The file contains your delta changes.

{
    "ord-detail-shipment-container-table": {
        "headers": [
            {
                "id": "estimatedDeliveryDate",
                "name": "Estimated delivery date",
                "sortKey": "StatusDate",
                "formatter": {
                  "type": "dateTime",
                  "value": "StatusDate"
                },
                "default": true,
                "sequence": 4
            },
            {
                "id": "containerStatus",
                "name": "Container status",
                "sortKey": "ExternalReference1",
                "dataBinding": "ExternalReference1",
                "default": true,
                "sequence": 5
            },
            {
                "id": "containerStatusValue",
                "name": "Status value",
                "dataBinding": "Status",
                "default": false,
                "sequence": 6
            }
        ]
    }
}

Pull the latest getPage-templates.json file from an Order Hub instance.
Customize the template in getPage-templates.json, which specifies what data to pull from Sterling Order Management. Add the three new fields to the getShipmentList template. Your file must contain only the template that you are updating and not all the templates, and must contain similar entries as listed here:

{
"getShipmentList": {
    "default": {
      "Shipments": {
        "Shipment": [
          {
            "ActualShipmentDate": "",
            "BuyerOrganizationCode": "",
            "SellerOrganizationCode": "",
            "CarrierServiceCode": "",
            "ExpectedShipmentDate": "",
            "ReceivingNode": "",
            "PickticketNo": "",
            "SCAC": "",
            "ScacAndService": "",
            "ScacAndServiceKey": "",
            "ShipMode": "",
            "ShipNode": "",
            "ShipmentKey": "",
            "ShipmentNo": "",
            "isHistory": "",
            "GiftFlag": "",
            "ServiceLine": {
              "ItemGroupCode": ""
            },
            "Status": {},
            "Containers": {
              "Container": {
                "ContainerNo": "",
                "CarrierServiceCode": "",
                "SCAC": "",
                "ShipDate": "",
                "ShipmentContainerKey": "",
				
				"Status": "",
				"ExternalReference1": "",
				"StatusDate": "",
				
                "ShipmentKey": "",
                "TrackingNo": "",
                "ContainerDetails": {
                  "ContainerDetail": [
                    {
                      "ItemID": "",
                      "OrderLineKey": "",
                      "ProductClass": "",
                      "Quantity": "",
                      "UnitOfMeasure": "",
                      "ShipmentLineKey": ""
                    }
                  ]
                }
              }
            },
            "ShipmentLines": {
              "ShipmentLine": {
                "ItemID": "",
                "OrderHeaderKey": "",
                "OrderLineKey": "",
                "OrderNo": "",
                "PrimeLineNo": "",
                "ProductClass": "",
                "Quantity": "",
                "ShipmentLineKey": "",
                "ShipmentLineNo": "",
                "SubLineNo": "",
                "UnitOfMeasure": ""
              }
            }
          }
        ]
      }
    },
    "search": {
      "Shipments": {
        "TotalNumberOfRecords": "",
        "Shipment": [
          {
            "ActualDeliveryDate": "",
            "ActualShipmentDate": "",
            "BolNo": "",
            "BuyerOrganizationCode": "",
            "CarrierServiceCode": "",
            "Containers": {
              "Container": {
                "TrackingNo": ""
              }
            },
            "DeliveryPlanKey": "",
            "DeliveryPlanNo": "",
            "EnterpriseCode": "",
            "ExpectedDeliveryDate": "",
            "ExpectedShipmentDate": "",
            "IsTagSerialRequested": "",
            "HoldFlag": "",
            "OrderNo": "",
            "OrderHeaderKey": "",
            "PackAndHold": "",
            "ProNo": "",
            "ReceivingNode": "",
            "ReleaseNo": "",
            "SCAC": "",
            "SellerOrganizationCode": "",
            "ShipMode": "",
            "ShipNode": "",
            "ShipmentKey": "",
            "ShipmentNo": "",
            "TotalVolume": "",
            "TotalVolumeUOM": "",
            "TotalWeight": "",
            "TotalWeightUOM": "",
            "TrackingNo": "",
            "TrailerNo": "",
            "ShipmentLines": {
              "ShipmentLine": {
                "ItemID": "",
                "OrderHeaderKey": "",
                "OrderLineKey": "",
                "OrderNo": "",
                "PrimeLineNo": "",
                "ProductClass": "",
                "Quantity": "",
                "ShipmentLineKey": "",
                "ShipmentLineNo": "",
                "SubLineNo": "",
                "UnitOfMeasure": "",
                "OrderLine": {
                  "ReceivingNode": "",
                  "ShipNode": ""
                }
              }
            },
            "ScacAndService": {
              "ScacAndServiceDesc": ""
            },
            "ToAddress": {
              "City": "",
              "Country": "",
              "State": "",
              "ZipCode": ""
            },
            "Status": {
              "Description": "",
              "ProcessTypeKey": "",
              "Status": "",
              "StatusKey": "",
              "StatusName": ""
            },
            "ShipmentHoldTypes": {
              "ShipmentHoldType": {
                "HoldType": "",
                "ReasonText": "",
                "Status": ""
              }
            }
          }
        ]
      }
    }
  }
}

Upload the files to the Order Hub servers to view the changes immediately.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
FactorySetUp		FactorySetUp
files/extensions/global/template		files/extensions/global/template
src/com/ibm/convey/integration/demo		src/com/ibm/convey/integration/demo
LICENSE		LICENSE
README.md		README.md
om-functional.properties		om-functional.properties

License

IBM/oms-convey-integration

Folders and files

Latest commit

History

Repository files navigation

IBM Sterling Order Management Integration to Convey

Overview

Prerequisites

Integration

Order process

Shipment status mapping

Inbound event attribute mapping

Tracking events

Sterling Order Management properties

Example for event tracking

Event-1.1

Event-1.2

Event-1.3

Event-n

Event-n+1

Transaction events

API / Service

IBMExternalDeliveryEvent.acceptEvent()

IBMExternalDeliveryEvent.processEvent()

IBM services

Deploying code

Configuring Sterling Order Management

Configuring Carriers

Configuring User Exit implementation for IBM Sterling Store Engagement

Configuring extended status

Configuring Transactions

Configuring Services

Configuring Conditions

Configuring Action

Configuring Events

Configuring Properties

Testing Convey integration

Extending Order Hub to add new fields

About

Resources

License

Stars

Watchers

Forks

Languages