Add Actions to an Application Integration

You add actions as part of integration design. Actions perform the activities in an integration.

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 Processing for a Specified Time Period with a Wait Action

• Add Global Fault Handling to Integrations

• Catch Faults with a Re-throw Fault Action

• Throw Faults with a Throw New Fault Action

• Process Files in Schedule Integrations with a Stage File Action

• Receive Requests for Multiple Resources in a Single REST Adapter Trigger with a Pick Action

• Log Messages with a Logger Action

• Process Tasks in Parallel with a Parallel Action
• Invoke Oracle Cloud Infrastructure Functions Directly from an Integration with an OCI Function Action
• Publish Events in an Integration with a Publish Event Action

• Add JavaScript Functions to an Integration with a JavaScript Action

• Invoke Oracle Cloud Infrastructure Object Storage from an Integration with an OCI Object Storage Action

• Add Placeholder Notes with a Note Action

• Translate an EDI Document with the B2B Action
• Interact with Files in File Server

Loop over Repeating Elements with a For-Each Action

The for-each action enables you to loop over a repeating element and process 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 download 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 processed for the first time. The for-each action is not allowed to process 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 Actions 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 Configure For Each panel opens. This includes a Sources tree of elements.

2. Click Edit under Configure For Each to enter a name and optional description for the for-each action.

3. Expand the Sources tree to select an element.

4. 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 three-box icon to the left of the element name.
     
     

   • 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.

   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.

   
   

   

   
   

   Note:

   If you drag a for-each action into a schedule 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 Save.

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

7. Click + inside the for-each action to add additional actions. These actions define what happens during each iteration of the loop. For this example, scope and switch actions are defined within the for-each action.

   
   
   Description of the illustration oic3_for_each2.png
   

Using Global Variables in For-Each Loops

When global variables are used in for-each loops (for example, for logging purposes), they can lead to the following runtime exception when bad or invalid data is associated with the variable:

FORG0001: invalid value for cast/constructor, Cikey=13695578,
FlowId=10025204, Current Activity Key=13695578-BpAss43-BpSeq8.240-4, Current
Activity Label=assignment_ics_api_internal_variable23,

As a recommendation:

• Limit the use of global variables in for-each loops.

• Global variable handling requires database access, which results in an added performance overhead.

• Local variables can be used for logic specific to a local scope.

Tracking the Status of a For-Each Action During Runtime

You can track the status of the for-each action on the Instances page through the tracking diagram and activity stream for an activated integration.

1. In the navigation pane, click Observability, then Instances.

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. The activity stream is displayed on the right side.

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 3
• Process Large Data Sets Asynchronously with Different Bulk Import Operations in Using the Marketo Adapter with Oracle Integration 3
• Subscribe to Atom Feeds in a Schedule Integration in Using the Oracle HCM Cloud Adapter with Oracle Integration 3
• Invoke an Endpoint Dynamically in Using the Oracle ERP Cloud Adapter with Oracle Integration 3
• Create an Integration to Import and Process Bulk Files in Using the FTP Adapter with Oracle Integration 3

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.

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

   • On the right side of the canvas, click Actions 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:

   
   

   

   
   

   • Route 1 (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 Actions in the switch action, then Add.

2. From the Route 1 branch icon, double-click the branch or click Actions , then Edit.

   The Configure Route panel opens. This includes a Sources tree of elements.

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

3. Click Edit under Configure Route to enter a name for the Route 1 branch.

4. Define a routing expression. For this example:
   • filetype is dragged to the upper Value field
   • = is selected as the operator
   • 'json' is manually entered in the lower Value field. You can also drag a value from the Sources tree or select a value from the drop-down list.
   
   
   
   
   

   You can add functions to your expression under the Functions tab. 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.

5. Click Switch to Developer Mode to view the complete path name.

   
   
   

6. Click Add condition to add more conditions or Add group to add group conditions, when needed.
7. Click Save.

   For this example, the following expression is defined:

   
   
   

8. Drag other actions and invokes into the branches of the switch action, when required by your integration. For this example, two switch action branches are defined.

   
   
   

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 3
• Design an Asynchronous Search Operation with Pagination in Using the Oracle NetSuite Adapter with Oracle Integration 3
• Use the Extract API in a Schedule Integration in Using the SAP Concur Adapter with Oracle Integration 3
• Use the Pagination Concept in an Integration in Using the Jira Adapter with Oracle Integration 3

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 processed. All fault handling must be done in the default fault handler.

• Creating a Scope Action
• Add Nested Scopes to a Scope Action
• Tracking the Status of a Scope Action During Runtime
• Rename a Scope

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 Actions 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. Click Edit under Edit Scope to enter a name and optional description for the scope action.

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

   
   
   

   The scope includes a default fault handler that is accessible by clicking the scope action and selecting Actions , then Fault Handlers, then Default Handler.

   
   
   

4. Click + to define actions on the default fault handler.
5. To return to the scope action, click the fault handler, and select Actions , then Show Scope Block 'scope_name'.
   When you add invokes to a scope, the named faults associated with the invokes are added to the default fault handler in the scope. For example:

   1. Add and configure an invoke connection inside the scope action (for example, a REST Adapter).
   2. Click the scope and select Actions , then Fault Handlers.

      In addition to the Default Handler, an invoke fault handler has been added.

      
      
      

   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.

6. 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.

7. Collapse the scope action by double-clicking it. You can expand it again by double-clicking it, selecting Actions, then Expand, or clicking >.

Note:

For application 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.

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.

   
   
   

2. Add actions and fault handlers to the nested scope, when necessary.

Track 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 navigation pane, click Observability, then Instances.

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

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

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

   • Scope processing fails and is displayed in red, but the fault handler succeeds in handling the fault and is displayed in green. Processing continues after the scope. Because the fault handler was processed, 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.

See Track the Status of Integration Instances for additional details.

Rename 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 Actions , then Edit.
4. Change the name and click Save.

Assign Values to Scalar Variables in an Assign Action

You can assign values to scalar variables in integrations with an assign action.

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 side of the canvas, click Actions and drag the Assign action to the appropriate location.
   • Click at the location where you want to add the assign action, then select Assign.

   The Configure Assign panel opens.

2. Click Edit under Configure Assign to enter a name and optional description for the assign action.

3. Click the + sign, then select a data type:

   • String: Create a string data type.
   • Fault: Catch and aggregate faults in parallel processing actions in schedule integrations. This operation is only supported in schedule integrations.
4. If you select String:
   1. Enter a string variable name or select an existing variable from the list.

      
      
      

      The Operations field defaults to an equal sign (=) and cannot be changed.

   2. Enter a value between the single quotes.

      
      
      

   3. Add more string variables, when needed.

      
      
      

5. If you select Fault:
   1. Enter a fault variable name or select an existing fault from the list.
   2. Select an operation from the Operation list.
      • Append: Adds a new fault to the end of the fault list.
      • Clear: Removes all entries in the fault list.
   3. If you selected Append, click Edit to select a fault from the mapper in the Value column. This option is not available with the Clear operation.

      
      
      

6. Add more fault variables, as needed.

7. Click Save.

Variable assignments can be of great complexity. You can use assignments in switch actions and maps. For example, the upper branch of a switch action is taken (if $FetchContactAssign = "failed"), which processes a contactCreateProcessing scope. Otherwise, a contactUpdateSkip scope is processed.

You can also configure the primary tracking variable and both custom field tracking variables (update and access values). You can map tracking variables to output variables or create complex expressions for an assign or switch 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 3
• Design a Basic Asynchronous CRUD Operation in Using the Oracle NetSuite Adapter with Oracle Integration 3
• Use the Extract API in a Schedule Integration in Using the SAP Concur Adapter with Oracle Integration 3
• Use the Pagination Concept in an Integration in Using the Jira Adapter with Oracle Integration 3

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 application integrations.

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 side of the canvas, click Actions and drag the While action to the appropriate location.
   • Click at the location where you want to add the while action, then select While.

   The Configure While panel opens. This includes a Sources tree of elements.

2. Click Edit under Configure While to enter a name and optional description for the while action.

3. Manually enter, select from the drop-down list, or drag an element from the Sources tree to the Value field. You can also add functions.

4. Select an operator.
5. Enter a value in the Value field.

   
   
   

6. Click Save.

   For this example, while the counter is less than or equal to 10000, the integration loops over the condition. When the condition is not met, the looping ends.

   
   
   Description of the illustration oic3_while.png
   

7. Drag invoke connections or other actions for configuration to the + sign that is displayed inside the while action. These invoke connections and actions are processed as long as the condition set in the while action is met.

   
   
   

8. If you want to edit the name or expression, double-click the While icon or select Actions , then Edit.

   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.

Track the Status of a While Action During Runtime

During runtime, you can track the status of the while action in the Instances page through the tracking diagram and activity stream for an activated integration.

1. In the navigation pane, click Observability, then Instances.

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.

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 3
• Retrieve Issue Details Using the Jira Query Language (JQL) in Using the Jira Adapter with Oracle Integration 3
• Use Pagination in an Integration in Using the Shopify Adapter with Oracle Integration 3

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 processing 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 side of the canvas, click Actions 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. Click Edit under Configure Notification to enter a name and optional description for the notification action.
3. Click the To field.
   This opens the Sources tree for defining an expression and a second To field for editing immediately after the first field.
4. Manually enter an email address, select from the drop-down list, or drag an element from the Sources tree to the To field:
   
   

   

   
   
5. Click the From field.
   This opens a second From field for editing immediately after the first field.

   
   
   

6. Manually enter an email address, select from the drop-down list, or drag an element from the Sources tree. For this example, an email element is dragged from the Sources tree.
   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 System Status Reports with Notification Emails.

7. Click the Subject field.
   This opens a second Subject field for editing immediately after the first field.
8. Manually enter a subject in plain text, select from the drop-down list, or build an expression from the Source or Functions tree. To drag a function, ensure that you first select Switch to Developer View .

   For this example, a concat function is selected for use from the Functions section.

   concat ( 'Hello', name )

9. Click the Body field.
   This opens a second Body field for editing immediately after the first field.
10. Enter a message using plain text and 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 after this field. After creating parameters, enter them inside { } brackets.

    <html>
    <body>
    <p>Hello <strong><span style="color: #2925BF;">{name},</span></strong></p>
    <p><span style="color: #298022;"><strong>Welcome to Oracle Integration!</strong></span></p>
    </body>
    </html>

11. Click + to add parameters.
12. Enter a parameter name and description or build an expression.
13. Click + to add attachments.
14. Select the attachments to add.
15. In the Attachments section, click + to open a page to select an attachment file.
    You can edit or delete attachments once added. Examples of attachments may include file reference attachments 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
16. When complete, the Configure Notification panel looks as follows for this example:
    
    

    

    
    
17. Click Save.

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 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 oic3_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 a Configure Stitch panel 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.

1. Add a stitch action to an integration in either of the following ways:
   • On the side of the canvas, click Actions and drag the Data Stitch action to the appropriate location.
   • Click at the location where you want to add the data stitch action, then select Data Stitch.
   The Configure Stitch panel opens.

   
   
   

2. Click Edit under Configure Stitch to enter a name and optional description for the stitch action.

3. Click the Variable field and manually enter a variable name, select a variable from the drop-down list, or click Switch to Developer View to open the Sources tree for dragging a variable name.

   
   
   

   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.

4. From the Operation list, select the operation to perform on the variable:
   • Append
   • Assign
   • Remove
5. Click the Value field and specify a value in any of the following ways:

   • Entering manually.
   • Selecting from the list.
   • Clicking Switch to Developer View to open the Sources tree.
   If you selected the Remove operation, the Value field is not displayed.
6. Click + if you want to create additional complex assignment statements.
7. When complete, click Save to save your statements and close the Configure Stitch panel.

   For this example, the following statement was created.

   
   
   

   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 processing.

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

The wait action enables you to delay the processing of an integration for a specified period of time. Use this action in schedule integrations, asynchronous integrations, synchronous integrations, and fire-and-forget integrations. A typical use for this action is to invoke a specific operation at a certain time. You can specify literal values or build XPath expressions that you can configure with property values during runtime.

Create a Wait Action

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

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

   The Configure wait panel opens.

2. Click Edit under Configure wait to enter a name and optional description for the wait action.

   Configure the time to wait before processing the integration in either of two ways:

3. If you want to use literal (hard coded) values:

   1. Enter the number of seconds to wait before processing the integration. Literal values can only be in seconds, with no upper limit. The wait time cannot exceed the total running time of the integration.

      
      
      
      
      
4. If you want to enter an XPath expression:

   This option enables you to update a wait action parameter with an integration property value after the integration is activated. This update does not require a re-activation of the integration.

   1. Drag an element from the Input sources section.

      
      
      

   2. Complete design of your integration and exit the integration canvas.
   3. Activate the integration.
   4. Hover your cursor over the integration, and select Actions , then select Update property values.
   5. Enter a value to use at runtime in the New value field (for this example, 9 is entered). This value overrides the value provided in the Default value field.

      
      
      

   6. Run the integration and view the activity stream.
   7. Click View for the action in front of the wait action (for this example, a logger action) and note that the integration property value is 9 and the wait action was initiated at 02:36:32 and the next action (for this example, a second logger action) was initiated at 02:36:41 (nine seconds later).

      
      
      

Track the Status of a Wait Action During Runtime

During runtime, you can track the status of the wait action on the Tracking page through the tracking diagram and activity stream for an activated integration.

1. In the navigation pane, click Observability, then Instances.

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

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

Related Documentation

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

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

Add Global Fault Handling to Integrations

You can add global fault handling to 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)).

Add a Global Fault

1. Design an 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 integration canvas, click View Global Fault Handler .

   The Global Fault Handler page is displayed. The initial trigger in your integration is automatically connected to an initial Re-throw Fault action. 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.

   
   
   

3. Click Actions to add actions to design specific fault handling logic in the integration. For example, you can add Switch, Stop, or additional actions, when needed.

4. To build an expression to capture fault handling information, select the action, then click , then Edit .

   

   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)

   • getFaultName (returns the fault name)

   • getFaultedActionName (returns the fault of the action)

   • getFlowId (returns the flow ID of the integration)

   • lookupValue

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

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

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

6. 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).

7. Click Save.

8. Click View Main Integration to return to edit mode in the integration canvas.

9. Complete the design of the integration.

10. Activate the integration.

Track the Status of a Global Fault During Runtime

During runtime, you can track the status of global faults on the 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 navigation pane, click Observability, then Instances.

2. On the Instances page, 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.

   If the global fault handler successfully handled the error, the integration is displayed as Succeeded on the 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.

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

2. Double-click the scope.
3. Select Actions , then Fault Handlers, and then Default Handler.

   The scope action is now in fault design mode.

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

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

     This creates a re-throw fault action in the fault handling section of the scope action.

     
     
     

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

5. Double-click the scope action to return to design mode.

   The Re-throw Fault action is hidden.

6. Design your scope action.

7. To return to fault mode, double-click the scope.
8. Select Actions , then Fault Handlers, and then Default Handler.

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 side of the canvas, click Actions 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. Click Edit under Throw New Fault to enter a name and optional description for the throw new fault action.
   The Throw New Fault panel is displayed.

   
   
   

3. Click a field to open the Sources panel and specify values in any of the following ways:
   • Enter manually.
   • Select from the list.
   • Click Switch to Developer View to drag a value from the Sources panel.

     
     
     

4. Complete the fields:

   Element	Description
   Code	Create a code value. This is a mandatory field.
   Reason	Define a reason for the error.
   Details	Define additional error details.
   Skip Condition	Define a condition to prevent the fault from being thrown.

   
   

   

   
   
5. Click Save

   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 processing 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 processing 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 Schedule Integrations with a Stage File Action

You can use the stage file action to process files or file references in schedule 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, encrypt, decrypt, 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 after the FTP Adapter to iterate over repeated elements.

• To read each file from the input directory, configure a stage file action after 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.

Create Local Files

Note the following details about local file behavior:

• Local Oracle Integration folders 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 in the Stage File panel.

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

When configuring the stage file action in the Stage File panel, 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.

Open the Stage File Panel

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 side of the canvas, click Actions 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 >.

   The Configure Operation page is displayed.

• Configure Stage File Operations
• Define the Schema File
• Define the Schema Format
• Review the Stage File Action in the Integration Canvas

Configure Stage File Operations

The Configure Operation page enables you to define the file operations to perform. You can select to read an entire file, read files in chunked sizes, unzip a file, write a file, zip a file, or list 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 also select to encrypt and decrypt files with a Pretty Good Privacy (PGP) authentication key that you configured on the Upload Certificate page. See Upload a Certificate to Connect with External Services.

1. From the drop-down 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

   • Zip File

   • Unzip File

   • Encrypt File

   • Decrypt File

   • List File

   Read Entire File

   Table 6-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 field and specify a file reference in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the File Name (Appears if you select No for the Configure File Reference.)	Click the field and specify a file name (for example, /compress:schedule/compress:start Time) in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree. 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 field and specify a directory from which to read files (for example, /compress:schedule/compress:start Time) in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   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 6-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 field and specify the file reference in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the File Name (Appears if you select No for the Configure File Reference.)	Click the field and specify a file name in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree. 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 field and specify a directory from which to read files in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Segment Size	Enter the segment size. The segment size defaults to 200 records per segment, but can be changed. The minimum value is 200 records and the maximum value is 2000 records. 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.
   Sequential Processing	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.
   • Multiple stage file action write operations appending data to the same stage file within a loop results in the data being overwritten. This results in data loss.

   Table 6-3 - Write File

   Property	Description
   Specify the File Name	Click the field and specify a file name in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Output Directory	Click the field and specify an output directory in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   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 6-4 - Zip Files

   Property	Description
   Specify the File Name	Click the field and specify a file name in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Directory to zip	Click the field and specify a directory to zip up in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Output Directory	Click the field and specify an output directory in which for the ZIP file in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.

   Unzip File

   Table 6-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 field and specify a file reference in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Zip File Name (Appears if you select No for the Configure File Reference.)	Click the field and specify a ZIP file name to read in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Zip File Directory	Click the field and specify a directory in which to unzip the file in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Directory to Unzip	Click the field and specify the directory to unzip in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.

   Encrypt File

   Table 6-6 - Encrypt File

   Property	Description
   Specify the File Reference	Click the field and specify a file reference in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the File Name	Click the field and specify a file name in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Output Directory	Click the field and specify an output directory in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   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 6-7 - Decrypt File

   Property	Description
   Specify the File Reference	Click the field and specify a file reference in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the File Name	Click the field and specify a file name in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   Specify the Output Directory	Click the field and specify an output directory in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   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 6-8 - List File

   Property	Description
   Specify the Directory to List Files from	Click the field and specify a directory from which to list files in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.
   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 > .

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

Define 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?	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 panel, 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. This option only appears if you selected the Read Entire File or Write File operation.

2. When complete, click >.

Define 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 based on the schema option you selected:

   Note:

   Oracle does not certify schemas that were manually updated with undocumented annotations. Use discretion if specifying these schemas. For example, runtime errors can occur if you use Oracle SOA Suite schemas that are annotated with constructs that are undocumented and not certified in Oracle Integration 3.

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

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

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

   • Sample JSON document (Table 6-12)

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

   Element	Description
   Select the Delimited Data File	Drag and drop 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.
   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 is 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 6-10 - XML Schema (XSD) Document

   Element	Description
   Select a New File	Drag and drop 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 field and specify the repeating node in the schema to support payload chunking in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.

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

   Element	Description
   Select a New File	Drag and drop 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 field and specify the repeating node in the schema to support payload chunking in any of the following ways: Entering manually. Selecting from the list. Clicking Switch to Developer View to open the Sources tree.

   Table 6-12 - Sample JSON document

   Element	Description
   Select a New File	Drag and drop 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 >.

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

Review 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.

  
  
  

  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.

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 3
• Process RaaS Reports that Support the Delivery of Data in CSV Format in Using the Workday Adapter with Oracle Integration 3
• Produce Messages to an Apache Kafka Topic in Using the Apache Kafka Adapter with Oracle Integration 3
• Use Bulk Response Operations in an Integration in Using the Salesforce Adapter with Oracle Integration 3

Receive Requests for Multiple Resources in a Single REST Adapter Trigger with a Pick Action

You can expose multiple entry points to a single integration that uses the REST Adapter as the trigger connection. Each entry point can be configured with a different resource URI and HTTP action/verb, when necessary. This feature eliminates the need to create multiple integrations (each with a separate resource URI and verb) to perform different operations.

This feature is useful in the following scenarios:

• Supports multiple resource URIs and actions/verbs in a specific integration through the REST Adapter.
• Supports multiple integration patterns (for example, synchronous and asynchronous). The combination of a resource and a verb is called an operation. Each operation can be configured as a synchronous or an asynchronous one-way service. Asynchronous services accept the request and return immediately with an HTTP 202 status.

Note:

This feature is only available when creating an application integration.

1. Drag a REST Adapter into the canvas as a trigger connection of an application integration.
   This invokes the Adapter Endpoint Configuration Wizard.
2. On the Basic Info page, specify the following:
   1. Enter a name and optional description.
   2. Select the Select to configure multiple resources or verbs (maximum 11) check box.
3. On the Resource Configuration page, specify the operation name, the endpoint relative resource URI, and the action/verb to perform, then click Next.
   
   

   
   Description of the illustration oic3_rest_ops1.png

   
   
4. On the Operations page, click Add another operation to add another resource URI and action/verb, then click Next.

   You are returned to the Resource Configuration page.

5. On the Resource Configuration page, specify a different operation name, endpoint relative resource URI, and action/verb to perform, then click Next.
6. Continue this process to add as many operations as necessary.
7. On the Operations page, note that all operations are displayed. Each operation represents a different branch in a single integration.
   
   

   
   Description of the illustration oic3_rest_ops.png

   
   
8. On the Summary page, review your selections, and click Done.
   For this example, there are six branches (modifyEmployee, updateEmployee, getEmployee, getEmployeeLocation, deleteEmployee, and addEmployee).
9. Place your cursor over each branch to show details about the operation/resource name, action/verb, and resource URI.
10. Further configure your integration by dragging appropriate actions after each operation name. You cannot add actions between the REST Adapter icon and the operation name.
    
    

    

    
    
11. Select Actions , then tracking for the pick action operation name for which to define business identifier tracking variables.
    
    

    

    
    
12. Set the tracking variables for each pick action operation branch. Tracking variables are populated per the operation. You must set primary tracking variable for all operations to activate the integration. If any branches are not configured with tracking variables, a red error icon is displayed on the node. Place your cursor over the error icon to show a detailed error message.
13. Activate and invoke the integration to take the appropriate branch.
    Once activated, the adapter metadata page displays information corresponding to each of the configured resources and verbs.

    The swagger displays all the configured resources and the verbs for each such resource. Similar to swagger from a single resource REST trigger endpoint, you can use this swagger in another invoke connection to automatically discover and browse the resource implemented.

Note:

You can edit the action in the integration to remove or add operation branches. This enables you to convert to and from a standard trigger-based integration with a single operation to an integration with multiple operation branches.

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.

Create a Logger Action

To create a logger action:

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

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

   The Configure Logger panel opens.

2. Click Edit under Configure Logger to enter a name and optional description for the log action.

3. Select whether to always log this message or log it only when tracing is set to audit. 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. Drag elements from the Sources tree to create a message.

   
   
   

5. When complete, click Save. For this example, a log action is included in the integration.

   
   
   

Track 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 navigation pane, click Observability, then Instances.
2. Click the integration instance.
3. Scroll through the activity stream.

4. Select Download to download the logs.

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

Process Tasks in Parallel with a Parallel Action

You can use a parallel action to process tasks in parallel to improve integration performance and response times. A parallel action allows the path of an integration to be split into multiple branches. Each branch is processed in parallel due to their independence from each other. Messages are sent to each service endpoint in parallel.

When all tasks are completed, all branches are automatically synchronized and merged at their termination points in the parallel action and the main path of the integration is resumed. Any variables created inside the parallel branches (for example, invoke responses) are available for use in the main path.

• Use Cases
• Guidelines and Restrictions
• Design Time Behavior
• Runtime Behavior

Want to see a video demo of the parallel action?

Use Cases

A parallel action is useful for use cases such as the following:

• An order processing integration contains individual tasks for checking inventory, customer credit, and legal constraints. These tasks are processed in parallel to ensure a better response time.
• An integration obtains the lowest price for an item from suppliers. The integration checks three suppliers for prices and takes the best offer. The three price checks are done in parallel because they are independent of each other. Once the three suppliers have responded, the branches are terminated. The three prices are compared to identify the lowest. The integration then continues its main path by placing the order with that supplier.
• An integration processes an incoming order from both an inventory and legal perspective (for example, can the product be shipped to the customer's country). Both checks are done in parallel.

Guidelines and Restrictions

• You can create a maximum of five branches to a parallel action. If you attempt to create a sixth branch by selecting Actions , and then Add on the parallel action, the selection is disabled.
• There is no limit to the number of parallel actions you can include in an integration.
• Synchronous and asynchronous integrations are supported.
• You cannot add a parallel action inside another parallel action.
• Parallel actions can be used in application integrations and schedule integrations.
• Only map, scope, switch, logger, JavaScript, B2B, and notification actions and invoke connections are supported in a parallel action branch.
• You can add parallel actions to the branches of a pick action.
• You can add parallel actions inside scope and switch actions.
• Nesting of parallel actions in for-each actions, while actions, or stage file actions with chunking is not supported.
• No independent branch-specific fault handling is supported. You can catch faults at the integration level with a global fault handler.
• Synchronization of global variables is not supported.
• Branch-specific timeouts are not supported.

Design Time Behavior

The following example provides a high-level overview of how to design a specific parallel action. This is just one example of parallel action use.

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

   A parallel action with two branches is created.

   
   
   

2. Select Actions to perform the following tasks.
   • Edit: Change the name of the parallel action.
   • Add: Add more branches. You can add a maximum of five branches.
   • Delete: Delete the parallel action.
   • Collapse/Expand: Collapse or expand the parallel action.
   • Cut: Cut the parallel action and paste it elsewhere in the integration. You can also cut and paste existing maps/invokes into the new parallel branches to make them process in parallel. You cannot cut an individual branch of a parallel action and paste it into another parallel action.

     See Cut and Paste Elements in the Integration Canvas.

   For this example, a third branch is added.

   
   
   

   For this example, the three branches are designed to obtain loan offers from three service endpoints and then select the best one.

3. Add and configure three REST Adapter connections to invoke the following service endpoints. At runtime, all three loan service endpoints are invoked in parallel to identify their specific loan offers.
   • American Loan
   • United Loan
   • Star Loan
4. In the mapper for each invoke action, map your SSN to the loan application for that service endpoint.

   
   
   

   At the bottom, the three branches are synchronized at their termination points and the parallel action rejoins the main branch of the integration. The main integration does not continue until all branches are complete

5. Add a switch action to define the routing rules to check for the best offer returned from the loan service endpoints.

   
   
   

6. Define the message in a log action for each switch branch.

   
   
   

   
   
   

   When complete, the integration looks as follows.

   

   The integration is now ready to be activated and invoked.

Runtime Behavior

You can view the status of parallel branches in the activity stream during runtime. For example, assume your integration is designed with the following:

• One parallel action with two branches
• A second parallel action with three branches

1. Invoke an instance of your integration and go to the Instances page.

   During runtime, the activity stream shows both parallel actions and their number of branches. For this example, both parallel actions processed successfully.

   
   
   

2. Expand each branch to view more specific details.

Invoke Oracle Cloud Infrastructure Functions Directly from an Integration with an OCI Function Action

Oracle Integration provides native support for invoking Oracle Cloud Infrastructure functions. This support enables you to invoke Oracle Cloud Infrastructure functions with an OCI Function action in an integration.

Oracle Cloud Infrastructure functions are part of a fully managed, multi-tenant, highly scalable, on-demand, Functions-as-a-Service platform. Use Oracle Cloud Infrastructure functions to focus on writing code to meet business needs. See Overview of Functions and Functions QuickStart Guides.

Note:

Ensure that your cloud tenancy uses identity domains. The OCI Function action in the integration canvas does not work in cloud tenancies that are not enabled for identity domains.

• Capabilities
• Prerequisites
• Invoke Oracle Cloud Infrastructure Functions

Want to see a video demo of the OCI Function action?

Capabilities

Oracle Cloud Infrastructure functions provide serverless execution of functions within Oracle Integration to process complex logic not easily performed in Oracle Integration, such as the following:

• Creating a digital signature based on a key against a specific payload.
• Supporting a custom ZIP format such as GZIP or TAR.
• Taking and parsing a PDF file for data fields that can then participate in an integration.

Oracle Integration supports whatever functions you create using Oracle Cloud Infrastructure functions. Oracle Cloud Infrastructure also provides a catalog of prebuilt functions. See Creating Functions Using Pre-Built Functions.

Prerequisites

You must perform the following prerequisites from the Oracle Cloud Infrastructure Console before you can invoke functions from an integration. Not performing these prerequisites results in the following error:

An authentication issue was encountered when invoking Function. Please 
check if the prerequisites for calling OCI services have been properly setup for 
this service instance. OCI service integration requires dynamic groups and policies 
granting access to be created in OCI Console. Please consult the documentation for 
more information.

1. Ensure that your cloud tenancy uses identity domains. Invoking Oracle Cloud Infrastructure functions from an integration does not work in cloud tenancies that are not enabled for identity domains. If you are unsure, ask your administrator for details. Your cloud tenancy does not use identity domains if you observe either of the following:
   • In the upper right corner, you select your Profiles icon and don't see an entry for identity domain.

     
     
     

   • From the menu, you select Identity & Security and don't see Domains under the Identity section.

     
     
     

2. Set up your environment to invoke Oracle Cloud Infrastructure functions from an integration. See Functions QuickStart on Cloud Shell. This section describes how to set up the following:
   • Set up your tenancy:
     • Create groups and users (if not already done so).
     • Create a compartment in which to create functions. You specify this compartment when configuring the OCI Function action in the integration canvas.
     • Create a virtual cloud network (VCN) and subnets. For example:

       
       
       

     • Create a policy for groups and services. This policy enables you to create functions. For example:

       
       
       

   • Create an application in which to create the functions to invoke. You specify this application when configuring the OCI Function action in the integration canvas. For example:

     
     
     

   • Set up your Cloud Shell development environment.
   • Create, deploy, and invoke your function. For example:

     Note:

     You must create your own functions in your tenancy. Oracle Cloud Infrastructure doesn't deploy or create any functions for you by default. Oracle Cloud Infrastructure does provide prebuilt functions that you can deploy to your own instance.

     
     
     

3. Create a dynamic group.
   1. Obtain the client ID of the OAuth application for the Oracle Integration instance.
   2. In the upper right corner, select Profile, then click the identity domain.

      
      
      

   3. In the left navigation pane, click Oracle Cloud Services.

      
      
      

      The Oracle Cloud Services page for your domain appears.

   4. In the Name column, click your service instance.
   5. Scroll down to the General Information section and copy the client ID value to use to create your dynamic group.
4. Scroll to the breadcrumbs at the top and click Default domain.

   
   
   

5. In the left navigation pane, click Dynamic groups.
6. Click Create Dynamic Group.
7. Enter the following details:
   1. In the Name and Description fields, enter values. These fields are required.
   2. In the Matching Rules section, enter the required rule. The resource ID you specify must match the client ID of the OAuth application of your Oracle Integration instance. Ensure that you enclose the value in single quotes. For example:

      resource.id = 'client_ID'

      
      
      

8. Assign a policy to the dynamic group to enable you to invoke Oracle Cloud Infrastructure functions from an integration.
9. Scroll to the breadcrumbs at the top and click Identity.

   
   
   

10. In the left navigation pane, click Policies.
11. Click Create Policy.
12. Select the compartment in which to create the policy.
13. Enter the following details:
    1. In the Name and Description fields, enter values. These fields are required.
    2. In the Policy Builder section, build the required policy for the dynamic group. The following example allows the dynamic group to use the entire functions family, but you can set more granular policies, as needed. See Controlling Access to Invoke and Manage Functions and Policy Statements to Give OCI Functions Users Access to Function-Related Resources.

       Allow dynamic-group group_name to use functions-family in compartment compartment_name

       Where:

       • group_name: Is the dynamic group name you created.
       • compartment_name: Is the compartment where the functions to invoke are hosted.

       This enables the Oracle Integration instance associated with the dynamic group to invoke Oracle Cloud Infrastructure functions with the OCI Function action in an integration.

Invoke Oracle Cloud Infrastructure Functions

This section provides an overview of how to configure an OCI Function action in the integration canvas to invoke the Oracle Cloud Infrastructure functions available in your application.

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

   Note:

   If your cloud tenancy is not using identity domains, an error message appears and the page is blank.

   The OCI Functions wizard appears.

2. On the Basic Info page, enter the following information to identify the function to invoke, then click >. When you enter details in a field, the page refreshes to show more fields.

   Element	Description
   Region	Select the region where the functions are deployed.
   Compartment	Select the compartment where the functions to invoke are hosted.
   Application	Select the application. Oracle Cloud Infrastructure functions are organized in sets called applications. An application can contain multiple functions.
   Function	Select the Oracle Cloud Infrastructure function to invoke. The functions you are entitled to invoke by your application are displayed for selection.

   
   
   

3. On the Request page, select the payload type and specify the content, then click >.
   • JSON Sample: Drag and drop or select a file, or manually enter the payload.
   • XML Schema: Drag and drop or select a file.
   • XML Sample (Single or No NameSpace): Drag and drop or select a file.
   • Binary: No additional selections are required.
4. On the Response page, select the response payload type and specify the content, then click >. The available response payload types are the same as the request payload types.
5. Review your selections on the Summary page. For this example, the hello-python-json function is invoked. The request and response media is in JSON format.

   
   
   

6. Click Done.

Publish Events in an Integration with a Publish Event Action

You can publish an event in an integration. Subscription integrations can then subscribe to this event.

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

   The Choose event panel opens.

2. Specify an event in either of two ways:
   1. Select the event, then click Choose. If you are unsure of the event contents, click View details .
   2. Click Define new event to create a new event. See Create Events to Publish and Subscribe to in Integrations.
3. Review your selections, then click Finish.

See Publish Events in an Integration.

Add JavaScript Functions to an Integration with a JavaScript Action

You can add JavaScript functions to the integration.

Create a JavaScript Action

Note:

Note the following restrictions when using the JavaScript action:

• The JavaScript action has a timeout threshold of 15 seconds. Any JavaScript function that processes for more than 15 seconds fails with a timeout 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 side of the canvas, click Actions 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. Click Edit under Configure Javascript to enter a name and optional description for the JavaScript action.

3. Click the Function button.

   The Functions List appears.

4. Select a function.

   The function and Sources tree are displayed. Function details are shown, including the input and output parameters.

   
   
   

5. Click the first input parameter to open a Value field.

   
   
   

6. Drag a value from the Sources tree.

   
   
   

7. Perform the same steps to add a value for the second input parameter.

8. Click Save.

Track the Status of a Javascript Action During Runtime

During runtime, you can track the status of the JavaScript action on the 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 navigation pane, click Observability, then Instances.
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.
   Details about processing status (including any JavaScript actions) are displayed, including any failures.

See Use Libraries to Manage Integration Functions.

Invoke Oracle Cloud Infrastructure Object Storage from an Integration with an OCI Object Storage Action

You can natively invoke Oracle Cloud Infrastructure Object Storage from an integration without the need to configure an explicit REST Adapter connection.

• Oracle Cloud Infrastructure Object Storage Concepts
• Prerequisites
• Invoke Oracle Cloud Infrastructure Object Storage from an Integration

Oracle Cloud Infrastructure Object Storage Concepts

Oracle Cloud Infrastructure Object Storage is an internet-scale, high-performance storage platform that offers reliable and cost-efficient data durability. Oracle Cloud Infrastructure Object Storage enables you to securely store any type of data in its native format. An unlimited amount of unstructured data of any content type is supported, including analytic data and rich content such as images and videos. See Object Storage and Overview of Object Storage.

Prerequisites

To natively invoke Oracle Cloud Infrastructure Object Storage, you must satisfy the following Resource Principal Session Token (RPST) prerequisites in the Oracle Cloud Infrastructure Console.

• Create a dynamic group
• Create a policy to grant access to Oracle Cloud Infrastructure Object Storage.

• Ensure that your cloud tenancy uses identity domains. Your cloud tenancy does not use identity domains if you observe either of the following:
  • In the upper right corner, you select your Profiles icon and don't see an entry for identity domain.

    
    
    

  • From the menu, you select Identity & Security and don't see Domains under the Identity section.

    
    
    

• Create the required dynamic group and assign a policy to that group to allow your Oracle Integration instance to access Oracle Cloud Infrastructure Object Storage. The policy defines the permissions for the dynamic group and determines which operations the dynamic group can perform on Oracle Cloud Infrastructure Object Storage and other services such as Oracle Cloud Infrastructure Functions, Oracle Cloud Infrastructure Vision, and more
  1. Log in to the Oracle Cloud Infrastructure Console.
  2. Obtain the client ID of the OAuth application for the Oracle Integration instance.
     1. In the upper right corner, select Profile, then click the identity domain.

        
        
        

     2. In the left navigation pane, click Oracle Cloud Services.

        
        
        

        The Oracle Cloud Services page for your domain appears.

     3. In the Name column, click your service instance.
     4. Scroll down to the General Information section and copy the client ID value to use to create your dynamic group.
  3. Scroll to the breadcrumbs at the top and click Default domain.

     
     
     

  4. In the left navigation pane, click Dynamic groups.
  5. Click Create Dynamic Group.
  6. Enter the following details:
     1. In the Name and Description fields, enter values. These fields are required.
     2. In the Matching Rules section, enter the required rule. The resource ID you specify must match the client ID of the OAuth application of your Oracle Integration instance. Ensure that you enclose the value in single quotes. For example:

        resource.id = 'client_ID'

        
        
        

  7. Scroll to the breadcrumbs at the top and click Identity.

     
     
     

  8. In the left navigation pane, click Policies.
  9. Click Create Policy.
  10. Select the compartment in which to create the policy.
  11. Enter the following details:
      1. In the Name and Description fields, enter values. These fields are required.
      2. In the Policy Builder section, build the required policy for the dynamic group. Examples of the minimum policy required are as follows:

         allow dynamic-group dynamic_group to manage object-family in compartment compartment_name 
         

         allow dynamic-group dynamic_group to inspect compartments in compartment compartment_name
         

         Where:

         • dynamic_group: Is the dynamic group name you specified in Step 5.
         • compartment_name: Is the compartment in which your Oracle Integration instance is located.

         This enables the Oracle Integration instance associated with the dynamic group to call Oracle Cloud Infrastructure Object Storage in this particular compartment. The RPST token is only valid for resources to which the dynamic group has been granted access using this policy.

         Details about more granular permissions for object storage are provided. See Securing Object Storage.

Invoke Oracle Cloud Infrastructure Object Storage from an Integration

Note:

Use of an OCI Object storage action in a project is not supported.

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

   The Configure object storage panel opens.

2. Enter a name.
3. Select the resource to manage.
   • Manage buckets: Buckets are logical containers for storing objects. Buckets are region- and compartment-specific. You can define policies at a bucket level to control access.
   • Manage objects: Objects are stored within buckets. Objects can be any data type and consist of the object itself and any metadata.
4. If you select Manage buckets:
   1. From the Operations list, select the operation to perform.
      • Create bucket: Create a bucket in Oracle Cloud Infrastructure Object Storage. In the mapper, you map the bucket name to create.
        1. Select the compartment in which to create the bucket. This selection during design-time is overridden if you map anything to the compartment Id field in the request mapper for this action.
      • List buckets: Retrieve a list of objects in a bucket in Oracle Cloud Infrastructure Object Storage. In the mapper, you map the bucket name to retrieve the objects list.
        1. Select the compartment in which to list the buckets. This selection during design-time is override if you map anything to the compartment Id field in the request mapper for this action.
      • Delete bucket: Delete a bucket in Oracle Cloud Infrastructure Object Storage. In the mapper, you map the bucket name to delete.
   2. Click Continue.
5. If you select Manage objects:
   1. From the Operations list, select the operation to perform:
      • Upload object: Upload an object into Oracle Cloud Infrastructure Object Storage. In the mapper, you map the object name to upload. This is how you update an object (it overrides an existing object with the same name). The file size limit is 1 GB. However, the API can handle objects up to 50 GB in size. See PutObject.
      • Download object: Retrieve an object from Oracle Cloud Infrastructure Object Storage. In the mapper, you map the object name to retrieve. The size limit is 1 GB. Otherwise, the download fails.
      • Delete object: Delete an object in Oracle Cloud Infrastructure Object Storage. In the mapper, you map the object name to delete.
      • List objects: List all objects in Oracle Cloud Infrastructure Object Storage. In the mapper, you map the bucket name to retrieve the objects list.
   2. Select the compartment in which to perform the operation.
   3. Select the bucket in which to perform the operation. This selection during design-time is overridden if you map anything to the Bucket Name field in the request mapper for this action.
   4. Click Continue.
6. Review your selections on the Summary page, then click Finish.

   This creates a map action in front of the OCI Object storage action.

Several use cases that natively invoke Oracle Cloud Infrastructure Object Storage are provided. See Manage Oracle Cloud Infrastructure Buckets and Objects from an Integration.

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.

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

   • Click Edit under Configure Note to enter a name and optional description for the note action.

2. Enter your notes, then click Save. You can add up to 256 characters.
3. Hover 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 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 Actions and drag the B2B action to the appropriate location.
   • Click at the location where you want to add the for-each 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 Continue.
   • B2B Trading Partner mode: Select to include B2B trading partner profiles and message persistence in your integration.
   • 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. Fetch raw messages: Fetches a B2B business message payload from persistence stored for processing.

   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 >.
   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	Select the document standard to follow when exchanging business documents between partners. Custom Delimited EDIFACT FixedLength OAG X12 X12HIPAA
      Document Version	Select the version of the document standard 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 that you created on the Documents page. For EDIFACT, X12, or X12HIPAA, you can also select Standard. See Create Custom Document Definitions in Using B2B for Oracle Integration 3.
      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. You can override this setting at runtime with the Validate request element in the mapper.

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

      Element	Description
      Run a test translation with sample data (optional)	Select or drag and drop a sample file. 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 Continue.
   5. Review your selections on the Summary page, then click Finish.

Interact with Files in File Server

You can obtain a list of files, write or move a file to File Server, get the reference of a file and then stage read or unzip the file, and delete a file on File Server using the File server action.

On This Page

• What You Can Do with the File Server Action
• When Not to Use the File Server Action
• Start Here: Add the File Server Action to an Integration
• Option 1. Obtain a List of Files in File Server
• Option 2. Write a File to File Server
• Option 3. Move a File to File Server
• Option 4. Stage a File and Work with It, or Write a File to Another Location in File Server
• Option 5. Delete a File in File Server
• Next Steps

What You Can Do with the File Server Action

The File server action lets you interact with files in the following ways.

For all of the options, you can hard code values, but most of the time, you'll pass dynamic values into the File server action using the Map action. Complete that task after you finish defining the File server action. See Next Steps.

Goal	Operation to use	Step-by-step instructions
Obtain a list of files in a File Server directory	List directory	Start Here: Add the File Server Action to an Integration Option 1. Obtain a List of Files in File Server
Create a new file in a File Server directory	Write File	Start Here: Add the File Server Action to an Integration Option 2. Write a File to File Server
Move a file from one File Server directory to another (similar to a cut and paste operation)	Move File	Start Here: Add the File Server Action to an Integration Option 3. Move a File to File Server
Get a reference to a file in a File Server director, and use the reference to complete either of the following tasks: Stage the file and then work with the staged file as needed in Oracle Integration Write the file to another File Server directory	Get File Reference	Start Here: Add the File Server Action to an Integration Option 4. Stage a File and Work with It, or Write a File to Another Location in File Server
Encrypt or decrypt a file	For files that must be encrypted and saved to File Server: Get File Reference, which gets a reference to a file. After the File server action, add a stage file action to encrypt the file, and then another File server action using the Write File operation. The File server action uploads the file to File Server by passing the encrypted file reference. For encrypted files in File Server that must be decrypted: Get File Reference, which gets a reference to an encrypted file, followed by a stage file action to decrypt the file. You can also use the capabilities of the FTP Adapter to encrypt or decrypt a file.	Start Here: Add the File Server Action to an Integration Option 4. Stage a File and Work with It, or Write a File to Another Location in File Server Process Files in Schedule Integrations with a Stage File Action Option 2. Write a File to File Server Alternatively, to use the FTP Adapter to encrypt or decrypt a file, see Create a Connection and Add the FTP Adapter Connection to an Integration in Using the FTP Adapter with Oracle Integration 3.
Delete a file in a File Server directory	Delete File	Start Here: Add the File Server Action to an Integration Option 5. Delete a File in File Server

When Not to Use the File Server Action

If you need to complete the following tasks, use a connection that is based on the FTP Adapter, or use the stage file action:

• Write a file to a temporary storage location and then perform work on the file, such as by updating the file.

• Sign or verify a file.

Start Here: Add the File Server Action to an Integration

No matter what you need to use the File server action to do, start here by adding the action to your integration.

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

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

   Note:

   If you don't see the File server action or can't add it to an integration, then an administrator needs to enable File Server for your Oracle Integration instance. See Enable File Server in Using File Server in Oracle Integration 3.

2. Fill in the following fields.

   Field	Description
   What do you want to call your endpoint?	Name of the endpoint, such as write_file_to_File_Server.
   Select resource	Select one of the following options: File: Interact with a file, such as by writing, moving, downloading, reading, or deleting it. Directory: Obtain a list of files in a specific directory in File Server.

   Additional fields, which are related to the operation that you selected, appear.

3. Continue following the steps in the appropriate section:

   • Option 1. Obtain a List of Files in File Server
   • Option 2. Write a File to File Server
   • Option 3. Move a File to File Server
   • Option 4. Stage a File and Work with It, or Write a File to Another Location in File Server
   • Option 5. Delete a File in File Server

Option 1. Obtain a List of Files in File Server

1. Complete the steps in Start Here: Add the File Server Action to an Integration.

2. From the Select operation drop-down list, select List directory.

3. Fill in the following fields.

   Field	Description	Can override later in the mapper?
   Input Directory	Name of the directory that contains the files that you need to list. Oracle recommends using an absolute directory. For example, /HOME/USERS/.	Yes
   File name pattern	Pattern of the files that you want to list, such as *.csv for only CSV files. Or, enter * to list files of all types.	Yes
   Max Files	Maximum number of files to return, up to 1000. Note: The File server action returns the files according to the last modified time. If you selected 10 as the maximum number of files and the last modified time of the eleventh file is the same as the tenth file, then the action also returns the eleventh file and any other files with the same last modified time. For example, consider a directory with 15 files, and the Max Files setting is 10. If the tenth, eleventh, twelfth, and thirteenth files have the same time stamp, then the File server action returns thirteen files.	No
   Minimum Age (seconds)	Minimum age in seconds of the files to return. For example, if a file was last modified at 02:28:45 AM, and the minimum age is 80 seconds, the file isn't returned at 02:29:00 AM and 02:30:00 AM. The file is returned only after 02:30:05.	No
   List File Recursively	Whether to list files within directories recursively beneath the input directory.	No

4. Select Continue.

5. Review the summary of the action, and select Finish.

The File server action appears on the canvas with a Map action before it.

Option 2. Write a File to File Server

1. Complete the steps in Start Here: Add the File Server Action to an Integration.

2. From the Select operation drop-down list, select Write File.

3. Fill in the following fields.

   Field	Description	Can override later in the mapper?
   Specify an Output Directory	Name of the directory to write the files to. Oracle recommends using an absolute directory. For example, /HOME/USERS/.	Yes
   File Name	Name of the file to create.	Yes

4. Select Continue.

5. Review the summary of the action, and select Finish.

The File server action appears on the canvas with a Map action before it.

Option 3. Move a File to File Server

1. Complete the steps in Start Here: Add the File Server Action to an Integration.

2. From the Select operation drop-down list, select Move File.

3. Fill in the following fields.

   Field	Description	Can override later in the mapper?
   Directory path	Name of the directory that contains the file to be moved. Oracle recommends using an absolute directory. For example, /HOME/USERS/.	Yes
   File name	Name of the file to be moved. The file can be of any size. If the file is missing, an error occurs when the integration attempts to locate it.	Yes
   Target directory path	Name of the directory to move the file to. Oracle recommends using an absolute directory. For example, /HOME/USERS/. If the directory doesn't exist, File Server creates it.	Yes
   Target file name	Name of the file in the target directory.	Yes
   Overwrite File	When selected, the target file is overwritten if it already exists. If you deselect this option and the file already exists in the target directory, an error occurs when File Server attempts to move the file to the directory.	No

4. Select Continue.

5. Review the summary of the action, and select Finish.

The File server action appears on the canvas with a Map action before it.

Option 4. Stage a File and Work with It, or Write a File to Another Location in File Server

This operation gets a reference to a file in File Server. If anyone moves or deletes the file while the integration is running, an error occurs, indicating that the file doesn't exist.

1. Complete the steps in Start Here: Add the File Server Action to an Integration.

2. From the Select operation drop-down list, select Get File Reference.

3. Fill in the following fields.

   Field	Description	Can override later in the mapper?
   Input Directory	Name of the directory that contains the files that you need to download. Oracle recommends using an absolute directory. For example, /HOME/USERS/.	Yes
   File Name	Name of the file in the input directory.	Yes

4. Select Continue.

5. Review the summary of the action, and select Finish.

The File server action appears on the canvas with a Map action before it.

Option 5. Delete a File in File Server

1. Complete the steps in Start Here: Add the File Server Action to an Integration.

2. From the Select operation drop-down list, select Delete File.

3. Fill in the following fields:

   Field	Description	Can override later in the mapper?
   Directory path	Name of the directory to delete. Oracle recommends using an absolute directory. For example, /HOME/USERS/.	Yes
   File name	Name of the file to delete.	Yes

4. Select Continue.

5. Review the summary of the action, and select Finish.

The File server action appears on the canvas with a Map action before it.

Next Steps

• Pass dynamic values into the File server action using the Map action, which appears before the File server action on the canvas. See About Mapping Data Between Applications in Using the Oracle Mapper with Oracle Integration 3.

• If you need to encrypt a file and then write it to File Server, perform the following steps:

  1. After the File server action, add a stage file action to encrypt the file.

     See Process Files in Schedule Integrations with a Stage File Action.

  2. After the stage file action, add another File server action using the Write File operation. This action uploads the file to File Server by passing the encrypted file reference.

     See Option 2. Write a File to File Server.

  Alternatively, use the FTP Adapter to encrypt the file and write it to File Server. See Create a Connection and Add the FTP Adapter Connection to an Integration in Using the FTP Adapter with Oracle Integration 3.

• If you need to decrypt a file that is in File Server, use the stage file action or the FTP Adapter. See the following links:

  • Process Files in Schedule Integrations with a Stage File Action

  • Create a Connection and Add the FTP Adapter Connection to an Integration in Using the FTP Adapter with Oracle Integration 3