Add Actions to an Orchestrated Integration

You can add actions to your integrations.

Topics

• Loop over Repeating Elements with a For-Each Action

• Route Expressions with Switch Action Branches

• Manage a Group of Actions and Fault Handlers with a Scope Action

• Assign Values to Scalar Variables in an Assign Action

• Loop Over Actions or Invoke Connections While a Condition is Satisfied with a While Action

• Send Notification Emails During Stages of the Integration with a Notification Action

• Build Complex Assignment Statements with a Stitch Action

• Delay Integration Execution for a Specified Time Period with a Wait Action

• Add Global Fault Handling to Orchestrated Integrations

• Catch Faults with a Re-throw Fault Action

• Throw Faults with a Throw New Fault Action

• Process Files in Scheduled Integrations with a Stage File Action

• Log Messages with a Logger Action

• Add a JavaScript Action

• Add Placeholder Notes with a Note Action

• Translate an EDI Document with the B2B Action

Loop over Repeating Elements with a For-Each Action

The for-each action enables you to loop over a repeating element and execute one or more actions within the scope of the for-each action. The number of loop iterations is based on a user-selected repeating element. For example, you may have an integration in which you have downloaded a number of files and want to loop over the output of the files. The for-each action enables you to perform this task.

Creating a For-Each Action

Note:

When you configure a stop action inside a for-each action, the entire integration is terminated when the for-each action is executed for the first time. The for-each action is not allowed to execute more than once. The stop action does not display any message describing this behavior during design time.

1. Add a for-each action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the For Each action to the appropriate location.
   • Click at the location where you want to add the for-each action, then select For Each.

   The For Each dialog is displayed.

2. Expand the Source tree to select an element.

3. Drag a repeatable element to the Repeating Element field. This is the element over which to loop.

   Note:

   Note the following restrictions:

   • The selected element must be repetitive. You can identify repetitive elements by the two-bar icon to the left of the element name.
     
     Description of the illustration repeating_element_sign.png
     

   • Any parent of the selected element must not be repetitive.

   • The data type of the selected element must be scalar.

   • Global and nonglobal repeated elements can be selected.

   • If you have a repeating element within another repeating element (that is, a list within a list), you must first create a for-each action and loop over the parent list. This gives you access to the child list during every iteration. You can then create a second for-each action within the scope of the first for-each action and loop over the child list.

   For this example, the element over which to loop is ICSFile.

4. Enter a name in the Name field and an optional description of the action in the Description field.

   For every iteration of the loop, there is a single reference to the repeating element (ICSFile). A current element name file is required for this action to occur.

5. Enter an alias for the current file of the iteration in the Current Element Name field.
   
   Description of the illustration repeating_element_drag.png
   

   Note:

   If you drag a for-each action into a scheduled integration or the for-each action is not inside a while action, for-each action, scope action, and so on, an additional field called Process items in parallel is visible at the bottom of the dialog.
   
   

   When selected, iterations of the for-each action are run in parallel. For example, if an integration processes a list of files with a for-each loop created over every file, the processing of the entire file is done in parallel for every file. If a variable is declared outside a for-each loop with Process items in parallel selected and updated within the for-each loop, the last updated value for that variable is available outside of the loop. Also, the degree of parallelism (DOP) is set to 1 to avoid concurrency issues.

6. Click Done.

   The for-each action is displayed in the canvas. A looping arrow indicates that this action performs repetitive looping.

7. Drag other actions inside the for-each action to define what should happen during each iteration of the loop. For this example, scope and switch actions are defined within the for-each action.
   
   Description of the illustration for_each_action.png
   

Tracking the Status of a For-Each Action During Runtime

You can track the status of the for-each action in the Track Instances page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

1. In the left navigation pane, click Home > Monitoring > Integrations > Tracking.

2. Click the business identifier value of the integration to track.

   The integration flow (including any for-each actions) is displayed. Any for-each action failures are identified by red arrows.

3. Select View Activity Stream from the menu.

   Details about processing status (including any for-each actions) are displayed, including any failures. If failures are inside the for-each action, the iteration number and other details are displayed. If processing is successful, no details and counts are displayed.

Related Documentation

The following sections provide examples of using a for-each action in an integration:

• Use Bulk Response Operations in an Integration in Using the Salesforce Adapter with Oracle Integration Generation 2
• Process Large Data Sets Asynchronously with Different Bulk Import Operations in Using the Marketo Adapter with Oracle Integration Generation 2
• Subscribe to Atom Feeds in a Scheduled Integration in Using the Oracle HCM Cloud Adapter with Oracle Integration Generation 2
• Invoke an Endpoint Dynamically in Using the Oracle ERP Cloud Adapter with Oracle Integration Generation 2
• Create an Integration to Import and Process Bulk Files in Using the FTP Adapter with Oracle Integration Generation 2

Route Expressions with Switch Action Branches

You can define switch action branches to add routing expressions in your integration. The switch action takes the first branch that evaluates to true. The other branches are ignored. A switch is essentially single-threaded.

To define switch action branches:

1. Add a switch action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Switch action to the appropriate location.
   • Click at the location where you want to add the switch action, then select Switch.

   Note:

   Nested switches are supported.
   Two branches are automatically created:

   • Undefined (first) branch: You must define a routing expression for this branch.

   • Otherwise (second) branch: This branch is taken if the routing expression for the initial branch does not resolve to true.

   Note:

   To add more branches, click the question mark in the switch activity to invoke a menu.

2. Click the Undefined branch icon.

3. Select the Edit icon from the menu that is displayed. This invokes the Expression Builder.

4. Define a routing expression, then click Close. XPath version 2.0 functions are supported. Base 64 encode and decode functions that process data confidentially across layers and functions that return boolean results are also supported. Functions that return nonboolean values are not supported.

   For this example, the following expression is defined:

   $FetchContactAssign = "failed" 

   You can now define different data flows for both the defined and otherwise branches in the switch activity.

5. Drag other actions and invokes into the switch action as required for your integration. For this example, scope actions are defined for both switch action branches.
   
   Description of the illustration switch_action.png
   

Related Documentation

The following sections provide examples of using a switch action in an integration:

• Invoke an Endpoint Dynamically in Using the Oracle ERP Cloud Adapter with Oracle Integration Generation 2
• Design an Asynchronous Search Operation with Pagination in Using the Oracle NetSuite Adapter with Oracle Integration Generation 2
• Use the Extract API in a Scheduled Orchestrated Integration in Using the SAP Concur Adapter with Oracle Integration Generation 2
• Use the Pagination Concept in an Integration in Using the Jira Adapter with Oracle Integration Generation 2

Manage a Group of Actions and Fault Handlers with a Scope Action

You can manage a group of actions with a scope action. The scope action is essentially a collection of child actions and invokes that can have their own fault handlers. The scope action provides the behavior context for the child elements. The elements defined in the parent scope have local visibility inside this scope. Anything that you can do in an integration such as designing invokes, mappings, and actions can be done in a scope action.

Note:

Scopes can have fault handlers in which specific faults can be caught and rethrown. However, in the case of connectivity agent-based invokes, the named fault handlers are not executed. All fault handling must be done in the default fault handler.

• Creating a Scope Action
• Add Nested Scopes to a Scope Action
• Reposition a Scope Action in an Integration
• Tracking the Status of a Scope Action During Runtime
• Renaming a Scope

Creating a Scope Action

To create a scope action:

1. Add a scope action to an integration in either of the following ways:
   • On the right side of the canvas, click and drag the Scope action to the appropriate location.
   • Click at the location where you want to add the scope action, then select Scope.

2. Enter a name and optional description when prompted, and click Create.

   The action is displayed in the integration.
   
   Description of the illustration scope_action.png
   

3. Drag and design appropriate actions, mappings, and invokes into the scope action.

   When you add invokes to a scope, the named faults associated with the invokes are added for selection to the Fault Handler section of the scope. These are faults that the invoke can handle. The uniqueness of the named faults is defined by the qname of the fault. If there are multiple invokes that define the qname fault, the fault (at runtime) can respond to any invoke. The various invokes cannot be differentiated if their qnames are not unique.

4. Select appropriate named faults.

   You can also define catch all blocks for fault handling through use of the raise error action in the Fault Handler section of the scope action. Catch all blocks are processed if an invoke throws a fault, but there is not a specific catch named for it. See Catch Faults with a Re-throw Fault Action.

5. Collapse the scope action by clicking the collapse icon in the upper left corner to condense the view of your integration. You can expand it again by clicking the expand icon.

Note:

Note the following issues when using the REST Adapter with fault handling.

• For orchestrated integrations with multiple REST Adapter invoke connections, only one handler can be defined when there are multiple invokes in an integration with scopes. Though the fault handler options are available for each invoke in the scope, it always points to one single handler.

• If you add a new fault handler into a 17.4.5 integration using an old adapter configuration (for example, a pre-17.4.5 configuration from a prebuilt or older integration), the fault handler does not work. Before adding a fault handler to the REST Adapter endpoints, ensure that the endpoints were created/edited in version 17.4.5 or later.

Add Nested Scopes to a Scope Action

You can add nested (child) scope actions to a basic scope action. This provides a more sophisticated way of organizing or separating actions into a subsection of the integration. A nested scope provides the following capabilities:

• Behaves the same way as a basic scope. It provides its own container of child actions and fault handlers.
• There is no limitation to the levels of nesting. Even a scope’s fault handlers can have nested scopes.

1. Drag a scope inside an existing scope.
   
   
   Description of the illustration nested_scope.png
   
   
2. Add actions and fault handlers to the nested scope, as necessary.

Reposition a Scope Action in an Integration

You can reposition a scope action in an integration. For example, you can move a scope from one part of an integration into a branch of a switch action.

1. Find the scope action to reposition.
2. Inside the scope, click . This collapses the scope.
3. Click Reposition above the integration canvas to enter reposition mode.
4. Drag the scope action to the plus sign location inside the switch action at which to place it.
5. After repositioning is complete, click Reposition to return to regular integration design mode.

Note:

Only collapsed scopes can currently be repositioned. Other container actions such as while actions, switch actions, for-each actions, and so on cannot be repositioned. You can move noncontainer actions (for example, assign actions, notification actions, and so on) by using the same reposition mechanism as with a scope action.

Tracking the Status of a Scope Action During Runtime

You can track the status of the scope action in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

1. In the left navigation pane, select Home > Monitoring > Integrations > Tracking.

2. Click the business identifier value of the integration to track.

   Depending upon runtime execution, several scope execution states can be displayed in the diagram:

   • Scope execution succeeds and is displayed in green. Because the fault handler is not executed, the Fault Handler section of the scope remains hidden.

   • Scope execution fails and is displayed in red, but the fault handler succeeds in handling the fault and is displayed in green. Execution continues after the scope. Because the fault handler was executed, the Fault Handler section of the scope is visible.

   • Both the scope and fault handler fail. Both are displayed in red. Both the scope and the Fault Handler section are displayed.

3. Select View Activity Stream from the menu.

   Details about processing status are displayed.

See Track Business Identifiers in Integrations During Runtime for additional details.

Renaming a Scope

1. Open the integration that includes the scope to rename.
2. Click to collapse the scope action.
3. Click the scope and select .
4. Change the name and click Save.

Assign Values to Scalar Variables in an Assign Action

You can assign values to scalar variables in orchestrated integrations using the Expression Builder.

Note:

• Variables created inside a scope action or a looping action (for example, a for-each or while action) are not directly accessible outside the scope/looping action. To access the variables (local) outside a scope/looping action, create a global variable using an assign action above the scope/looping action. Assign the local variable to this global variable and then use it outside the scope/loop action.

• Values cannot be assigned to other variable types, such as complex types.

1. Add an assign action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Assign action to the appropriate location.
   • Click at the location where you want to add the assign action, then select Assign.

2. Enter an assignment name and optional description when prompted by the Assignments dialog, then click OK.

3. Enter a name for the assignment in the Name field, then click the Expression Builder icon at the far right. Assignment names are case sensitive.

   Note:

   Once you navigate away from the Assign page (for example, go to the Expression Builder or close the Assign page), you can no longer change the name of the assign variable.

4. Build an expression, then click Close. See Create Routing Expression Logic in Both Expression Mode and Condition Mode. The expression is automatically saved in edit mode.
   
   Description of the illustration assign_action_expr.png
   

5. Click Yes when prompted to save your changes.

   The expression value is displayed in the Value field.

6. Click the Add icon to add multiple assignments to the assign action. For example:
   
   Description of the illustration assign_action_expr2.png
   

   You can also define an assignment with a value from a previously defined assignment.

7. Click Save.

Variable assignments can be of greater complexity. For example, you can use assignments in switch activities and in maps. For this example, the upper branch of a switch action is taken (if $FetchContactAssign = "failed"), which executes the contactCreateProcessing scope. Otherwise, the contactUpdateSkip scope is executed.

Description of the illustration assign_action_in_int.png

You can also configure the primary tracking variable and both custom field tracking variables (update and access values) in the Expression Builder. You can map tracking variables to output variables or create complex expressions for an assign or switch activity. The primary parameter and two custom parameters are available in the From palette, but only the two custom parameters are present on the To palette for the assign activity.

• All tracking variables are of type string (all that assignments support).

• All three tracking variable entries are present even if you choose not to model them. The name and XPath can be empty for tracking.

• Editing or deleting the tracking variables only updates the name and XPath nodes in that particular tracking variable element.

• The tracking variables have static names. Therefore, it is possible to set a tracking variable somewhere in the flow, but not initialize it with a value and a name in the Tracking dialog.

• The primary tracking variable cannot be assigned any value in between the flow.

• You cannot create a new variable with the same names as any of the statically name tracking variables.

Related Documentation

The following sections provide examples of using an assign action in an integration:

• Retrieve the Name and IDs from Account Records with the queryMore Operation in Using the Salesforce Adapter with Oracle Integration Generation 2
• Design a Basic Asynchronous CRUD Operation in Using the Oracle NetSuite Adapter with Oracle Integration Generation 2
• Use the Extract API in a Scheduled Orchestrated Integration in Using the SAP Concur Adapter with Oracle Integration Generation 2
• Use the Pagination Concept in an Integration in Using the Jira Adapter with Oracle Integration Generation 2

Loop Over Actions or Invoke Connections While a Condition is Satisfied with a While Action

The while action enables you to loop over actions or invoke connections as long as a specific condition is met. You define the condition for the while loop in the Expression Builder. The while action is available in both scheduled and nonscheduled orchestrations.

Creating a While Action

Note:

Variables used in while action statements can be of several types, including number, string, and boolean types.

1. Add a while action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the While action to the appropriate location.
   • Click at the location where you want to add the while action, then select While.

2. Enter a name and optional description for the while action when prompted, then click OK.

   The Expression Builder is displayed.

3. Expand the Source tree to select an element. You can also add functions and operations.

4. Select an element, and click to the New Condition fields. For this example, while the ZIP code equals the value for $result, the integration loops over the condition. As soon as the condition is not met, the looping ends.

   
   
   Description of the illustration while_activity.png
   

5. Click Close. The values of the while action are displayed in the canvas.

   
   
   Description of the illustration while_activity_values.png
   

6. If you want to edit the name or expression, click the respective Edit icon. Otherwise, click to return to the integration canvas.

   The while action is displayed in the canvas. A looping arrow indicates that this action performs repetitive looping while the condition is satisfied.
   
   Description of the illustration while_activity_in_canvas.png
   

7. Drag invoke connections or other actions for configuration to the Plus sign that is displayed inside the while action. These invoke connections and actions are executed as long as the condition of the while action is met.

   Note:

   Deleting a while action has no impact on downstream processing of the integration because the while action does not have any output. Any changes in the upstream actions in the integration that impact the while condition result in the display of a warning icon on the while action.

Tracking the Status of a While Action During Runtime

During runtime, you can track the status of the while action in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

1. In the left navigation pane, click Home > Monitoring > Integrations > Tracking.

2. Click the business identifier value of the integration to track.

   The integration flow (including any while actions) is displayed. Any while action failures are identified by red arrows.

3. Select View Activity Stream from the menu.

   Details about processing status (including any while actions) are displayed, including any failures. If failures are inside the while action, the iteration number and other details are displayed. If processing is successful, no details and counts are displayed. Any actions (including any inner while actions) inside the main while action are not recorded.

Related Documentation

The following sections provide examples of using a while action in an integration:

• Retrieve the Name and IDs from Account Records with the queryMore Operation in Using the Salesforce Adapter with Oracle Integration Generation 2
• Retrieve Issue Details Using the Jira Query Language (JQL) in Using the Jira Adapter with Oracle Integration Generation 2
• Use Pagination in an Integration in Using the Shopify Adapter with Oracle Integration Generation 2

Send Notification Emails During Stages of the Integration with a Notification Action

You can send a notification email to relevant users at specific points in the execution of an integration. You can set the to, from, and subject parts of an email. You can create the body part of an email using parameters defined in the Expression Builder. You can also add attachments to the email if your integration includes them. The total size limit on a notification email is 1 MB for Oracle Integration and 2 MB for Oracle Integration Generation 2. Both the email body and attachment are considered in calculating the total size.

1. Add a notification action to an integration in either of the following ways:
   • On the right side of the canvas, click and drag the Notification action to the appropriate location.
   • Click at the location where you want to add the notification action, then select Notification.
2. Enter a name and optional description for the notification action when prompted, then click OK.
3. For the From, To, and Subject fields, click the Expression Builder icons to build the expressions to use. You can also manually enter plain text in the Subject field. You can provide an email address in the From field that is approved as the sender for service failure alerts, system status reports, and integration error reports. You configure the approval email address to use in the From field on the Notifications page that is accessible from Settings > Notifications. See Send Service Failure Alerts, System Status Reports, and Integration Error Reports by Notification Emails.
4. In the Body field, enter a message using plain text, plain HTML formatting that you create in a separate HTML editing tool and paste into this field, or parameters that you create in the table immediately below this field. After creating parameters, enter them inside { } brackets.
5. To add a parameter name and value, click the Plus icon in the Parameters section.
6. Enter a parameter name and description.
7. Click the Expression Builder icons to define parameter values (for this example, name is created).
8. In the Attachments section, click the Plus icon to open a page to select an attachment file.
9. Select the attachments to add. You can edit or delete attachments once added. For this example, the integration includes three file reference attachments (highlighted in yellow) that are available for selection:
   • An attachment from a REST Adapter connection
   • A file reference from a stage file write operation
   • A file reference from an FTP Adapter download operation

   
   

   
   Description of the illustration notification_attach.png

   
   
10. Click Close, then save your updates when prompted.
    When complete, the Notification page looks as follows for this example:
    

    
    Description of the illustration notification_action.png

    
    
11. Click Done.

When the email notification is received during integration runtime, the parameter name is replaced with a dynamic value.

Note:

• Deleting the notification action does not impact downstream activities because a notification does not have any output. Changes in the upstream activities impact the notification when they are used either in the From, To, or Subject fields or in the body parameters. For example, if the name example used in this section is modified, the parameter assignment become invalid.

• Notification actions are treated as asynchronous actions with no failure. For example, assume you include a notification action in an integration and disable the sendmail service on your host, which prevents you from receiving an email notification. The integration instance appears as completed on the Track Instances page and there is no error message in the instance. This is the expected behavior. You can only see an issue with the instance if you open the integration instance and view the notification action.

Set the content-type in a Notification Action

You can set the content-type in an email body of a notification action.

Code the content-type as follows:

Description of the illustration notification_content_type.png

Build Complex Assignment Statements with a Stitch Action

You can incrementally build a message payload from one or more existing payloads with the stitch action. The stitch action provides an editor that enables you to assign values to variables.

The stitch action supports scalar and complex type variables, arrays, and partial and full message payloads. Complex variables are not limited to message payloads.

The stitch action differs from the mapper and assign action in the following ways:

Mapper and Assign Action Capabilities	Stitch Action Capabilities
Mapper: Only generates full message payloads. If you attempt to map into an existing message payload, a full replacement of that payload occurs.	Supports both partial and full replacement of the message payload.
Assign action: Limited to scalar type variables. Complex objects or full payloads are not supported.	Supports both scalar and complex type variables.

You can perform the following complex assignments (operations) on variables (and child elements of variables) with the stitch action:

• Append: Appends at the end of the repeating/unbounded target element, the selected element, or the value. For example, you have an existing purchase order payload containing five lines and want to add a sixth line. The stitch action enables you to append a sixth line to the existing array of lines in the purchase order.
• Assign: Places the selected value/element/attribute into the target element/attribute, overriding any existing data in the target element/attribute. For example, you want to change the current address in an existing purchase order. The stitch action enables you to change the address. You can either map fields individually or copy the address object itself.
• Remove: Removes the target element/attribute from the variable. For example, you have an existing purchase order payload and want to remove the price to enable the end point application to calculate a new price. The stitch action enables you to remove the price. For repeating/unbounded elements, all instances are removed unless a specific instance is selected by index or predicates.

Before using the stitch action, understand the use cases. See Stitch Editor Use Cases.

To build complex assignment statements with a stitch action:

1. Add a stitch action to an integration in either of the following ways:
   • On the right side of the canvas, click and drag the Data Stitch to the location where you want to create the complex assignment statement.
   • Click at the location where you want to add the complex assignment statement, then select Data Stitch.
   The right pane is refreshed to display the stitch editor.
2. Enter a name and optional description, then click Configure.

   The editor is refreshed to display the Variable list.

3. Select a variable in either of two ways:
   1. Click the Variable list and select a variable.
   2. Click to create a global variable. Once created, the variable is available for selection from the Variable list.
4. From the Variable list, select a variable to update. Global variables and business identifier tracking variables are displayed for selection. A data element is a subcomponent of a variable. A complex variable conforms to a series of data elements.

   The stitch editor is refreshed to show a list for selecting the operation to perform and the value.

   
   
   
   Description of the illustration stitch_select_var.png
   
   
5. From the Operation list, select the operation to perform on the variable: Append, Assign, or Remove.
6. From the Value list, select a value for the variable. If you selected the Remove operation, the Value list is not displayed.

   The page is refreshed to display a plus sign for creating additional complex assignment statements.
   
   Description of the illustration stitch_select_op.png
   

7. Click the plus sign if you want to create additional complex assignment statements.
8. Create as many statements as necessary.
9. When complete, click X in the upper right corner to save your statements and close the stitch editor.
10. Click the View or Edit icon for the stitch action in the integration to view your assignment statements.

    For this example, two statements were created.
    
    Description of the illustration stitch_second_state.png
    

    You can also define the sequence of variables to update. For example, if you want to copy an address, and then override a child element such as street, place these statements in the correct order of execution.

Delay Integration Execution for a Specified Time Period with a Wait Action

The wait action enables you to delay the execution of an integration for a specified period of time. Use this action in scheduled and asynchronous orchestrated integrations. A typical use for this action is to invoke a specific operation at a certain time. Wait actions are only available in asynchronous and fire-and-forget integrations.

Creating a Wait Action

1. Add a wait action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Wait action to the appropriate location.
   • Click at the location where you want to add the wait action, then select Wait.
2. Enter the following details when prompted, then click OK.

   • Name of the action.

   • Optional description of the action.

   • Number of hours, minutes, and seconds to wait before executing the integration. Enter positive integer values between 0 and 59. All three fields cannot be zero. The total wait time cannot exceed six hours.

3. If you want to edit or delete the action, click it and select an option from the menu that is displayed.

Tracking the Status of a Wait Action During Runtime

During runtime, you can track the status of the wait action in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

1. In the left navigation pane, click Home > Monitoring > Integrations > Tracking.

2. Click the business identifier value of the integration to track.

   The integration flow (including any wait actions) is displayed.

3. Select View Activity Stream from the menu.

   Details about processing status (including any wait actions) are displayed.

Related Documentation

The following sections provide examples of using a wait action in an integration:

• Use the Extract API in a Scheduled Orchestrated Integration in Using the SAP Concur Adapter with Oracle Integration Generation 2
• Process RaaS Reports that Support the Delivery of Data in CSV Format in Using the Workday Adapter with Oracle Integration Generation 2
• Export Candidate Data from Oracle Talent Acquisition Cloud (Taleo EE) in Using the Oracle Taleo Enterprise Edition Adapter with Oracle Integration Generation 2

Add Global Fault Handling to Orchestrated Integrations

You can add global fault handling to orchestrated integrations. This functionality enables you to direct business faults back to the caller or apply business logic before sending faults to the error handling framework. You can add fault handling to any integration type (for example, asynchronous, synchronous, or scheduled fire-and-forget (no response expected)).

Adding a Global Fault

To add a global fault:

1. Design an orchestrated integration. The integration does not need to be complete. You can add fault handling at any time. However, the integration must include an invoke connection.

2. In the upper left corner of the integration canvas, select Global Fault.

   The Global Fault Handler page is displayed. The initial trigger in your integration is automatically connected to an initial Re-throw Fault action that cannot be deleted. However, you can add and delete other Re-throw Fault actions. The Re-throw Fault action does not respond back to the trigger. Instead, details collected by the Re-throw Fault action are sent to the error handling framework.
   
   Description of the illustration global_fault.png
   

   You can add actions to design specific fault handling logic in the integration. For example, you can add Switch, Stop, or additional actions, as needed.

3. Click the upper branch, then select the Edit icon.
   
   Description of the illustration global_fault_switch.png
   The Expression Builder is displayed. In the Source tree, the schedule (trigger) and target fault handling information are both displayed.
   
   Description of the illustration ics_source_target.png
   

   Note:

   The Expression Builder includes the following functions under Functions > Integration Cloud for designing fault handling:

   • getFaultAsString (returns the fault as a string value)

   • getFaultAsXML (the fault as an XML element)

   • getFaultedActionName (returns the fault of the action)

   • getFaultName (returns the fault name)

   • getFlowId (returns the flow ID of the integration)

   These functions are only available within the Expression Builder in orchestrated integrations.

4. Build an expression to capture fault handling information. For example:

   $TargetApplicationObject1/nssrcmpr:fault/nssrcmpr:details = "ERROR"

5. Drag a Stop action to the Otherwise branch of the switch action.

   The fault handling logic is now complete. For this example, if an error occurs, error details are captured and sent to the error handling framework (as indicated by the Re-throw Fault action). If no error occurs, the fault handling stops and nothing is sent to the error handling framework (as indicated by the Stop action).

6. Click Global Fault to return to edit mode in the integration canvas.

7. Click Save.

8. Complete design of the orchestrated integration.

9. Click Save, then click Close.

10. Activate the integration.

Tracking the Status of a Global Fault During Runtime

During runtime, you can track the status of global faults in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

1. In the left navigation pane, click Home > Monitoring > Integrations > Tracking.

2. Click the business identifier value of the integration to track.

   Global fault handling is only invoked if there is a failure in the integration flow. Failures are identified by red arrows.

3. Select View Activity Stream from the menu.

   Details about where the failure occurred and the global fault handler being triggered are displayed.

   If the global fault handler successfully handled the error, the integration is displayed as COMPLETED on the Track Instances page.

Catch Faults with a Re-throw Fault Action

You can send failed messages to the error hospital for further analysis with a re-throw fault action. If the integration contains a defined global fault, the error captured by the re-throw fault action is sent through the global fault and onto the error hospital for analysis. If no global fault is defined, the fault is sent directly to the error hospital for analysis. The re-throw fault action can only be placed inside the fault handler section of a scope action. The re-throw fault action operates as a catch all block and is processed if a fault is thrown by an invoke action in the scope. However, the re-throw fault action does not have a specific catch named for it. The following example describes how to define a re-throw fault action in a scope action.

To catch faults with a re-throw fault action:

1. Add a re-throw fault action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Re-throw Fault action to the appropriate location.
   • Click at the location where you want to add the re-throw fault action, then select Re-throw Fault.

2. Create an integration that includes a scope action. See Manage a Group of Actions and Fault Handlers with a Scope Action.

3. Click Fault Handler on the right side of the scope.

4. On the right side of the canvas, click Actions to expand the panel.

5. Drag the Re-throw Fault icon to the plus sign in the scope action.
   
   Description of the illustration raise_error_add_scope.png
   

   Any faults captured by this action are passed to the error hospital for analysis. Because of this fault, the integration flow is terminated.

6. Click the < icon to the left of Fault Handler to return to the scope action.

   The Re-throw Fault icon is hidden.

7. Design additional logic in the scope action.

8. To return to the Re-throw Fault icon, click Fault Handler, then select Default Handler. The green check mark indicates that this fault handler is defined in the scope action.

   
   
   Description of the illustration raise_error_return.png
   

Throw Faults with a Throw New Fault Action

You can create and throw your own faults in an integration with a throw new fault action. During configuration of this action, you define the condition under which to throw the fault and the point in the integration at which to throw the fault. You can add this action at the end of a block (for example, a for-each action, switch action, and so on). Nothing can be dropped after this action in the block.

1. Add a throw new fault action to an integration in either of the following ways:
   • On the right side of the canvas, click and drag the Throw New Fault action to the appropriate location.
   • Click at the location where you want to add the throw new fault action, then select Throw New Fault.
2. Enter a name and description of the action, then click OK.
   The Throw New Fault page is displayed.
3. Define the action:

   Element	Description
   Code	Click the Edit icon to create an expression in the Expression Builder. This is a mandatory field.
   Reason	Click the Edit icon to define a reason for the error in the Expression Builder.
   Details	Click the Edit icon to define additional error details in the Expression Builder.
   Skip Condition	Define a condition to prevent the fault from being throw in the Skip Condition version of the Expression Builder.

   
   

   
   Description of the illustration throw_new_fault.png

   
   

   The throw new fault action is displayed in the integration.

   If a skip condition is not defined, the throw new fault action is displayed with a dashed line connecting to the next action. This signifies that the action continues processing only after executing the fault.
   
   

   If a skip condition is defined, the line connecting to the next action is solid. The solid line indicates that it is possible that the execution of the integration bypasses the fault and goes straight through to the next action.
   
   

   Deleting the throw new fault action has no impact on downstream activities because this error does not have any output. Any changes to upstream activities triggers a throw new fault action validation because both the Code, Reason, and Details fields in the Throw New Fault page can point to flow input or upstream outputs.

Process Files in Scheduled Integrations with a Stage File Action

You can use the stage file action to process files or file references in scheduled integrations. The stage file action can process each file downloaded by the FTP Adapter. The stage file action can read (and remove any trailer), write, zip, unzip, and list files in a staged location known to Oracle Integration.

The stage file action can also read (and remove any trailer) and unzip referenced files in a staged location. The stage file action is similar in functionality to adapters. However, unlike adapters, you do not need to create a connection to use the stage file action. The stage file action has no credential properties and security policies. The stage file action also differs from the File Adapter and FTP Adapter in that it provides the ability to define a file format for read and write operations. For the stage file action to process or act upon files and attachments, they must be available in Oracle Integration. Make the files available in Oracle Integration either using the download operation in the FTP Adapter or consuming the SOAP/REST APIs that return multipart or MTOM attachments. Oracle Integration flows exposed as REST endpoints using the REST Adapter and exposing an interface to accept multipart attachments also automatically stage files in Oracle Integration when the requests are posted to the endpoint.

For example, you may include a stage file action in an integration as follows:

• Configure an FTP Adapter with the following settings:

  • Download File operation

  • Unzip the File option

  • Input directory and download directory path

• Because the ZIP file may contain multiple files, configure a for-each action below the FTP Adapter to iterate over repeated elements.

• To read each file from the input directory, configure a stage file action below the for-each action to read each file from the input directory as follows:

  • In the Expression Builder, specify the file name and directory from which to read the file.

  • Specify the schema file by loading a comma-separated value (CSV) file that contains the data structure.

Note:

• Do not use special characters in schema names (such as #). Otherwise, integration activation fails.

• The stage file action only supports the .zip file format. For example, if the input file is .gz format, Oracle Integration cannot unzip or read the contents of the file.

Process File References

You can specify a file reference to process when you select to read the entire file, read a file in segments, or unzip a file.

This feature provides the following benefits:

• Processes upstream operations that provide a file reference. For example, a REST Adapter connection enables you to download an attachment into an attachment folder. The REST Adapter provides a file reference, but does not provide a file name or directory. The stage file action provides both these options.

  The following operations provide file references:

  • Attachment reference (REST Adapter attachments)

  • Stream reference (REST Adapter invoke response)

  • MTOM (for a SOAP Adapter invoke connection response)

  • FileReference (for an FTP Adapter)

• Provides a prerequisite to process encrypted content. This means that other adapters do not need to duplicate the decryption operation.

• Encrypts content as a post-processing operation. Therefore, other adapters do not need to duplicate the encryption operation.

Creating Local Files

Note the following details about local file behavior:

• Local Oracle Integrationfolders can only be created using a stage file write operation from within the integration.

• Within the integration scope, the file is available for further processing.

• Using stage file operations such as read, write, and others enables you to read the contents in the scope in which the file is available.

• The file is not visible outside the scope in which it was created.

• You can use stage file write-related variables in mapping operations to point to this virtual file.

• Once the integration moves outside the scope of file visibility, the local file is deleted.

Configure a Stage File Action

You can configure a stage file action with the Configure Stage File Action wizard.

Restrictions on Using Stage File Action Operations with the File/Attachment Features of the Connectivity Agent

When configuring the stage file action in the Configure Stage File Action wizard, note that there are restrictions on using some operations with the connectivity agent.

• List File operation: Files uploaded through the connectivity agent are not available with the List File operation.
• Read Entire File and Read File in Segments operations: Files uploaded through the connectivity agent can only be read with a file reference.
• Zip File operation: Files uploaded through the connectivity agent are not available with the Zip File operation.
• Unzip File operation: Files uploaded through the connectivity agent can only be unzipped using a file reference.

Start the Configure Stage File Action Wizard

Note:

Stage file operations cannot share a schema root element that defines the record structure if they are working with different file formats and record structures. Either the target namespace or the root element name must be unique while parsing different file formats and records structures.

1. Add a stage file action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Stage File action to the appropriate location.
   • Click at the location where you want to add the stage file action, then select Stage File.

2. Complete the fields on the Basic Info page, and click Next.

   The Configure Operation page is displayed.

• Configuring Stage File Operations
• Defining the Schema File
• Defining the Schema Format
• Reviewing the Stage File Action in the Integration Canvas

Configuring Stage File Operations

The Configure Operation page enables you to define the file operations to perform. You can select to list a file, read an entire file, read files in chunked sizes, unzip a file, write a file, or zip a file, You use the Expression Builder to build the specific details of your operation. The Expression Builder shows all upstream sources (including assignments, for-each actions, invoke connections, and so on) for you to specify these details. You can select to encrypt and decrypt files with a Pretty Good Privacy (PGP) authentication key that you configured on the Upload Certificate page. See Upload an SSL Certificate.

1. From the dropdown list, select the stage file operation to perform. The page refreshes to display fields appropriate to your selection. There are restrictions when using the connectivity agent with some stage file action operations. See Restrictions on Using Stage File Action Operations with the File/Attachment Features of the Connectivity Agent.

   • Read Entire File

   • Read File in Segments (for chunking files)

   • Write File

   • Unzip File

   • Zip File

   • Encrypt File

   • Decrypt File

   • List File

   Read Entire File

   Table 4-1 - Read Entire File

   Property	Description
   Configure File Reference	Yes: Select to process an upstream operation that provides a file reference. Once selected, you specify the file reference. No: Select to process a file name.
   Specify the File Reference (Appears if you select Yes for the Configure File Reference.)	Click the Expression Builder icon to specify a file reference.
   Specify the File Name (Appears if you select No for the Configure File Reference.)	Click the Expression Builder icon to build an expression to specify the file name (for example, /compress:schedule/compress:start Time). Note: The file size must be less than 10 MB. For files greater than 10 MB, use the Read File in Segments operation.
   Specify the Directory to read from	Click the Expression Builder icon to build an expression to specify the directory from which to read files.
   Remove Trailer	Select to not remove the trailer, to remove the last row, or to remove the last n rows.
   Decrypt	Click the check box, then select the private key of the target location to use to decrypt the file.

   Read File in Segments

   This option enables you to read files in segments (chunks). Chunking files enables large files to be processed, one logical chunk at a time. A logical chunk (segment) is retrieved from a huge file, enabling the file to stay within memory constraints.

   You can also read large XML files containing repeating elements and multiple namespaces. A use case is provided. See Read Large XML Files Containing Multiple Namespaces.

   Note:

   • If you select the Read File in Segments operation, you cannot specify an opaque or JSON schema. If you do, you receive the following runtime error:

     NXSD has infinite loop.
     Flow has bad NXSD or bad input file which is causing infinite loop.
     Either NXSD is not designed properly or input file is not compatible with
     NXSD. Processing of file at stage read was not advancing and looping at same
     location in input file.
     Please download ICS flow and review NXSD file or inspect input file to ensure
     there are no infinite loop.
     Stage Read Failed

   Table 4-2 - Read File in Segments

   Property	Description
   Configure File Reference	Yes: Select to process an upstream operation that provides a file reference. No: Select to process a file name.
   Specify the File Reference (Appears if you select Yes for the Configure File Reference.)	Click the Expression Builder icon to specify a file reference.
   Specify the File Name (Appears if you select No for the Configure File Reference.)	Click the Expression Builder icon to build an expression to specify the file name. The Read File in Segments option creates a stage file action that includes a scope part. This enables you to drag actions inside the scope (such as for-each actions, additional stage file actions, and others) for more complex scenarios.
   Specify the Directory to read from	Click the Expression Builder icon to build an expression to specify the directory from which to read.
   Segment Size	Chunking files enables large files to be processed, one logical chunk at a time. A logical chunk (segment) is retrieved from a huge file, enabling the file to stay within memory constraints. Note: This field is not displayed when you add a new stage file action to an integration. The segment size defaults to 200 records and cannot be changed. This field is only displayed in existing stage file actions in which a segment size of other than 200 records is specified. For these scenarios, you can specify a value between 10 and 200 records.
   Process Sequentially	Select to read the segments sequentially.
   Remove Trailer	Select to not remove the trailer, to remove the last row, or to remove the last n rows.

   Write File

   Note:

   When writing to a stage file, there is no built-in support for headers. You must create headers by explicitly writing them to the file.

   Table 4-3 - Write File

   Property	Description
   Specify the File Name	Click the Expression Builder icon to build an expression to specify the file name.
   Specify the Output Directory	Click the Expression Builder icon to build an expression to specify the output directory.
   Append to Existing File	Optionally select to append records to the existing file. Note: If you append JSON or XML content, the final file is invalid XML or JSON.
   Encrypt	Click the check box, then select the public key of the target location to use to encrypt the file.

   Zip Files

   Table 4-4 - Zip Files

   Property	Description
   Specify the File Name	Click the Expression Builder icon to build an expression to specify the file name.
   Specify the Directory to zip	Click the Expression Builder icon to build an expression to specify the directory to ZIP.
   Specify the Output Directory	Click the Expression Builder icon to build an expression to specify the output directory in which to write a ZIP file.

   Unzip File

   Table 4-5 - Unzip File

   Property	Description
   Configure File Reference	Yes: Select to process an upstream operation that provides a ZIP file reference. Once selected, you specify the file reference and the directory in which to unzip the file. No: Select to process a ZIP file.
   Specify the File Reference (Appears if you select Yes for the Configure File Reference.)	Click the Expression Builder icon to specify a ZIP file reference.
   Specify the Zip File Name (Appears if you select No for the Configure File Reference.)	Click the Expression Builder icon to build an expression to specify the ZIP file name to read.
   Specify the Zip File Directory	Click the Expression Builder icon to build an expression to specify the directory in which to unzip the file.
   Specify the Directory to Unzip	Click the Expression Builder icon to build an expression to specify the directory in which to unzip files.

   Encrypt File

   Table 4-6 - Encrypt File

   Property	Description
   Specify the File Reference	Click the Expression Builder icon to specify a file reference.
   Specify the File Name	Click the Expression Builder icon to build an expression to specify the file name.
   Specify the Output Directory	Click the Expression Builder icon to build an expression to specify the output directory.
   Specify PGP Key to encrypt file	Select the private key of the target location to use to encrypt the file. You can encrypt a file up to 1 GB in size. When using the mapper, note that encrypt is visible as an element for mapping.

   Decrypt File

   Table 4-7 - Decrypt File

   Property	Description
   Specify the File Reference	Click the Expression Builder icon to specify a file reference.
   Specify the File Name	Click the Expression Builder icon to build an expression to specify the file name.
   Specify the Output Directory	Click the Expression Builder icon to build an expression to specify the output directory.
   Specify PGP Key to decrypt file	Select the private key of the target location to use to decrypt the file. You can decrypt a file up to 1 GB in size. When using the mapper, note that decrypt is visible as an element for mapping.

   List File

   Table 4-8 - List File

   Property	Description
   Specify the Directory to List Files from	Click the Expression Builder icon to build an expression to specify the directory from which to list files.
   Specify the File Pattern to use	Specify the pattern of the file name to transfer to the output directory. Click the ? icon for the list of supported patterns.
   List Files Recursively	Select to list the files recursively.

2. When complete, click Next.

   The Schema Options page is displayed if you selected a read or write stage file operation.

Defining the Schema File

The Schema Options page enables you to define a schema. This page is displayed if you selected a read or write stage file operation.

1. Provide the following details.

   Property	Description
   Do you want to specify the structure for the contents of the file for the payload?	Select Yes to define a schema format to use for the files to transfer. Select No if a schema is not required and you want to send opaque files (for example, a GIF or PNG file).
   Which one the following choices would be used to describe the structure of the file contents?	Select an option: Sample delimited document (erg. CSV): Select to create a new schema from a CSV file. On a subsequent page of this wizard, you are prompted to select the CSV file from which to create the schema. XML schema (XSD) document: Select to create a new schema from an XML schema (XSD) file. You can upload a ZIP file with nested XML schema files. Sample XML document (Single or No Name Space): Select to create a new schema from a sample XML file with a single or no name space. Sample JSON document: Select to create a new schema from a JSON file. EDI document: Select to create a new schema from an EDI X12 document, then select the character encoding that the imported EDI X12 document is expected to use.

2. When complete, click Next.

Defining the Schema Format

Based on your selection on the Schema Options page, the Format Definition page enables you to select the file from which to create a schema. This page is displayed if you selected a read or write stage file operation.

1. Follow the instructions below based on the schema option you selected.

   • Sample delimited document (e.g. CSV) (Table 4-9)

   • XML schema (XSD) document (Table 4-10)

   • Sample XML document (Single or No NameSpace) (Table 4-11)

   • Sample JSON document (Table 4-12)

   Table 4-9 - Sample Delimited Document (e.g. CSV)

   Element	Description
   Select the Delimited Data File	Select the delimited comma-separated value (CSV) file from which to create the schema file. The content of the file is then displayed at the bottom of the page. This field appears if you selected to create a new schema on the Basic Info page of the wizard.
   Enter the Record Name	Enter the record name. This becomes the parent element in the created schema file for the record names selected as column headers from the CSV file.
   Enter the Recordset Name	Enter the recordset name. This becomes the root element of the created schema file.
   Select the Field Delimiter	Select one of the following supported file delimiter options: Single space Comma Semicolon Tab Pipe (for example, Name|City|Country)
   Character Set	Select a character set. The selected value will be used as the encoding format while reading the sample data file.
   Optionally Enclosed By	This value causes occurrences of the selected delimiter to be ignored during processing. For example, when processing the following record: Fred,"2 Old Street, Old Town,Manchester",20-08-1954,0161-499-1718 If the selected Field Delimiter is “,” and the Optionally Enclosed By value is quot; (“), then the value 2 Old Street, Old Town,Manchester is treated as a single record column.
   Use the First Row as Column Headers	Displays by default the first row of the selected CSV file as the column headers.
   Detach	Select to edit the CSV file in a separate window.
   Mark All As Optional	Select to mark elements as optional in the schema file. By default, all elements are mandatory. You can also select the data type (for example, string, byte, integer, and so on) to use for each column in the table and mark specific elements as optional. While this option enables you to select all elements as optional, you must have at least one mandatory element to validate this page. This check box provides a convenient method to select the majority of elements as optional.

   Table 4-10 - XML Schema (XSD) Document

   Element	Description
   Select a New File	Select an existing XML schema file or schema archive file from the file system.
   Selected File Name	Displays the selected schema file name.
   Select the Element Name	Select the schema element. This field is displayed after the XML schema file is selected. The element name is treated as the root element in the uploaded schema file.
   Select Repeating Batch Element	Click the Expression Builder icon to build an expression to identify the repeating node in the schema to support payload chunking.

   Table 4-11 - Sample XML Document (Single or No NameSpace)

   Element	Description
   Select a New File	Select a sample XML document from the file system. The file must contain no namespace or a single namespace.
   Selected File Name	Displays the selected schema file name.
   Select the Schema Element	Select the schema element. This field is displayed after the sample XML file is selected. The element name is treated as the root element in the uploaded schema file.
   Select Repeating Batch Element	Click the Expression Builder icon to build an expression to identify the repeating node in the schema to support payload chunking.

   Table 4-12 - Sample JSON document

   Element	Description
   Select a New File	Select a sample JSON document from the file system.
   Selected File Name	Displays the selected schema file name.
   Select the Schema Element	Select the schema element. This field is displayed after the JSON file is selected. The element name is treated as the root element in the uploaded schema file.

2. Complete the fields, and click Next.

3. Review your selections on the Summary page, and click Done.

Reviewing the Stage File Action in the Integration Canvas

Once design is complete, the stage file action is displayed in the integration canvas.

• If you designed a stage file action with a Read File in Segments operation, a scope portion is created. Place your cursor over the icon to display a message indicating that segmentation (chunking) is enabled.

  
  
  

  You can drag additional actions into the scope part of the stage file action to perform tasks. For example, you can add a for-each action to the stage file action to process the segmented chunks of large files one record at a time. You can also add child stage file actions to perform further processing on each of the chunks. However, you cannot configure additional chunking on the child stage file action.
  
  Description of the illustration stage_file_chunk2.png
  

  Note:

  If a variable is declared outside of a loop of a stage file action that was configured with the Read File in Segments operation and updated within the stage file action loop, the last updated value for that variable is available outside of the loop. In such a case, the DOP (degree of parallelism) is set to 1 to avoid concurrency issues.

• If you designed a stage file action with an operation other than a Read File in Segments operation, a scope portion is not included.
  
  Description of the illustration stage_file_chunk3.png
  

Complete your integration design and configure any business identifiers for tracking fields in messages (including file storage-related parameters).

Related Documentation

The following sections provide examples of using a stage file action in an integration:

• Create an Integration to Import and Process Bulk Files in Using the FTP Adapter with Oracle Integration Generation 2
• Process RaaS Reports that Support the Delivery of Data in CSV Format in Using the Workday Adapter with Oracle Integration Generation 2
• Produce Messages to an Apache Kafka Topic in Using the Apache Kafka Adapter with Oracle Integration Generation 2
• Use Bulk Response Operations in an Integration in Using the Salesforce Adapter with Oracle Integration Generation 2

Log Messages with a Logger Action

You can log messages to the activity stream and diagnostic logs by adding the logger action at any point in the integration. You create a log message in the logger action that is a static message or variable-populated message in the Expression Builder.

Creating a Logger Action

To create a logger action:

1. Add a logger action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Log action to the appropriate location.
   • Click at the location where you want to add the log action, then select Log.

2. Enter a name and optional description, then click OK.

   The Logger page is displayed.

3. Select whether to always log this message or log it only when tracing is enabled. You can enable tracing when you activate an integration. See Activate an Integration.

4. Specify a static or variable-populated message to be displayed in the activity stream and diagnostic logs. Click the Expression Builder icon to create a message that includes variables. For this example, the logger is being configured to indicate that a specific file name is being read from an FTP server location.

   concat(“Filename is: ”,fileName)

5. Drag and configure additional Logger icons into the integration, as needed. For this example, the another logger is being configured to indicate that a file has been uploaded to a directory location.

   concat(“The file ”,fileName, “has been uploaded to “,directory)

6. When complete, click Close. For this example, a log action is included in the integration.
   
   Description of the illustration logger_action.png
   

Tracking the Status of a Logger Action During Runtime

During runtime, the messages in the loggers are written to the activity stream and diagnostic logs.

1. In the left navigation pane, click Home > Monitoring > Integrations > Tracking.

2. Select View Activity Stream from the menu.

   Details about processing status are displayed.

3. In the left navigation pane, click Dashboards.

4. Select Diagnostic Logs from the Logs list.

5. Open the zip file and view the log messages you created.

Add a JavaScript Action

You can add JavaScript functions to the integration.

Creating a JavaScript Action

To create a JavaScript action:

Note:

Note the following restrictions when using the JavaScript action:

• The JavaScript action has a time out threshold of 15 seconds. Any JavaScript function that executes for more than 15 seconds fails with a time out error.

• JavaScript functions are not allowed to make outbound calls to external services. Any outbound calls are blocked and ultimately fail.

• Network, disk access, or thread access functions are not supported.

1. Add a Javascript action to an integration in either of the following ways:

   • On the right side of the canvas, click and drag the Javascript action to the appropriate location.
   • Click at the location where you want to add the Javascript action, then select Javascript.

2. Enter a name and optional description for the JavaScript action when prompted, then click OK.

3. Click the +Function button.

   The Select a Function dialog appears.

4. Click a function, then click the Select in the function’s row.

   The configuration page is displayed. It shows the details of the selected function including the input and output parameters.

5. Click the icon in the Value column to use the Expression Builder to configure the input parameters.

6. Click Validate in the title bar to validate the parameters.

7. Click Close in the title bar to close the page.

Tracking the Status of a Javascript Action During Runtime

During runtime, you can track the status of the JavaScript action in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.

1. In the left navigation pane, click Home > Monitoring > Integrations > Tracking.
2. Click the business identifier value of the integration to track.
3. The integration (including any JavaScript actions) is displayed. Any JavaScript action failures are identified by red arrows.
4. Select View Activity Stream from the menu.
   Details about processing status (including any JavaScript actions) are displayed, including any failures.

See Use Libraries to Manage Integration Functions.

Add Placeholder Notes with a Note Action

You can add placeholder notes similar to sticky notes to an integration. For example, you have not yet defined an invoke connection and want to add a placeholder note in the integration indicating that you plan to define the invoke connection later. Another integration developer reads that note and may add the invoke connection or the note reminds you to add the invoke connection at a later time when you again work on the integration.

The note action is a design-time feature that does not impact runtime. Any changes to upstream or downstream actions in your integration do not impact the note action.

To add a note action:

1. Add a note action to an integration in either of the following ways:
   • On the right side of the canvas, click and drag the Note action to the appropriate location.
   • Click at the location where you want to add the note action, then select Note.
2. Enter a name and description of the action, then click OK.
   The action is added to the integration.
3. Click the Edit icon to add your notes. You can add up to 256 characters.
4. Enter your notes, then click OK.
5. Hover your cursor over the icon to display the note text.

Translate an EDI Document with the B2B Action

You can translate a message to or from the Electronic Data Interchange (EDI) format in an orchestrated integration with the B2B action.

The B2B action translates an incoming EDI document into an Oracle Integration XML message and an outgoing Oracle Integration XML message into an EDI X12 document.

1. Add a B2B action to the integration in either of the following ways:
   • On the right side of the canvas, click and drag the B2B icon to the appropriate location.
   • Click at the location where you want to add the action, then select B2B.
   The Configure B2B Action Wizard is displayed.
2. Enter a name and optional description.
3. Select how you want to use the B2B action, then click Next.
   • B2B Trading Partner Mode: Select to include B2B trading partner profiles and message persistence in your integration.

     Note:

     This option is only available with Oracle Integration Generation 2.
   • Standalone Mode: Select to use the B2B action independently in your integration without a B2B trading partner profile or message persistence.

   
   

   

   
   
4. If you select B2B Trading Partner Mode, follow these wizard steps:
   1. Select the B2B message direction for this B2B action:
      • Inbound: The B2B message is sent from the trading partner to the host trading partner (partner where Oracle Integration is installed).
      • Outbound: The B2B message is sent from the host trading partner (partner where Oracle Integration is installed) to the trading partner.
   2. Select the operation for the B2B action to perform based on the direction.

      If You Selected...	Then Select an Operation...
      Inbound	Fetch Message: Fetches a B2B business message from the persistence store, given a message identifier. Translate: Translates an inbound EDI message to an Oracle Integration message. Mark As Error: Marks a B2B business message with a failed processing status.
      Outbound	Translate: Translates an Oracle Integration message to an outbound EDI message. Mark As Error: Marks a B2B business message with a failed processing status.

   3. If you select either of the following, the Select Data Format page is displayed.
      • Inbound message direction and Fetch Message operation
      • Outbound message direction and Translate operation

      1. Select the document definition for the B2B action to handle, and click Search to refresh the page.
      2. Select the document standard, version, and type.
      3. Click Next.
   4. Review your selections on the Summary page, then click Done.
5. If you select Standalone Mode, follow these wizard steps:
   1. Specify the message translation and document format details.

      Element	Description
      Select the direction in which to translate the message	Inbound EDI message to Oracle Integration message: When an integration receives an EDI document from a business partner, it is considered an inbound document (an EDI document is translated to XML). Oracle Integration message to outbound EDI message: When an integration sends an EDI document to a business partner, it is considered an outbound document (an EDI document is generated from XML).
      Document Standard	The document standard identifies the business protocol to follow when exchanging business documents between partners. EDIFACT X12
      Document Version	Lists the supported versions of the selected document standard. Select the version to use.
      Document Type	Select the document type (for example, purchase order, invoice, shipping notice, or others). The document types available for selection are based on the document version you selected.
      Document Definition	Select the document definition (either Standard or a custom document definition that you created on the B2B Documents page). See Create Custom Document Definitions in Using B2B for Oracle Integration Generation 2.
      EDI Character Encoding	Select the character encoding that the inbound EDI document is expected to use.
      Perform validations on input data	Yes: Validates the structure and data of an inbound EDI message. Enabling message validation has an impact on performance. If errors are found, translation does not succeed. No: Errors are ignored during translation and the message is passed through in its current format.

      
      

      
      Description of the illustration edi_translate_wizard.png

      
      
   2. Click Next.
   3. Specify to optionally upload sample data to test that translation is successful.

      Element	Description
      Select sample data to upload	Click Browse to upload a sample. To test inbound EDI message translation, upload an EDI document. To test outbound EDI message generation, upload an XML document.
      Translate	Click to translate your sample data. Output is displayed in the Output of translation field. Any errors are displayed in the Error in translation field.

   4. Click Next.
   5. Review your selections on the Summary page, then click Done.