Enabling Sterling Order Management System Software to connect to Order Service

The built-in integration with Order Service integrates Sterling Order Management System Software with the Order Search and Archive Service components of Order Service. Starting release 10.0, the capability to save, index, and archive the ‘Order’ entity is available in the built-in integration.

When integration is enabled, orders that are created or updated from the application server and all agent or integration servers are saved and indexed in Order Search. When you purge orders in Sterling Order Management System Software, it updates the corresponding documents in Order Search with the order history information. When you archive orders, the entire order details are archived in Archive Service and erased from Sterling Order Management System Software.

The built-in integration with Order Service becomes a critical subsystem in Sterling Order Management System Software when the indexing, search, and archive capabilities are enabled in Sterling Order Management System Software. In essence, this integration brings Order Service to an integral part of Sterling Order Management System Software when the indexing, search, and archive capabilities are enabled. To enforce this, the integration logic checks at the time of initializing Sterling Order Management System Software whether it can communicate to Order Service and fails the deployment, if it could not. As Order Service is an integral part of Sterling Order Management System Software when indexing, search, and archive capabilities are enabled, a failure to connect to Order Service is an erroneous state of things and throwing the exception is to prevent any Sterling Order Management System Software deployment in such a situation.

The enabling of the built-in integration with Order Service is in fact assigning right values to the properties explained in this topic. If you configure values incorrectly that are no longer valid, it results in the failure of built-in integration and the entire Sterling Order Management System Software deployments. If such failures occur, Sterling Order Management System Software can be recovered only after correcting the values of these properties. Besides this, you must ensure that your configurations and preferences on the archive and indexing behavior are set appropriately based on your business needs and are valid too. This is because, when integration is enabled all your preferences and configurations also invoke automatically. So, you must show at most care and prudence on enabling the built-in integration with Order Service.

There are five sets of properties to enable the built-in integration with Order Service.

1. Setting up built-in integration properties

The following set of properties are mandatory to enable the built-in integration of Sterling Order Management System Software with Order Service. if you are using Sterling OMS Operator to setup your OMS integrated environment with Order Service, the operator scripts assign the following properties with the values given below for you:

Elasticsearch properties	Value	Description
`yfs.elasticsearch.client.type`	`SSIClient`	`SSIClient` connects to the Order Search service that deploys Elasticsearch internally.
`yfs.validation.fail.behaviour`	`warn`	Use this property to configure the behavior when an attempt to connect to Order Service fails at startup. Setting value `warn` logs an error and continues. whereas the value `fail` aborts the OMServer deployment.

YFS properties	Value	Description
`yfs.ssi.delete.from.index.on.entity.purge`	`false`	The Elasticsearch, implemented in Order Search Service, maintains multiple indices for past durations and capable to put data in the approximate index. Besides, Order Service acts as the single search repository for all Sterling Order Management System Software orders and hence, you must set this property to `false` if you want to use Order Service implementation for search.
`yfs.ssi.disabled.entities`	Shipment	The indexing capabilities in Order Service does not support the indexing of shipment entity. If you are using `SSIClient`, override this property and set `Shipment` to avoid any possible attempts to index shipments from Sterling Order Management System Software.
`yfs.ssi.entities.perform.custom.indexing`	`NIL`	This is a comma-separated list of `XMLName` of the entities for which only the business-layer indexing is applied. The order entity has a default implementation to submit indexing from its business logic. For most of the searchable and index able fields in an order entity, this should be sufficient. However, if the order status and some non-searchable fields of an order are included in the index (to use the index content as an outline view of an order), then a database operational level propagation is also needed. That is because Sterling Order Management System Software has business APIs which do direct update of order entity instead of calling the update via the mentioned business logic. Set this property to `NIL` to use database-level propagation for order entity. Note: Setting to `NIL` increases the number of indexing attempts between Sterling Order Management System Software and Order Service though it helps surface only the latest state of order.
`yfs.ssi.index.draft.orders`	`false`	Most of the orders reaching Sterling Order Management System Software from e-Commerce system are confirmed orders. Hence, Order Service does not want to support indexing of the Draft orders. Therefore, set this property to `false` if you want to use Order Service implementation for search.
`yfs.ssi.transform.wrap.child.entities.in.list`	`false`	Order Service expects every list XML node and its children XML nodes in the order index XML document to a JSON array format with the child node contents against the child node name. If you are using the Order Service implementation, you must set this property to `false` so that the XML is transformed to JSON specification expected by Order Service.

2. Setting up JWT token generation

Authentication is always enabled in Order Service. All incoming requests in Order Service are authenticated with the help of a signed JWT (JWS). To authenticate the incoming request, Order Service uses the JWT token that is generated by Sterling Order Management System Software. To set up the JWT token generation, configure the following yfs properties in Sterling Order Management System Software.

Property	Default value	Description
`yfs.jwt.create.issuer`	`oms`	Specify the issuer name when creating a JWT token for a current user.
`yfs.jwt.create.audience`	`service`	Specify to whom you intend to send the JWT token.
`yfs.jwt.create.algorithm`	`RS256`	Specify the algorithm that is used for signing the JWT token.
`yfs.jwt.create.expiration`	5 minutes	Specify the expiration time in minutes for the JWT token.
`yfs.jwt.create.pk.alias`		This alias corresponds to the Java keystore, which is used to save a private key. The corresponding public key is configured in Order Service. For more information about adding certificate and keys, see the Readme file.

Attention: If you specify inappropriate values or alter the default values it can lead to failure of token generation and fails the entire Sterling Order Management System Software deployments.

3. Setting up the Order Service deployment URL: Specify the URL to connect to Order Service to the osi.order.service.url yfs property. If you do not specify any value or assign an unreachable URL, the entire Sterling Order Management System Software deployments will fail.

4. Enabling archive of Order entity: To enable Archive Service integration, set osi.archive.enabled yfs property to Y.

5. Enabling Sterling Search Index feature: a. To enable Sterling Search Index feature, set the yfs.ssi.enabled yfs property to Y. This will enable order entity for indexing.; b. Start the SSI_DELAYED_SYNC agent. This agent must be running the entire time when the above property is Y and scheduled for auto-triggering on short intervals to ensure that any records that await indexing are processed. For more information on configuring the agent, see SSI delayed sync agent.

Note: As already mentioned, incorrect values which are no longer valid fails the entire Sterling Order Management System Software deployments. If such failures occurs, it can be recovered only after correcting the values of these properties. If you are managing your properties in database, use the manageProperty.sh script to correct the property values. This is because, a property cannot be modified through System Management Administrator in case of Sterling Order Management System Software deployment failures.