Generic Order Transaction History API

Purpose: Use the Order Transaction History API to receive order transaction records for a specified order, based on XML messages from an external system, such as a warehouse management system. You can review the order transaction history records created on the Display Order History Screen.

In this chapter:

• Order Transaction History API Setup

• Order Transaction History API Process

• Order Transaction History Message: Sample XML

• Order Transaction History Message (CWOrderTransactionHistory)

Order Transaction History API Setup

Before you can use the Order Transaction History API, you must perform the necessary setup.

CWServiceIn web service: The CWServiceIn web service allows an external system to post the Order Transaction History Message (CWOrderTransactionHistory) directly to Order Management System and receive responses without the need of any queues.

Web service authentication? Use the Working with Web Service Authentication (WWSA) menu option to define a valid user for basic web service authentication.

To use the CWServiceIn web service, you must define the endpoint:

If you are using the CWServiceIn RESTful web service: You POST inbound CWServiceIn messages to the web service’s URI, or endpoint, of the RESTful service. The individual URL for the CWServiceIn RESTful service uses the following format: http://server:port/SerenadeSeam/sxrs/application/CWServiceIn, where server:port identifies the application server where the RESTful service is located and CWServiceIn is the name of the web service to call.

If you are using the CWServiceIn SOAP-based web service: The endpoint specified in the CWServiceIn.wsdl file is where you need to post messages in order for the CWServiceIn web service to process them. The endpoint is typically set to http://server:port/CWDirectCPService/services/CWServiceIn, where server:port identifies the application server where the wsdl is located and CWServiceIn is the name of the web service to call.

The CWServiceIn SOAP-based web service requires the inbound messages be embedded in SOAP envelope tags. A sample XML message embedded in a SOAP envelope is presented below.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:dom="http://dom.w3c.org">

<soapenv:Header />

<soapenv:Body>

<dom:performAction type="xsd:string">

<![CDATA[

 

<Message source="WMS" target="CWSerenade" type="CWOrderTransactionHistory" resp_qmgr="" resp_q="" >

<CWOrderTransactionHistorys>

<CWOrderTransactionHistory company_code="7" order_number="3968" ship_to_number="1" trans_date="101112" trans_text="KAB" dollar_amt="10.11"/>

</CWOrderTransactionHistorys>

</Message>

 

]]>

</dom:performAction>

</soapenv:Body>

</soapenv:Envelope>

Order Transaction History API Process

You can use the Order Transaction History API to create order transaction history for a specified order. The steps are:

1.	An external system sends an Order Transaction History Message (CWOrderTransactionHistory) to Order Management System using the CWServiceIn web service.
2.	Order Management System receives the message and writes the message to the MQ Log if its Logging Level is set to INFO or lower.
3.	Order Management System determines if the XML message is well formed. • If the XML message is not well formed, the system returns a simple response with the error Invalid XML Message and does not perform any further updates; see Order Transaction History API Errors. • If the XML message is well formed, the system continues to the next step.
4.	Order Management System determines if any errors exist in the Order Transaction History Message (CWOrderTransactionHistory). • If an error exists in the message, the system returns a simple response with a description of the error and does not perform any updates. See Order Transaction History API Errors. • If an error does not exist in the message, the system creates records in the Order Transaction History table and returns a simple response of OK. You can review the order transaction history records created on the Display Order History Screen. For each order transaction history record created, the system defaults USER DEFINED (Z) to the Transaction type field.

Order Transaction History API Errors

If the Order Transaction History Message (CWOrderTransactionHistory) contains an error, the system returns a simple response with a description of the error.

Error Message	Reason For Error
Invalid XML Message	The Order Transaction History Message (CWOrderTransactionHistory) is not a well formed XML message.
Invalid Target: com.mr.serenade.exception.BOException: MessageInBO.getQueues - Target CWSerenade does not match inbound job name	The web service used to post the Order Transaction History Message (CWOrderTransactionHistory) directly to Order Management System is not set up correctly; see Order Transaction History API Setup.
Invalid XML Message: ERROR: Company, Order, or Ship to combination is not found	The company_code, order_number, and ship_to_number combination in the Order Transaction History Message (CWOrderTransactionHistory) is invalid.

Order Transaction History Message: Sample XML

A sample of the Order Transaction History Message (CWOrderTransactionHistory) is presented below.

<Message source="SYS" target="CWSerenade" type="CWOrderTransactionHistory" resp_qmgr="" resp_q="">

<CWOrderTransactionHistorys>

<CWOrderTransactionHistory company_code="7" order_number="3968" ship_to_number="1" trans_date="11152011" trans_text="SLBL USPS#1234567890" dollar_amt="10.11" />

<CWOrderTransactionHistory company_code="7" order_number="3968" ship_to_number="1" trans_date="11152011" trans_text="SLBL INTRNL#9801234756" dollar_amt="" />

</CWOrderTransactionHistorys>

</Message>

Successful Response: If the Order Transaction History message is well formed and contains valid data, Order Management System creates a record in the Order Transaction History table for each OrderTransactionHistory element passed in the message and returns a simple response of OK.

Error Response: If an error exists in the Order Transaction History message, the system returns a simple response with a description of the error and does not perform any further updates. For example: Invalid XML Message: ERROR: Company, Order, or Ship to combination is not found

Order Transaction History Message (CWOrderTransactionHistory)

 

Order Management System receives and processes this message to create order transaction history records for an order. See Order Transaction History API Process for processing details.

Sample message: See Order Transaction History Message: Sample XML.

Name	Type	Length	Comments
Message One Message element is required.
source	alpha	25	The source of the XML message. Informational only.
target	alpha	25	The target of the XML message, such as OROMS. Informational only.
type	alpha	25	CWOrderTransactionHistory indicates the message is an Order Transaction History message.
resp_qmgr	alpha	25	Informational only.
resp_q	alpha	25	Informational only.
CWOrderTransactionHistory One or more CWOrderTransactionHistory elements are required.
company_code	numeric	3	Required. A code for the company where the order associated with the order transaction history record exists. Updates Company in the Order Transaction History table.
order_number	numeric	8	Required. The order number associated with the order transaction history record. Updates Order # in the Order Transaction History table.
ship_to_number	numeric	3	Required. The order ship to number associated with the order transaction history record. Updates Ship to # in the Order Transaction History table.
trans_date	numeric	7	Optional. MMDDYYYY format; translated to CYYMMDD format in the database. The date when the order activity occurred. If a date is not passed or it is invalid, the system defaults the current date. Updates Date in the Order Transaction History table.
trans_text	alpha	40	Optional. A description of the activity related to the transaction. Updates Transaction note in the Order Transaction History table.
dollar_amt	numeric	9.2	Optional. The dollar amount associated with the order activity. If a dollar amount is not passed or it is invalid, the system defaults 0. Updates Dollar amount in the Order Transaction History table.