Guidelines for Using Web Services to Integrate Order Management

Plan

Plan Your Integration

Requirement	Description
Register source system.	You must register each source system that sends the order request as a source system. More than one source system might create a source order, so the web service stores details that identify the source system on the order so it can track the source system that sends the order. The web service uses the source system during cross-referencing to determine the corresponding internal identifier or value that's specific to the source system.
Plan how you will synchronize customer master data.	You must synchronize customer master data before you import a source order. If the customer on the order doesn't exist in the customer model in Oracle Trading according to the CreateCustomerInformationFlag preference in the service schema, then Order Management can create the customer details.
Plan for attributes in Oracle Configure, Price, and Quote Cloud.	If you use Oracle Configure, Price, and Quote Cloud `(CPQ)`, then CPQ sends details about the attributes that Order Management requires to use this functionality, such as FreezePriceFlag, FreezeShippingChargeFlag, FreezeTaxFlag, and so on.
Plan for pricing.	You can send a source order that your upstream system already priced, or the web service can price the source order for you. If you use a predefined implementation of Oracle Configure, Price, and Quote Cloud, then the web service assumes the upstream system already priced the source order and won't allow price changes in Order Management.
Plan how to handle draft sales orders.	Your source system can send a submitted source order or a source order that's in draft status. If the source order is in draft status, then you must submit the sales order that references the source order. Order Management won't run the orchestration process that fulfills your sales order until you submit it. If the web service creates the order in draft status, then you can submit it from the Order Management work area, or you can use operation SubmitDraftOrder in the web service to submit it. If you use SubmitDraftOrder, then you must add the payload that defines it.

Use Asynchronous or Synchronous Services

Asynchronous or Synchronous?	Description
The integration platform or application that uses the service supports an asynchronous service.	Use the asynchronous operation because asynchronous is more resilient and fault tolerant than synchronous. If the response from the fulfillment system is delayed for some reason, then an asynchronous operation can continue processing but a synchronous operation might time out and go into an error state.
The platform or application doesn't support an asynchronous service, or you prefer not to use asynchronous because its more complex to implement.	Use synchronous as long as the number of lines in the sales order doesn't result in a timeout after 300 seconds. If you use synchronous, and if a sales order times out, then you must make sure you set up your implementation to resubmit the sales order.

Asynchronous or Synchronous?

Description

The integration platform or application that uses the service supports an asynchronous service.

Use the asynchronous operation because asynchronous is more resilient and fault tolerant than synchronous. If the response from the fulfillment system is delayed for some reason, then an asynchronous operation can continue processing but a synchronous operation might time out and go into an error state.

The platform or application doesn't support an asynchronous service, or you prefer not to use asynchronous because its more complex to implement.

Use synchronous as long as the number of lines in the sales order doesn't result in a timeout after 300 seconds.

If you use synchronous, and if a sales order times out, then you must make sure you set up your implementation to resubmit the sales order.

Process More Than One Sales Order

Use these operations of Order Import Service.

stageOrders. The only operation that can accept more than one sales order in the payload.
createOrders. Can accept only one sales order in the payload.

The Receive Order Request web service can accept only one sales order in the payload.

Learn about the input messages and output messages that you can use with Order Import Service. For details, go to SOAP Web Services for Oracle SCM, then expand Business Object Services > Import Sales Orders.

Make Sure Your Payload Uses the Correct Hierarchy

Entity Hierarchy That Web Services Support

Make sure your payload uses this entity hierarchy.

Header
- Order Payment
- Order Sales Credit
- Order Attachments
- Order Lines
  - Line LotSerial
  - Line SalesCredit
  - Line Payments
  - Line Document References
  - Line Attachments
  - Line Transactional Attributes
  - Charge
    - Charge Components
- Order Preferences

Logical Data Model

Make sure your payload can accommodate the data model.

Response Payload

Make sure your integration can accommodate the response that Order Management sends. The response payload returns a status.

Status	Description
SUCCESS	The response includes source keys and Order Management keys. It sends this response after Order Management successfully creates the sales order.
FAILURE	The response includes the first validation error message.

The response payload uses this structure.

Specify Attributes in Payloads

Specify Attributes in Groups

To make sure the payload includes all the required details, the web service processes some attributes as a group. For example, here are the attributes that the web service examines as a group to make sure the payload identifies the buying party.

BuyingPartyId
BuyingPartyName
BuyingPartyNumber

Here's the sequence that the web service uses when it processes each group.

Use the attribute that specifies the identifier, such as BuyingPartyId.
If the attribute that specifies the identifier is empty, then use the attribute that specifies the number, such as BuyingPartyNumber.
If the attribute that specifies the number is empty, then use the attribute that specifies the name, such as BuyingPartyName.

If the attribute that specifies the identifier includes a value, then the web service will always use this value even if the attributes that specify the name or number aren't empty.

If the payload doesn't include a value for the identifier, name, or number, then your order import will likely fail.

Specify Coded Attributes and Their Partners

Some attributes, such as ReturnReasonCode, store an abbreviation for a longer term. The abbreviation is typically text that you can view to quickly identify a lookup value's meaning.

You can think of the value of this attribute as coded. A coded attribute typically includes a partner attribute. For example, the ReturnReason attribute is the partner for ReturnReasonCode.

If you provide a value only for the coded attribute in the payload, then Order Management will use the value that the database cross-references from the lookup value to the meaning. For example, it cross-references the RET lookup value to the meaning for RET, which is Return.

Continuing this example, assume you set ReturnReasonCode=RET in the payload, and.

You set ReturnReason="Return Order", then the web service will ignore this value and use the code. This behavior is similar to using Identifier when you don't supply the Name.
You don't specify a value for ReturnReason, and if the value that the database cross-references to the meaning is Return, then the web service will use Return for the reason.

The web service uses this logic for each of these sets of attributes.

Coded Attribute	Partner Attribute
AccountingRulecode	AccountingRule
CancelReasonCode	CancelReason
ChargeDefinitionCode	ChargeDefinition
ChargeSubtypeCode	ChargeSubType
DemandClassCode	DemandClass
FOBPointcode	FOBPoint
FreightTermsCode	FreightTerms
InvoicingRuleCode	InvoicingRule
OrderedUOMCode	OrderedUOM
PaymentMethodCode	PaymentMethod
PaymentTerm	PaymentTermCode
RequestedFulfillmentOrganizationCode	RequestedFulfillmentOrganizationName
RequestedSupplierCode	RequestedSupplierName
ShipmentPriorityCode	ShipmentPriority
ShippingCarrierCode	ShippingCarrier
ShippingModeCode	ShippingMode
ShippingServiceLevelCode	ShippingServiceLevel
SubInventoryCode	Subinventory
SubstitutionReasonCode	SubstitutionReason
TaxExemptReasonCode	TaxExemptReason
TransactionalCurrencyCode	TransactionalCurrencyName
TransactionLineTypeCode	TransactionLineType

Include Identifiers and Values

Use an attribute that includes the word Identifier in the name to send the identifier, such as Requesting Business Unit Identifier. If you send the identifier and the value for the identifier, then the web service uses the identifier.

Master data includes customers and items. The source system can send different details, depending on whether it uses the same master data and references data that Order Management uses.

Uses the same data. The source system can send the Oracle identifier or the values.
Doesn't use the same data. The source system can send the identifiers and values that it contains. Order Import Service uses them as keys to look up the cross-reference, depending on whether the key references customer data or product data. If the cross-reference resides in:
- Oracle Trading Community Model, then resolve it into Oracle customer data
- Product Information Management, then resolve it into Oracle product data

Each service typically uses a pair of synchronous and asynchronous operations. The service appends the operation name with a value.

Sync. The other operation in the pair is asynchronous.
Async. The other operation in the pair is synchronous.

Process Change Orders and Cancel Orders

Process Change Orders

To modify a sales order, you call a web service with a payload that includes these details:

Source transaction system
Source transaction identifier
Order number and source transaction number of a sales order that Order Management already processed

The web service will process the order as a change order according to the combination of source transaction system and source transaction identifier.

Use the same web service that you used to create the sales order. The payload structure for a change order is similar to the payload structure for create order.
Design your payload so it sends the modified value for each attribute.
Make sure your payload includes all attributes for the order line that you modify.
If you use Oracle Application Development Framework (ADF), then you must include the entire order line in your payload even if you don't modify any part of the line. However, if you use REST API or FBDI with REST API, then you can exclude that entire line from the payload. For example, if your sales order has 100 lines but you only need to modify order line 1001, then you can use REST API or FBDI with REST API to import only line 1001. For details, see Use REST API with FBDI to Import Large Volumes of Sales Orders.

Cancel Sales Orders

To cancel a sales order or order line, you call the same web service that you use to create the sales order.

Here are details to include in your payload.

What You Must Cancel	Description
Cancel the entire sales order.	Set the OperationCode for the order header to CANCEL. You must also identify the source transaction system and include the source transaction identifier.
Cancel the entire order line.	Send the SourceTransactionLineIdentifier and SourceTransactionScheduleIdentifier for the order. Do one of. Set the OperationCode attribute for the order line to CANCEL. Set the Ordered Quantity attribute to 0.
Cancel part of a shipped order line.	Set the ordered quantity to the quantity that already shipped. For example, if the quantity on the original order line is 10 Each, and if 7 shipped, and if 3 were back ordered, then set the ordered quantity in the payload to 7 Each. Make sure your payload also includes all other attributes from the original order line.

What You Must Cancel

Description

Cancel the entire sales order.

Set the OperationCode for the order header to CANCEL. You must also identify the source transaction system and include the source transaction identifier.

Cancel the entire order line.

Send the SourceTransactionLineIdentifier and SourceTransactionScheduleIdentifier for the order. Do one of.

Set the OperationCode attribute for the order line to CANCEL.
Set the Ordered Quantity attribute to 0.

Cancel part of a shipped order line.

Set the ordered quantity to the quantity that already shipped. For example, if the quantity on the original order line is 10 Each, and if 7 shipped, and if 3 were back ordered, then set the ordered quantity in the payload to 7 Each.

Make sure your payload also includes all other attributes from the original order line.

Example of Canceling Part of an Order Line

Consider an example.

Quantity originally ordered equals 100
Quantity already shipped equals 40
Quantity awaiting shipping or backordered equals 60

Use these values.

Scenario	Quantity to Send in Payload for Update Service	Description
Your customer needs a revised total quantity of 55.	55	The quantity of 55 in the payload replaces the original quality. 40 already shipped, so order fulfillment cancels 45 of the 60 that are currently awaiting shipping or backordered, leaving 15 that are still awaiting shipping or backordered.
You must cancel the quantity that hasn't shipped.	40	The quantity of 40 in the payload replaces the original quality. Order fulfillment cancels the 60 that are currently awaiting shipping or backordered.
Assume quantity already shipped is 0, quantity awaiting shipping is 100, and you must cancel the entire quantity.	0	The quantity of 0 in the payload replaces the original quality. Order fulfillment cancels the 100 that are currently awaiting shipping.

Scenario

Quantity to Send in Payload for Update Service

Description

Your customer needs a revised total quantity of 55.

55

The quantity of 55 in the payload replaces the original quality.

40 already shipped, so order fulfillment cancels 45 of the 60 that are currently awaiting shipping or backordered, leaving 15 that are still awaiting shipping or backordered.

You must cancel the quantity that hasn't shipped.

40

The quantity of 40 in the payload replaces the original quality.

Order fulfillment cancels the 60 that are currently awaiting shipping or backordered.

Assume quantity already shipped is 0, quantity awaiting shipping is 100, and you must cancel the entire quantity.

0

The quantity of 0 in the payload replaces the original quality.

Order fulfillment cancels the 100 that are currently awaiting shipping.

Use Security with Web Services

The web service attaches an LPA security policy to the service and the callback. It includes a hybrid policy.

oracle/wss11_saml_or_username_token_with_message_protection_service_policy

This policy supports five different assertions, including this one.

oracle/wss_username_token_over_ssl_client_policy

The callback includes an attachment.

oracle/wss_username_token_over_ssl_client_policy LPA

Use these settings to call the web service only with SSL (Secure Sockets Layer).

Use Files to Import Source Orders

Use the Order Import Template to import source orders. It helps reduce errors and simplifies order import. It contains a structure that the Oracle database requires. For example, it includes a tab for each database table, and it displays these tabs in a specific sequence.

Automate using files to import source orders. Oracle provides a set of web services you can use to upload the completed import template to the server that hosts Oracle WebCenter Content. You then run a scheduled process that imports the uploaded file to the interface tables, processes them, then imports each interface record as a sales order. For details, see Using the Oracle ERP Cloud Adapter with Oracle Integration.

Here are the parameters you use when you run the scheduled process.

Parameter	Value
JobDefinitionName	ImportOrdersJob
JobPackageName	oracle/apps/ess/scm/doo/decomposition/receiveTransform/receiveSalesOrder