Guidelines for Setting Up Holds on Sales Orders

Determine the Type of Hold You Need

You can apply different kinds of holds.

Type	Description
Generic	Hold that you apply on any step of an orchestration process. It doesn't apply a hold for a specific task. You enable Hold All Services when you create the hold code.
Service	Hold that you apply on a specific task type and service, such as the Create Billing Lines service of the Invoice task type. You specify the service when you create the hold code.
System	Hold that Order Management automatically applies and releases. Here are some examples. Hold_for_Change_Request. Order Management applies the Hold_for_Change_Request hold when the user revises a sales order so no other user or process can modify the sales order during the revision. DOO_CreditCheck. Order Management applies this hold when the customer exceeds their credit limit. For example, if credit check fails because the customer exceeded their credit limit, then you don't want the orchestration process to proceed to the ship step and ship the item.

Type

Description

Generic

Hold that you apply on any step of an orchestration process. It doesn't apply a hold for a specific task. You enable Hold All Services when you create the hold code.

Service

Hold that you apply on a specific task type and service, such as the Create Billing Lines service of the Invoice task type. You specify the service when you create the hold code.

System

Hold that Order Management automatically applies and releases. Here are some examples.

Hold_for_Change_Request. Order Management applies the Hold_for_Change_Request hold when the user revises a sales order so no other user or process can modify the sales order during the revision.
DOO_CreditCheck. Order Management applies this hold when the customer exceeds their credit limit. For example, if credit check fails because the customer exceeded their credit limit, then you don't want the orchestration process to proceed to the ship step and ship the item.

Create Your Hold Code

Note

Use the Setup and Maintenance work area to manage hold codes, orchestration processes, and task types.
Use the hold code to specify the task to hold, such as creating the invoice.
Specify the service, or specify the task type.

Set the attributes.

Attribute	Description
Applicable Roles	Use the Applicable Roles tab to specify who can apply and release the hold, such as the Order Manager. Note that you can't specify a role for applying a system hold, but you can specify a role to release a DOO_CreditCheck hold.
Set	As an option, use the Set attribute of the hold code to specify the business unit where Order Management applies the hold. You can also use Set to create a set of hold codes and apply them all to the same business unit.
Hold Tasks In Progress	Order Management automatically enables the Hold Tasks In Progress option when the user applies it on the Order page in the Order Management work area or when you import a hold. Disable this option only if you haven't set up your fulfillment system to correctly interpret it.
End Date	Don't set the End Date attribute for a predefined, system hold code, such as HOLD_FOR_CHANGE_REQUEST. Order Management uses these codes. If you set the end date on one, you might introduce errors in your implementation. Examine the description to determine whether a predefined hold code is a system hold code. The description usually identifies system holds. For example, here's the description for HOLD_FOR_CHANGE_REQUEST. `System defined hold code used in change management process` If you set the End Date for a hold code, then you can't apply the hold after the end date happens, but you can release the hold after the end date happens.

Hold All Services

If You Don't Enable the Hold All Services Option	If You Enable the Hold All Services Option
The service that you specify affects each orchestration process step that references the service. Assume you: Don't add a check mark to Hold All Services for the HOLD CREATE SHIP hold. On the services tab, you specify the Create Billing Lines service. Your hold affects only step 300 of orchestration process ShipOrderGenericProcess because step 300 is the only step that references the Create Shipping service. Use this option when you want some of the services of the task type to run but not others. For example, you want to put a hold on Create Shipping until you verify the orchestration process successfully created the shipment request, but you want the process to automatically do the Wait for Shipment task after you remove the hold for Create Shipping.	The task type that you specify affects each orchestration process step that references the task type. Assume you: Add a check mark to Hold All Services for the HOLD CREATE SHIP hold. You leave the Services tab empty. Your hold affects step 300 and step 400 because these steps reference the Shipment task type. Use this option when you don't any part of the task to run. Let's say you're shipping a highly flammable, dangerous item. Before shipping, you place a hold to verify the carrier is licensed to handle hazardous material. Enable the Hold All Services option on the shipping task type to make sure no part of shipping runs.

If You Don't Enable the Hold All Services Option

If You Enable the Hold All Services Option

The service that you specify affects each orchestration process step that references the service.

Assume you:

Don't add a check mark to Hold All Services for the HOLD CREATE SHIP hold.
On the services tab, you specify the Create Billing Lines service.

Your hold affects only step 300 of orchestration process ShipOrderGenericProcess because step 300 is the only step that references the Create Shipping service.

Use this option when you want some of the services of the task type to run but not others. For example, you want to put a hold on Create Shipping until you verify the orchestration process successfully created the shipment request, but you want the process to automatically do the Wait for Shipment task after you remove the hold for Create Shipping.

The task type that you specify affects each orchestration process step that references the task type.

Assume you:

Add a check mark to Hold All Services for the HOLD CREATE SHIP hold.
You leave the Services tab empty.

Your hold affects step 300 and step 400 because these steps reference the Shipment task type.

Use this option when you don't any part of the task to run. Let's say you're shipping a highly flammable, dangerous item. Before shipping, you place a hold to verify the carrier is licensed to handle hazardous material. Enable the Hold All Services option on the shipping task type to make sure no part of shipping runs.

See Where You Can Release Holds

If I Apply Hold Through	Can I Release it on Create Order or Revise Order Page in Order Management Work Area	Can I Release It in Fulfillment View in Order Management Work Area	Can I Release It Through Web Service	Can I Release It Through REST API
Create Order or Revise Order Page in Order Management Work Area	Yes	Yes	Yes, but only if you applied the hold on the order header or order line. You can't use the web service to release a hold that you apply on a fulfillment line on the Revise Order page.	Yes, but only if you applied the hold on the order header or fulfillment line.
Fulfillment View	Yes, but only if you applied the hold on the order header or fulfillment line. You can't use the Revise Page to release a hold that you applied on an order line because you already submitted the order, and Order Management transformed the order line to a fulfillment line.	Yes	Yes, but only if you applied the hold on the order header. You can't use the web service to release a hold that you apply on a fulfillment line in a fulfillment view.	Yes, but only if you applied the hold on the order header or fulfillment line. You can't use REST API to release a hold that you apply on a order line in a fulfillment view.
Web Service	Yes, but only if you applied the hold on the order header. You can't use the Create page or Revise page to release a hold that you apply on an order line or fulfillment line through the web service.	Yes	Yes	Yes, but only if you applied the hold on the order header.
REST API	Yes, but only if you applied the hold on the order header or fulfillment line.	Yes, but only if you applied the hold on the fulfillment line.	Yes, but only if you applied the hold on the order header. You can't use the web service to release a hold that you applied on a fulfillment line through REST API.	Yes

Use a Wait Step

If you enable the FOM_SKIP_HOLDS_WAIT_VALIDATION profile option, then Order Management will process a request to apply or release a hold on the fulfillment line only if the line is on a wait step. For example, when the line is in the Awaiting Shipping status. If the line isn't on a wait step, then Order Management will return an error. To enable the profile option, go to the Setup and Maintenance work area, click Tasks > Search, search for and open the Manage Profile Options page, search the Profile Option Code attribute for FOM_SKIP_HOLDS_WAIT_VALIDATION, then make sure the Enabled option contains a check mark at the Site level.

An orchestration process that references a service that does a Wait operation is a wait step. To determine which services do a wait operation, go to the Manage Task Types page in the Setup and Maintenance work area, click the row that includes your task type of interest, such as Shipment, then, in the Details area, examine the services. Look for services that do a Wait operation.
If you create a hold code for a long-running task, such as a shipping or invoicing task, then set it up so Order Management applies it on a wait step.

Using this approach will help to avoid a concurrency problem that happens when the user revises a sales order while a long-running task is running. Placing the hold on a wait step helps to make sure any actions that were in process finish before the user can revise the order.
Apply the hold on the Wait for Shipment service for a shipment task, and the Wait for Billing service for an invoice task. Each of these services do a wait operation.

Apply Holds on Shipment Sets

If you apply or release a hold on any source line that's part of a shipment set, then Order Management applies or releases the hold on all lines that are part of the set.

If you apply a hold on a line that's part of a shipment set, then Order Management queries the database to determine whether other lines in the same shipment set exist on the sales order. If it doesn't find any other lines in the set, then it applies the hold only on the line that you specify in the payload. The same behavior applies when you release a hold.

Assume shipment set n includes lines x, y, and z. If your import applies a hold on line x, then Order Management applies the same hold on lines y and z. Order Management applies the hold on lines y and z even if you don't include them in your payloads.

Make Sure You Have the Privileges

A job role has privileges. Examine the job role and make sure you have its privileges.

What I Need to Do	Job Role	Formal Name of Job Role
Set up a hold code.	Order Administrator	ORA_DOO_ORDER_ADMINISTRATOR_JOB
Apply, release, or view a hold on a sales order, order line, or fulfillment line on the Create Order page, Revise Order page, or in a fulfillment view.	Order Entry Specialist or Order Manager	ORA_DOO_ORDER_ENTRY_SPECIALIST_JOB ORA_DOO_ORDER_MANAGER_JOB
View a hold on an orchestration process in a fulfillment view.	Order Manager	ORA_DOO_ORDER_MANAGER_JOB
Apply or release a hold through a web service.	Create your own role.	Add privileges to your role. DOO_MANAGE_ORDER_ORCHESTRATION_DECOMPOSITION_WEB_SERVICE_PRIV DOO_MANAGE_ORDER_ORCHESTRATION_ORDER_MODIFICATION_PRIV
Apply a hold through REST API.	Create your own role.	Add privileges to your role. FOM_APPLY_UPDATE_HOLDS_PRIV DOO_MANAGE_ORCHESTRATION_ORDER_MODIFICATION_PRIV FOM_SALES_ORDER_REST_POST_PRIV
Release a hold through REST API.	Create your own role.	Add privileges to your role. FOM_RELEASE_HOLDS_PRIV DOO_MANAGE_ORCHESTRATION_ORDER_MODIFICATION_PRIV FOM_SALES_ORDER_REST_POST_PRIV

This topic uses predefined job roles. You must create your own job roles, depending on your security requirements. For details, see Privileges That You Need to Implement Order Management.

Import Holds Through Web Service

Use a web service to import holds.

Here's an example payload that applies the DOO_SHIP_ALL hold on order line 101 for source order 20156 that you import from source system LEG.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope> 
  <soapenv:Header/> 
  <soapenv:Body> 
    <dood:RequestHoldProcessRequest>
      <!-1 or more repetitions:--> 
      <dood:ApplyHoldRequestParams>
        <dood:SourceOrderSystem>LEG</dood:SourceOrderSystem> 
        <!--Optional:--> 
        <dood:SourceOrderId>20156</dood:SourceOrderId> 
        <!--Optional:--> 
        <dood:SourceLineId>101</dood:SourceLineId> 
        <!--Optional:--> 
        <dood:SourceHoldCode>DOO_SHIP_ALL</dood:SourceHoldCode> 
        <!--Optional:--> 
        <dood:HoldComments>Hold Shipping</dood:HoldComments> 
        <!--Optional:--> 
        <dood:SourceOrderNumber></dood:SourceOrderNumber> 
        <!--Optional:--> 
        <dood:SourceOrderLineNumber></dood:SourceOrderLineNumber> 
        <!--Optional:--> 
        <dood:HoldName></dood:HoldName> 
        <!--Optional:--> 
        <dood:AppliedBy>?</dood:AppliedBy>
      </dood:ApplyHoldRequestParams>
    </dood:RequestHoldProcessRequest>
  </soapenv:Body> 
</soapenv:Envelope>

Here's an example payload that releases the hold.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope> 
  <soapenv:Header/> 
  <soapenv:Body> 
  <dood:ReleaseHoldProcessRequest>
    <!-1 or more repetitions:--> 
    <dood:ReleaseHoldRequestParams>
        <dood:SourceOrderSystem>LEG</dood:SourceOrderSystem> 
        <!--Optional:--> 
        <dood:SourceOrderId>20156</dood:SourceOrderId> 
        <!--Optional:--> 
        <dood:SourceLineId>101</dood:SourceLineId> 
        <!--Optional:--> 
        <dood:SourceHoldCode>DOO_SHIP_ALL</dood:SourceHoldCode> 
        <!--Optional:--> 
        <dood:HoldReleaseReasonCode>DOO_RELEASE_SHIP</dood:HoldReleaseReasonCode> 
        <!--Optional:--> 
        <dood:HoldComments>Remove Hold</dood:HoldComments> 
        <!--Optional:--> 
        <dood:SourceOrderNumber>?</dood:SourceOrderNumber> 
        <!--Optional:--> 
        <dood:SourceOrderLineNumber>?</dood:SourceOrderLineNumber> 
        <!--Optional:--> 
        <dood:HoldName>?</dood:HoldName> 
        <!--Optional:--> 
        <dood:HoldReleaseReasonName>?</dood:HoldReleaseReasonName> 
        <!--Optional:--> 
        <dood:ReleasedBy>?</dood:ReleasedBy>
      </dood:ReleaseHoldRequestParams>
    </dood:ReleaseHoldProcessRequest>
  </soapenv:Body> 
</soapenv:Envelope>

Note

Use the ReceiveOrderRequestService web service. For details, see Web Services That You Can Use to Integrate Order Management.
To apply a hold on the order header, include a value for SourceOrderId but not for SourceLineId. The hold will apply to the header and all lines in the order.
To apply or release a hold on the order line, you must include a value for SourceOrderId and for SourceLineId.

Apply or release a hold on more than one sales order. Use the same soapenv:Header and soapenv:Body, and include a separate RequestHoldProcessRequest section or ReleaseHoldProcessRequest section for each sales order. For example:

<soapenv:header> ..... </soapenv:header>
<soapenv:body>
<RequestHoldProcessRequest>
   <SalesOrderNumber>1234</SalesOrderNumber>
   <SalesOrderSystem>GPR</SalesOrderSystem>
</RequestHoldProcessRequest>
<RequestHoldProcessRequest>
   <SalesOrderNumber>2345</SalesOrderNumber>
   <SalesOrderSystem>GPR</SalesOrderSystem>
</RequestHoldProcessRequest>
</soapenv:body>

The web service imports the order with the Hold Tasks In Progress option as enabled when applying or releasing a hold.
You can use the web service to apply or release a hold on a sales order that's in Draft status.
You can use the web service to apply or release a hold on the order header or order line, but you can't use it to apply or release a hold on a fulfillment line. To apply or release a hold on a fulfillment line, go to a fulfillment view in the Order Management work area, then use the Apply Hold action or the Release Hold action. For details, see Use Holds to Temporarily Stop Processing.
You can't include RequestHoldProcessRequest and ReleaseHoldProcessRequest in the same soapenv:Body.
You can't enable a hold on a service that uses a Wait, Apply Hold, Release Hold, or Inbound operation. For example, the Wait for Shipment task places the orchestration process in a wait state that's effectively the same as a hold, so its not necessary to place a hold when the process is already waiting. If you must hold the orchestration process, then add the hold to the step immediately before the Apply Hold, Release Hold, or Inbound operation step.

Import Holds Through REST API

For details, see Use REST API to Apply and Release Holds.

Example Hold Codes

Here are some examples you might find useful.

Code	Name	Task Type	Service to Hold
DOO_ACTIVTY	HOLD CREATE ACTIVITY	Activity	Create Activity.
DOO_SCHDL	SCHLD	Schedule	Create Scheduling and Cancel Scheduling.
DOO_SCHLD_ALL	SCHLD_ALL	-	All scheduling services.
DOO_RSRV	RESRV	Reservation	Create Reservation and Cancel Reservation.
DOO_RSRV_ALL	RESRV_ALL	-	All reservation services.
DOO_SHIP_CREATE	HOLD CREATE SHIP	Shipment	Create Shipping.
DOO_SHIP_ALL	SHIP_ALL	-	All shipping services.
DOO_RCV_CREATE	HOLD CREATE RECEIVE	Return	Create Expected Receipt Advice.
DOO_INVOICE_CREATE	HOLD CREATE INVOICE	Invoice	Create Billing Lines.

Drop Shipments and Purchase Orders

If Order Management applies a hold on a fulfillment line, and if the line involves a drop shipment and a purchase order, then the Order Management work area displays a hold icon on that line. Order Management displays the icon even if it applied the hold on only on one line in the purchase order.

Assume your sales order has these fulfillment lines:

Line 1, purchase order 1
Line 2, purchase order 2
Line 3, purchase order 1

If you use the Order Management work area to apply a hold on line 1, then the work area will display a hold icon on lines 1 and 3 because the entire purchase order is now on hold in Oracle Procurement. If you then release the hold on line 1 or line 3, then the work area will remove the icon from lines 1 and 3 because the entire purchase order is no longer on hold.

Other Points to Consider

Order Management comes with a number of predefined hold codes that hold a variety of task types and services. Add your own hold code only if the predefined ones don't meet your needs.
If you don't see the task type and the service that you need on the Services tab, then use the Manage Task Types page to specify the tasks and services that you can select for the hold. You must set the Hold Enabled option to make the service display on the Services tab. You can't enable some services for hold, such as Billing Response or Wait for Billing. For details, see Set Up Task Types for Holds.
If you apply a hold on the order header, then Order Management will also apply the hold on all order lines that are currently open in that sales order, but it won't apply a hold on lines that are closed or cancelled.
Order Management ignores a hold that you apply on a pause task. The pause task will resume according to its own conditions.

For a configured item, make sure you apply the hold on the configured item. Don't apply a hold on a configure option. For details, see Sales Order Hold.
Your downstream fulfillment systems can't finish the task until you release the hold.
If the total shipped quantity in Order Management doesn't equal the shipped quantity in Shipping, then Order Management rejects the hold request and displays an error.
Save time. You can migrate your hold setups. For details, see Copy Setups Between Instances of Order Management.
Order Management won't process a hold request or release request for a line that's in error recovery.