1. Implementing Order Management
  2. Guidelines for Pausing Orchestration Processes

Guidelines for Pausing Orchestration Processes

Use these guidelines to help make sure your pause task works correctly.

Add Step That Has a Pause Task

Add a step that references a pause task.

Add a step that references a pause task.

Note

  • Use the Edit Orchestration Process Definition page in the Setup and Maintenance work area.

  • Add a pause step. Set these values:

    Attribute

    Value

    Step Type

    Service

    Task Type

    Pause

    Task

    Pause

    Service

    Pause Process

  • Click the link in the Pause Rule column to set up your release rule.

    You typically use line-selection criteria to filter fulfillment lines that the orchestration process step processes. However, line-selection criteria isn't available for a pause task because the pause task already examines every fulfillment line in the sales order, by default.

Don't Specify Evaluation Intervals That Are Too Short

If you set up your pause task so the evaluation interval is too short, then the orchestration process might evaluate the pause condition an excessive number of times and degrade performance. Assume you:

  • Create a pause step that pauses the orchestration process until the Scheduled Ship Date happens.

  • Set the reevaluateFlag to Y.

  • Evaluate the condition one time every five minutes.

Assume five days typically elapse between the time the pause step runs and when the Scheduled Ship Date happens. On average, the orchestration process will evaluate the condition 1,440 times.

  • 12 times for each hour, multiplied by 24 hours, multiplied by five days, equals 1,440

This processing consumes a lot of resources, can affect performance, and might result in memory problems that can cause your runtime environment to fail. So, set up your pause step so it evaluates the condition less frequently. In this example, the evaluation could probably happen one time every two hours without affecting the orchestration process in a negative way.

Use the Number of Times to Retry Pause parameter to control the maximum number of times the orchestration process evaluates the condition before it temporarily pauses the pause task and displays an error message informing your users to click Recover to manually recover the pause. For details, see Manage Order Management Parameters.

Evaluate Conditions Again

Use the Recover Errors scheduled process to evaluate the conditions again. For example:

  1. Set up Recover Errors so it runs on the pause task.

  2. Set the Number of Times to Retry Pause to 10.

  3. At run time, Order Management retries 10 times.

  4. If all 10 retries fail, then Order Management places the pause task on the error and displays a message that it exceeded the maximum number of retries.

  5. The Order Entry Specialist uses the Recover Order action to recover the sales order.

  6. Each order line that's in error retries the pause 10 times.

  7. If the condition:

    • Satisfies during retry. Order Management releases the pause.

    • Doesn't satisfy. Order Management sets the pause task back to an error state.

Pause When Revising Sales Orders

Pause when the Order Entry Specialist revises a sales order. You can set attributes that control this behavior.

Pause Task That Happens When Revising Sales Orders

Note

  • If your pause task doesn't reference an extensible flexfield, then disable the Use Flexfield Attributes option to instruct the orchestration process to skip the pause step when the value in an extensible flexfield changes.

  • If you don't need to run your pause task when revising a sales order, then write a compensation pattern.

    Assume you write a pause step that waits for payment. The Order Entry Specialist manually indicates that the customer sent payment, and the pause ends. Some time later, the Order Entry Specialist revises the sales order in a way that doesn't affect the payment amount, such as modifying the ship-to address.

    It isn't necessary to pause to wait for payment after the revision, so you can write a compensation pattern that skips the pause on the payment step.

  • The orchestration process uses the attributes that you specify on the Order Attributes That Identify Change page to determine when to compensate while revising a sales order. Use it to make sure your pause task runs only if the revision that the Order Entry Specialist makes affects an attribute that your pause task references.

    For details, see Manage Order Attributes That Identify Change.

Release Your Pause

If the flow doesn't meet the conditions in the pause rule, then the release rule releases the pause. For example, if the actualShipDate attribute in the pause rule contains a value for each fulfillment line, then:

  • All fulfillment lines already shipped.

  • The flow hasn't met the pause rule condition that pauses the task.

  • The flow is ready to proceed to the next orchestration process step.

  • The flow returns to the release rule.

  • The release rule sets SacResult to SAC_TYPE_IMMEDIATE.

  • The release rule releases the pause.

  • The flow continues to the next orchestration process step.

If you set up more than one rule that runs as a set of rules on the same start after condition, then you must set the release rule to the highest priority of all rules in the set.

Default Release Rule

Here's an example of a release rule and a pause rule together.

guidelines when you define the release rule

Note

  • Order Management runs the rule with the highest priority first.

  • Set the Priority attribute to Highest on the rule where you use Assign New. This makes sure the rule runs first. It also makes sure that this rule creates the object that stores the result of the start-after condition (SAC). Other rules might set the value for the start-after condition.

  • If you only have one rule in your rule set, then you don't need to worry about setting priority.

  • If you don't set the priority correctly, you might encounter a null pointer error when Order Management runs the rule.

  • Don't use the If statement on the release rule to define the condition that your business logic requires. Instead, set up your conditional logic on the pause rule.

  • The rule editor requires that you set up a condition on the release rule so it passes validation, so set up a condition that's always true.

  • Use Assign New. Assign New creates a new instance of SacResult so you can assign values to it while the rules in your rule set run.

Another Example of a Release Rule

Adding a Release Rule

Note

  • Use advanced mode.

  • Specify sacResult.

    Attribute

    Description

    sacType

    Required

    sacEventName

    ReevaluateFlag

    waitDateTime

    Optional, depending on the type of pause. For example, if the rule pauses according to a dependency to resolve, then you must include sacEventName.

    For details, see Overview of Pausing Orchestration Processes.

  • Don't set default value for other attributes.

Use Some Other Technology to Release Pause

You typically use a release rule to release a pause. However, you can also use a web service, scheduled process, or the Order Management work area to release the pause.

Use Some Other Technology to Release Them

Note

  • Use only one rule in your rule set.

  • Don't specify a condition.

  • Use some other technology to release the pause task.

Here's the code.

Code

Description

Header is a DOOSeededOrchestrationRules.DOOHeader

Declare the Header variable, then store attributes of the order header that the orchestration process is currently processing into this variable.

Assign new DooSeededOrchestrationRules.SacResult SAC = new DooSeededOrchestrationRules.SacResult()

Create a new variable named SAC and set it to the SacResult type in the DooSeededOrchestrationRules method.

Assign Header.sacResult = SAC

Set the value of the sacResult object on the order header to the value that SAC contains.

Assign Header.sacResult.sacType = DooSeededOrchestrationRules.SacResult.SAC_TYPE_EVENT

Pause the orchestration process until an event happens.

Assign Header.sacResult.eventName = "Waiting for Manual Release"

Specify the event you use to identify the event that's tracking the pause. In this example, assume you named it Waiting for Manual Release.

Don't Include a Condition

If you manually release a pause or release it through a web service or scheduled process, then don't include a condition or default release rule. Here's an example where you send shippable and nonshippable lines together to invoicing, and you want to control when to send these lines.

If you manually release a pause or release it through a web service or scheduled process, then don't include a condition or default release rule.

You can specify your own eventName, such as Waiting for manual release. The Order Management work area will display this name. You can also specify it on the scheduled process that you use to release the pause.

Assign the Result

You must include these assignments as the first two actions in your Then statement:

Code Description

Assign new DooSeededOrchestrationRules.SacResult SAC = new DooSeededOrchestrationRules.SacResult()

Create a new variable named SAC and set it to the SacResult type in the DooSeededOrchestrationRules method.

Assign Header.sacResult = SAC

Set the value of sacResult on the order header to the value that SAC contains.

This code creates the object that stores the result of the start-after condition (SAC).

If you don't include these assignments, and if you don't create a release rule, then at least one of the rules in your rule set must use the Assign New action to create the SAC object.

Test Your Set Up

Test your set up in a development environment. Use these conditions.

  • Sales order that includes one fulfillment line.

  • Sales order that includes more than one fulfillment line. This test helps to make sure you set up your rules so they examine fulfillment lines that the current orchestration process instance isn't examining, but where a dependency exists between these fulfillment lines and the fulfillment line that the instance is examining.

  • If your data includes a ship set, then include a ship set in your test.

  • If your data includes a configured item, then include a configured item in your test.

  • Attributes that don't contain a value.

  • Attributes that contain values that result in condition evaluating to false.

  • Attributes that contain values that result in condition evaluating to true.

  • Order revision.

  • Change order.

  • If your rules reference them, then test extensible flexfields.

Troubleshoot

Fix Null Pointers When You Use equalsIgnoreCase

Assume you encounter an error that's similar to:

Order management can't pause the sales order. oracle.apps.scm.doo.common.DooJboException: oracle.rules.rl.exceptions.RLNullPointerException: Attempted to invoke method "equalsIgnoreCase" in class "java.lang.String" on a null object reference. at line 6 in /Ruleset(StartAfterCond_RuleSet_18)/Rule(Rule1)/Pattern(v0_DOOHeader)/Test[1]. For details, see the Guidelines for Pausing Orchestration Processes topic on Oracle Help Center

This might happen because your pause rule doesn't check to see whether the order header attribute that you're using to determine whether to pause the orchestration process contains a value. Assume you're using the customerPoNumber attribute to pause the process, and you have this statement in your rule.

If Header is a DooSeededOrchestrationRules.DOOHeader and Header.customerPoNumber equals ignore case "MyValue"

Here's how you can fix that: 

If Header is a DooSeededOrchestrationRules.DOOHeader and Header.customerPoNumber equals ignore case "MyValue" and Header.customerPoNumber isn't null

Fix Null Pointers When You Use longValue

Assume you encounter an error that's similar to:

Order management can't pause the sales order. oracle.apps.scm.doo.common.DooJboException: oracle.rules.rl.exceptions.RLNullPointerException: Attempted to invoke method "longValue" in class "java.lang.Long" on a null object reference. at line 6 in /Ruleset(StartAfterCond_RuleSet_18)/Rule(Rule1)/Pattern(v0_DOOFLine)/Test[1]. For details, see the Guidelines for Pausing Orchestration Processes topic on Oracle Help Center.

This might happen because your pause rule doesn't check to see whether the fulfillment line attribute that you're using to determine whether to pause the orchestration process contains a value. Assume you're using the paymentTermId attribute to pause the process, and you have this statement in your rule.

If Fline is a DooSeededOrchestrationRules.DOOFLine and Fline.paymentTermId is 100

Here's how you can fix that: 

If Fline is a DooSeededOrchestrationRules.DOOFLine and Fline.paymentTermId is 100 and Fline.paymentTermId isn't null

Fix Your Start After Condition

Assume you encounter an error that's similar to:

Order management can't pause the sales order. oracle.apps.scm.doo.common.DooJboException: oracle.rules.rl.exceptions.RLNullPointerException: Attempted to access property "sacType" in class "oracle.apps.scm.doo.common.businessRules.model.obr.facts.SacResult" with a null object reference. at line 7 in /Ruleset(StartAfterCond_RuleSet_18)/Rule(Rule1)/Action[1]. For details, see the Guidelines for Pausing Orchestration Processes topic on Oracle Help Center.

This might happen because you haven't correctly created an instance of your start after condition. To fix it, make sure you add an Assign New action that creates an instance of the start after condition first, and then assign that instance to sacResult. For example:

assign new DooSeededOrchestrationRules.SacResult SAC = new DooSeededOrchestrationRules.SacResult()
assign Header.SacResult = SAC

Next, set the priority to Highest on the rule that has this Assign New action. This priority makes sure Order Management runs the Assign New rule before it runs any other rules. The Assign New action creates an instance of the start after condition that the subsequent rules use at run time. For example, the subsequent rules set the values in that instance. If the instance doesn't exist, then you'll encounter the error.

For details, see the Set the Priority subtopic in Apply Logic in Business Rules.

Commonly Used Expressions

ExpressionCode

Possible Values

DooSeededOrchestrationRules.SacResult

SAC new DooSeededOrchestrationRules.SacResult()

Header.sacResult

SAC

Header.sacResult.sacType

DooSeededOrchestrationRules.SacResult.SAC_TYPE_IMMEDIATE

DooSeededOrchestrationRules.SacResult.SAC_TYPE_EVENT

DooSeededOrchestrationRules.SacResult.SAC_TYPE_TIMER

Header.sacResult.eventName

DooSeededOrchestrationRules.SacResult.SAC_SYSTEM_EVENT_IPC_PAUSE

You can reference the name of any event that you set up.

Header.sacResult.WaitDateTime

header.getAdjustedDate(null,number of days)

Commonly Used Date Functions

Function

Parameters

Description

Header.getAdjustedDate

Timestamp, double

Add a number of days, specified in the double format, to the date that your provide in the first parameter.

The return value is in the datetime format.

Header.subtractFromDate

Timestamp,Timestamp

Subtract the second parameter from the first parameter.

The return value is the number of days.

Header.getConvertedDate

Object

Convert various types of date objects in the datetime format.

Header.current_date

Not applicable

Return the system date in the datetime format.

Related Topics