3 External Order Framework

The External Order Framework leverages several key components to interact with an External Order System. Figure 3-1 illustrates the interaction of these components to look up Siebel orders from a Point-of-Service client workstation.

Figure 3-1 External Order Interaction

This section provides details about the APIs and configurations enabling Point-of-Service to query and update Siebel orders.

External Order Manager

ExternalOrderManager class is a ServiceManager class that exposes an ExternalOrder-specific API into the Point-of-Service client code. This manager is configured to talk to a general-purpose ConnectorTechnician.

The manager includes the following APIs that are invoked by the Point-of-Service client to query orders or change an order status by locking, cancelling, or rejecting the order:

Example 3-1 External Order Manager APIs

/**
* Query for external orders based on the search criteria
* @param criteria the external order search criteria
* @return a list of external orders
* @throws ExternalOrderException
*/
List<ExternalOrderIfc> query(ExternalOrderSearchCriteriaIfc criteria) throws
ExternalOrderException;
/**
* Lock the external order so that it will not be available for other
Point-of-Service clients to process
* @param orderId the external order id
* @throws ExternalOrderException
*/
void lock(String orderId) throws ExternalOrderException;
/**
* Cancel the external order so that it will be available for Point-of-Service
clients to process
* @param orderId the external order id
* @throws ExternalOrderException
*/
void cancel(String orderId) throws ExternalOrderException;

ConnectorTechnician

The ConnectorTechnician is configured to talk to the COMMEXT components that are used by the External Order Lookup flow (query Siebel orders).

The configuration file for the ConnectorTechnician is DefaultConnectorTechnician.xml under <source_directory>\applications\pos\deploy\server\config\technician.

The External Order Lookup flow uses a simple set of routes configured with formatters that know Siebel's message formats and a general purpose web service connector configured to talk with Siebel's exposed service. Each route is a specific message to the Siebel system to find, lock, cancel, or reject an order.

These routes do not provide guaranteed delivery as it is not required for these interactions. The routes, web service connector, and the formatters that are used by the query flow are configured in the DefaultConnectorTechnician.xml.

Figure 3-2 Query External Order Routes

Retail Transaction Technician

RetailTransactionTechnician is responsible for updating the external order system after an order has been tendered in the Point-of-Service system. Besides updating the external order system (based on the response after update), the Point-of-Service database is updated with the order details.

In the ExternalOrderUpdate flow, the COMMEXT framework components are used to update a Siebel external order once the transaction has been funded. The existing DataManager class is configured to talk to the RetailTransactionTechnician class that knows how to save a Point-of-Service transaction object and then access various COMMEXT routes configured for post-save communications. This enables multiple systems to be notified once a transaction has been completed. For Siebel, after the transaction is persisted, the message is forwarded to the Siebel routes to see if there is an embedded External Order object in the transaction. If so, the Siebel routes extract that order object through the formatter and turn its information into the appropriate messages for the Siebel web service. The message is then sent to Siebel using a specialized web service connector.

To facilitate guaranteed delivery, a chained-connector is introduced to catch connection errors. In the event an error occurs, these connectors catch that error and leave the message in the queue for later delivery.

The configuration file for the RetailTransactionTechnician where all the COMMEXT components used by the External Order Update flow are defined is RetailTransactionTechnician.xml under <pos server install>/pos/config/technician.

Figure 3-3 Update External Order Routes

The starting point in the configuration is persisting the transaction to a Point-of-Service database:

<MSGROUTER type="PERSIST_TO_DB" rule="StopOnErrorRule">
<MSGCONNECTOR connector="SaveTransactionsToDatabaseConnector"
formatter="PassThroughFormatter" />
<MSGCONNECTOR connector="SaveTransactionsToFileConnector"
formatter="TransactionDataFormatter"/>
</MSGROUTER>

After the transaction is persisted to the database, the transaction is written to DefaultTrnFileQueue.queue:

<CHAINED_CONNECTOR name="SaveTransactionsToFileConnector"
javaclass="oracle.retail.stores.commext.connector.queued.FileQueueConnector"
connector="MulticastQueuedTransactions">
<PROPERTY propname="queueFileName"
propvalue="DefaultTrnFileQueue"/>
<PROPERTY propname="queueMonitorInterval" propvalue="30000"/>
<PROPERTY propname="executionInterval" propvalue="1000"/>
</CHAINED_CONNECTOR>

A multicast connector listening to these messages distributes the transaction to all integrated external systems:

<!-- WebService Connectors MulticastConnector. After persisting txn to
database, it is given to the below integration points -->
<CONNECTOR name="MulticastQueuedTransactions"
javaclass="oracle.retail.stores.commext.connector.multicast.ThreadedMulticastConnector">
<!-- Begin PSI
<PROPERTY propname="msgTypes" propvalue="FILTER_PSI_TRANSACTIONS"/>
End PSI -->
<!-- Begin Siebel -->
<PROPERTY propname="msgTypes" propvalue="FILTER_SIEBEL_
TRANSACTIONS"/>
<!-- End Siebel -->
<!-- Begin BillPay
<PROPERTY propname="msgTypes" propvalue="FILTER_BILL_PAY_
TRANSACTIONS"/>
End BillPay
 
</CONNECTOR>

For Siebel integration, the message type is FILTER_SIEBEL_TRANSACTIONS. This is the starting point before communicating to the Siebel system:

The message is passed to a SiebelTransactionsFilterConnector where messages are filtered based on defined criteria. The criteria is defined in ExternalOrderTransactionFilterConfig.xml.
After the transaction is marked eligible for updating Siebel, a connector (SaveTransToFileForSiebel) is called that is responsible for writing the transaction to a file queue named SiebelTrnFileQueue.
The SaveTransToFileForSiebel connector calls the UPDATE_SIEBEL message type.
UPDATE_SIEBEL message router formats the message using formatter SiebelOrderFundedFormatter.
The message is given to the FundSiebelOrderConnector. FundSiebelOrderConnector is a chained connector. This connector is responsible for queueing the message to FundSiebelOrderQueue, from which the message is passed to the Siebel system by invoking SiebelWebService.
After getting a response from Siebel with no errors, the message is given to the UPDATE_SIEBEL_PAYMENT, SIEBEL_SYNCH_DB message routers:
- UPDATE_SIEBEL_PAYMENT: This route is responsible for updating the payments in the Siebel system.
- SIEBEL_SYNCH_DBL: This route is responsible for updating the Point-of-Service database.
During the Siebel update process, if there are any errors, the errors are written to a log file using LoggerConnector.

Formatters

Formatters are responsible for formatting requests and translating responses, during communication between Point-of-Service and Siebel. Each formatter has a pair of methods, formatConnectorMessage and translateConnectorResponse, that are called to perform a function.

Formatters enlisted in direct communication with Siebel translate data between Point-of-Service domain objects and WSDL-generated Siebel web service objects. For internationalization (I18N) support, the Siebel Formatters communicate using Language Independent Code (LIC) values.

The following tables describe the functions and properties of the major formatters leveraged during communication between Point-of-Service and Siebel.

Siebel Query Formatter

Table 3-1 shows the method functionality for oracle.retail.stores.formatter.siebel.QueryFormatter.

Table 3-1 Siebel Query Formatter Method Functionality

formatConnectorMessage	translateConnectorResponse
Request order data from Siebel. Based on search criteria, either Order Header or Order Detail is requested.	Convert Siebel Order Data into Point-of-Service External Orders.

Table 3-2 shows the configuration properties for the <pos server install>/pos/config/technician/DefaultConnectorTechnician.xml configuration file.

Table 3-2 Siebel Query Formatter Configuration Properties

Configuration Property	Purpose
myStoreUserID	User ID for Siebel user with limited order visibility.
myStorePassword	Password for Siebel user with limited order visibility.
globalUserID	User ID for Siebel user with global order visibility.
globalPassword	Password for Siebel user with global order visibility.
securityType	Security model used by Siebel web service. Must be either Siebel or WS-Security.
endPointUrl	Siebel web service endpoint URL.
timeOutInSeconds	Siebel web service time out in seconds.
maxLineItems	Maximum number of order line items requested in order detail.
myStoreViewMode	Siebel View Mode used for limited order visibility.
globalViewMode	Siebel View Mode used for global order visibility.
sellActionCode	Siebel action code for sell items.
returnActionCode	Siebel action code for return items.
supportedOrderTypes	Siebel Order Types to be included in search results. If more than one order type is desired, types should be delimited by comma.

Siebel Status Update Formatter

Table 3-3 shows the method functionality for oracle.retail.stores.formatter.siebel.StatusUpdateFormatter.

Table 3-3 Siebel Status Update Formatter Method Functionality

formatConnectorMessage	translateConnectorResponse
Request update to the status of a Siebel Order.	Validate IDs in response matches the IDs from request.

Table 3-4 shows the configuration properties for the <pos server install>/pos/config/technician/DefaultConnectorTechnician.xml configuration file.

Table 3-4 Siebel Status Update Formatter Configuration Properties

Configuration Property	Purpose
userID	User ID for Siebel user with global order visibility.
password	Password for Siebel user with global order visibility.
function	Purpose of status change. Possible values are Lock, Cancel, and Reject. The status text mapped to each function can be found in `<pos server install>/pos/config/ExternalOrderMapping.xml`.
securityType	Security model used by Siebel web service. Must be either Siebel or WS-Security.
endPointUrl	Siebel web service endpoint URL.
timeOutInSeconds	Siebel web service time out in seconds.

Siebel Funded Order Formatter

Table 3-5 shows the method functionality for oracle.retail.stores.formatter.siebel.FundedOrderFormatter.

Table 3-5 Siebel Funded Order Formatter Method Functionality

formatConnectorMessage	translateConnectorResponse
Request update to order with funding details resulting from tendering a transaction in Point-of-Service.	Validate IDs in response matches the IDs from request. If the order contains accessories (items not in the original Siebel order), Point-of-Service transaction object is updated with Siebel Line Item IDs.

Table 3-6 shows the configuration properties for the <pos server install>/pos/config/technician/RetailTransactionTechnician.xml configuration file.

Table 3-6 Siebel Funded Order Formatter Configuration Properties

Configuration Property	Purpose
userID	User ID for Siebel user with global order visibility.
password	Password for Siebel user with global order visibility.
securityType	Security model used by Siebel web service. Must be either Siebel or WS-Security.
endPointUrl	Siebel web service endpoint URL.
timeOutInSeconds	Siebel web service time out in seconds.
writeInPartNumber	Part Number used for Siebel Write-In Products.
useAdjustmentNRC	Boolean indicates if return totals should be posted to Siebel's AdjustmentNRC field.

Siebel Payment Formatter

Table 3-7 shows the method functionality for oracle.retail.stores.formatter.siebel.PaymentFormatter.

Table 3-7 Siebel Payment Formatter Method Functionality

formatConnectorMessage	translateConnectorResponse
Request update to order with payment details resulting from tendering a transaction in Point-of-Service.	Validate IDs from one or more payments records are in response.

Table 3-8 shows the configuration properties for the <pos server install>/pos/config/technician/RetailTransactionTechnician.xml configuration file.

Table 3-8 Siebel Payment Formatter Configuration Properties

Configuration Property	Purpose
userID	User ID for Siebel user with global order visibility.
password	Password for Siebel user with global order visibility.
securityType	Security model used by Siebel web service Must be either Siebel or WS-Security.
endPointUrl	Siebel web service endpoint URL.
timeOutInSeconds	Siebel web service time out in seconds.
includeCashChangeRoundingAdjustment	Boolean indicates if the cash change rounding adjustment should be sent as tender to Siebel.

Siebel Transaction Sync Formatter

Table 3-9 shows the method functionality for oracle.retail.stores.formatter.siebel.TransactionSyncFormatter.

Table 3-9 Siebel Transaction Sync Formatter Method Functionality

formatConnectorMessage	translateConnectorResponse
Request update of Point-of-Service database with Siebel line item IDs for any accessories added to order.	No action.

Table 3-10 shows the configuration properties for the <pos server install>/pos/config/technician/RetailTransactionTechnician.xml configuration file.

Table 3-10 Siebel Transaction Sync Formatter Configuration Properties

Configuration Property	Purpose
No properties.	No properties.

Queues

The following are the queues for processing an external order, as defined by the COMMEXT framework:

SiebelTrnFileQueue.queue: After tendering the order, the transaction is persisted to the Point-of-Service database. The transaction is then saved into this file queue.
FundSiebelOrderQueue.queue: The transaction from the SiebelTrnFileQueue.queue file is written to the FundSiebelOrderQueue.queue file and then sent to the external order system to have the order details updated. After the successful completion of updates, the message is sent to the SyncTransactionFromSiebelOrderQueue.queue and it is deleted from FundSiebelOrderQueue.queue. If there are any errors during processing, the QueuedForwardConnector retries sending the message to the external order system.
SyncTransactionFromSiebelOrderQueue.queue: The message in this queue is used by the Point-of-Service application to update the transaction based on the response from the previous step.
UpdateSiebelOrderPaymentQueue.queue: The message in this queue is used by Point-of-Service to update the external order with the payment information based on the response from the previous step.

ExternalOrderMapping.xml

In many cases, text used in Point-of-Service does not match text used in Siebel for names and codes common to both systems. The translation of these text strings is performed in the Siebel Formatters by looking-up mappings, externalized, in <pos server install>/pos/config/ExternalOrderMapping.xml. Retailers are expected to customize this file to match the text used in their Siebel deployment. The values contained in the ExternalOrderMapping.xml that is shipped with Point-of-Service are only intended for demonstration purposes.

Retailers with unique needs might need to require creation of additional mappings in the ExternalOrderMapping.xml file. Adding mappings also requires enhancing the xml parsing logic in oracle.retail.stores.formatter.siebel.Translation.

Status

ExternalOrderMapping.xml defines mappings used by Siebel formatters when interacting with Siebel status fields.

Order Status

Maps Siebel Order-level status field to Order-states known by Point-of-Service.

Table 3-11 Siebel Order-Level Status Field

Status	Formatter	Comments
Searchable	QueryFormatter	External Order search results will be limited to only orders having the Searchable order-level status. If more than one order-level status is desired, then Siebel Status names should be comma-delimited.
Lock	StatusUpdateFormatter	An External Orders are updated with the Lock status when Point-of-Service operator selects a specific order to begin the tendering process.
Cancel	StatusUpdateFormatter	An External Orders is updated with the Cancel status when Point-of-Service operator clicks the Cancel button to abandon the tendering process.
Reject	StatusUpdateFormatter	An External Orders is updated with the Reject status when Point-of-Service determines the external order cannot be successfully tendered due to issues with the data.
Funded	FundedOrderFormatter	An External Order is updated to the Funded status after the transaction has been tendered by Point-of-Service.
Funded Failed	StatusUpdateFormatter	An External Order is updated to the Funded Failed status when Siebel, due to an error condition, is unable to accept a Point-of-Service request to update the Order in Siebel with details from a tendered transaction.

Payment Status

Maps Tender Type Codes (see oracle.retail.stores.domain.tender.TenderTypeMap) to Siebel Payment-level Status.

SALE: Defines the Siebel status used for Types of Payment for positive amounts.
RETURN: Defines the Siebel status used for Types of Payment for refunded amounts.
OVERTENDERSALE: Defines the Siebel status used for Types of Payment for refunded amounts.

Shipping Instruction

A Shipping Instruction is text sent by the FundedOrderFormatter to Siebel to update the Shipping instruction field when an order contains line items not shipped by Siebel.

Items not shipped by Siebel are either Store shipped or NotShipped at all; line items meeting these criteria will be assigned the shipping instruction defined in ExternalOrderMapping.xml:

 <SHIPPING>
    <!--Mapping for Siebel shipping instructions-->
    <OBJECT name="Instruction">
      <!--item shipped from the store-->
      <MAPPING name="Store">Store purchased</MAPPING>
      <!--item not shipped from the store or from warehouse-->
      <MAPPING name="NotShipped">Store purchased</MAPPING>
    </OBJECT>
  </SHIPPING>

Price Type

The Price Type defines the item-level Price Types the QueryFormatter recognizes as non-recurring charges. If more than one Price Type text is used for non-recurring charges, then Price Types should be delimited with a comma.

<OBJECT name="Type">
  <MAPPING name="OneTime">One-Time</MAPPING>
</OBJECT>

Payment

The payment element defines mappings used by the PaymentFormatter to post Payment information to Siebel:

<PAYMENT>
  <OBJECT name="Type">
    <MAPPING name="AmEx">American Express</MAPPING>
    ...
  </OBJECT>
  <OBJECT name="Method">
    <MAPPING name="CRDT">Credit Card</MAPPING>
    ...
  </OBJECT>
</PAYMENT>

Method: Maps Point-of-Service Tender Type Codes (see oracle.retail.stores.domain.tender.TenderTypeMap) to Siebel Payment Methods.
Type: Maps Point-of-Service Card Type (see oracle.retail.stores.domain.utility.CardTypeIfc) and Tender Type (see oracle.retail.stores.domain.tender.TenderTypeMap) codes to Siebel Payment Types.

Axis2

The Point-of-Service integration with Siebel is built using the Apache Axis2/Java web services framework.

Since Point-of-Service initiates all communication with Siebel, Point-of-Service acts only as a web service client. The Axis2-dependant client code exists in two places:

Formatter Web Service Client Code
Connector Web Service Client Code

Formatter Web Service Client Code

Formatters translate information between Point-of-Service objects and Web Services Description Language (WSDL)-generated objects that provide a direct mapping between Java objects and the Siebel web service WSDL. The WSDL-generated classes, having been built using Axis2 wsdl2java adb option, leverage the Axis2 Databinding (ADB) Framework.

The Siebel Formatters format all messages for a Document-Literal (DOC-Literal) bound web service.

Connector Web Service Client Code

All Siebel web service calls are invoked through the oracle.retail.stores.connector.siebel.WebServiceConnector, a subclass of oracle.retail.stores.connector.GenericWebServiceConnector. The GenericWebServiceConnector functions as a blocking client, leveraging the Axis2 API to marshall ADB object data and SOAP messages. The WebServiceConnector provides some Siebel-specific functions for security and error-handling.

For more information about Axis2, see the following web site: http://ws.apache.org/axis2/

Integration With a Different Web Service

The Point-of-Service-to-Siebel integration is designed to operate with the ORPOS_Order_WebService only. However, merchants might have unique needs that require implementing a customized integration with a different web service. In most cases, this level of customization can be achieved by doing the following:

Export the web service WSDL.
Generate client classes using the Apache Axis2 WSDL2Java utility.
Replace or update the Siebel Formatters to use the WSDL-generated classes.
Update the ExternalOrderMapping.xml and enhance or replace the oracle.retail.stores.formatter.siebel.Translator to support the translation of text required by formatters.
Update the DefaultConnectorTechnician.xml and RetailTransactionTechnician.xml to support changes to formatters.

If the new web service is not a Document-Literal (DOC-Literal) bound web service, changes might be required to the GenericWebServiceConnector to support remote procedure call-style actions.