Create Application-Driven Orchestrated Integrations

You can create business object- or event-based orchestrated integrations. Orchestrated integrations can be synchronous, asynchronous, or fire-and-forget types. Orchestrated integrations use Oracle BPEL Process Manager capabilities. Oracle BPEL Process Manager enables you to define how a business process that involves web services is executed. BPEL messages invoke remote services and orchestrate process execution. When designing integrations, you can create multiple routing expressions.

Create an Orchestrated Integration

This section describes how to create an orchestrated integration. It also provides an overview of the orchestrated integration canvas.

To create an orchestrated integration:

  1. Follow the steps in Create Integrations to create an orchestrated integration.

    An empty integration canvas with the following sections is displayed:
    • The Triggers icon icon in the upper right corner enables you to display a menu of available trigger adapter connections (for example, Oracle Engagement Cloud Adapter). Click an adapter to display the number of configured adapter connections available for adding to an integration. A trigger enables you to create an inbound connection in an integration.

    • The empty integration is identified by a START label in which you can drag the trigger to define the inbound part of the integration. You can also place your cursor over the + sign to invoke an inline menu for adding a trigger. See Add Actions, Connections, and Artifacts Through an Inline Menu.



    • Several icons are provided in the upper left corner for working with the integration.

      • Canvas View button Canvas View: Displays the default view of the integration canvas.
      • Pseudo View Pseudo View: Displays the integration vertically with child nodes indented. Details about each node in the integration are displayed to the right. You can edit the integration by selecting the + sign to invoke an inline menu for adding invokes and actions. See Add Actions, Connections, and Artifacts Through an Inline Menu. When you select Pseudo View, the options for Layout View disappear.



      • Global Fault: Select to add a global fault to the integration.

      • Select: Select to move specific portions of an integration.

      • Reposition: Select to enter reposition mode, then select the action or invoke in the integration and drag it to a different part of the integration. You can reposition invokes and assign, function call, map, notification, stage file (except for the Read File in Segments operation), scope, and wait actions. You cannot reposition stop, return, or error hospital elements; and repeat elements such as for-each, while, and switch actions. For this example, Assign1 is being moved below Assign2.
        Description of reposition.png follows
        Description of the illustration reposition.png

        When the action or invoke is moved, the integration design is refreshed. When you click Save, validation errors or warnings caused by the move are displayed in the Errors palette and on the individual actions or invokes. The Errors palette shows the element names. The error/warning count is displayed at the top right. The count represents the number of actions that have errors/warnings. If you fix all errors, and only warnings still exist, the count of actions that have warnings is displayed. Click Reposition again to return to edit mode to resolve any errors.

      • Layout: Select the option for viewing the integration layout:

        • Horizontal: Displays the integration horizontally.

        • Vertical: Displays the integration vertically.

      • Reset: Click to reset the integration to its normal size and place it on the left side of the page.

    • Several icons are provided in the upper right corner of the integration for adjusting the size of the integration and getting started with integration design.

      • Zoom Out: Click to decrease the size of the integration.

      • Sizing Bar: Drag the circle up and down the bar to change the size of the integration.
      • Zoom In: Click to increase the size of the integration.

      • Zoom To Fit: Click to make the entire integration visible on the page.

      • Go To Trigger: Click to go to the trigger connection in the integration.
      • Maximize / Minimize: Click to maximize the size of the orchestration. Click again to minimize the size of the orchestration.

      • A box below these icons shows a scale model of the undefined integration. You can place you cursor within the box or anywhere in the canvas to move your integration. You can also drag parts of the integration (such as switch actions) around the canvas to redraw the integration. However, the order of the integration does not change.

      • Triggers: Click to display a list of trigger connections from which to choose.
      • Errors: Displays an errors in the integration.

Add Actions, Connections, and Artifacts Through an Inline Menu

As an alternative to dragging actions, trigger and invoke connections, and integration artifacts from the right navigation pane, you can hover your cursor over the + sign that is displayed between the nodes in your integration. When you click the + sign, a list of actions, connections, and artifacts available for adding to your integration is displayed. A search facility is also available.

To add actions, connections, and artifacts through an inline menu:
  1. Hover your cursor over the lines between the nodes to display a + sign.
  2. Click the + sign.

    The + icon between a map and an adapter connection is displayed for selection.

    A menu with the following selections and a search field are displayed.


    Menu with a Commonly Used header (and its selections) and Invokes header (and its selections).

    Element Description

    Commonly Used

    Displays actions that are commonly placed between the two nodes.

    Connections

    Displays adapter connections available to add. The option is only displayed when a connection can be added after the nodes.

    Actions

    Displays actions that are allowed to be placed between the two nodes.

  3. Select the appropriate element to add to your integration or begin entering the element type in the search field at the bottom to show matching elements to add.

    The search field with text being enter is displayed.

    The dialog box or wizard specific to your selection is displayed for configuration. For example, if you add a connection, the Adapter Endpoint Configuration Wizard is displayed.

Create Global Variables

You can create complex and simple type global variables that are available for usage throughout an orchestrated integration (for example, when building an expression in the Expression Builder of an assign action).

User-defined complex type variables are defined based on the WSDLs/XSDs exposed in the integration by the trigger connection and any invokes connection. These variables are then be available throughout the integration for assignment and usage.

To create global variables:

  1. In the upper right corner of the integration canvas, click integration properties icon.
    If there are no global variables, the Global Variables dialog is displayed.
  2. Click Add Variable.
  3. Enter a name and select the data type from the dropdown list. The Object selection is considered a complex type.
    Description of define_global_variable.png follows
    Description of the illustration define_global_variable.png
  4. Click + to add more global variables. A maximum of 20 global variables can be added.
  5. If you add a global variable that is an Object data type, the dialog is expanded to display a source tree with all the elements from the request object.
  6. Expand the tree and click any element (root/child). This marks the current global variable type as a selected node type. The Type list selection changes from Object to the node name that you select.
    Description of global_variable_complex.png follows
    Description of the illustration global_variable_complex.png

    Note the following complex data type design rules:

    • Complex types are only based on XML root elements. If you select a nonroot element when creating a complex type global variable, a WSDL is automatically generated defining it as a root element for use throughout the integration.

    • Because complex type global variables are based on WSDLs/XSDs introduced into the integration by the trigger connection and invoke connections, there may be an impact when the trigger or an invoke is deleted, modified, or regenerated. Global variables react to these design changes, which may result in invalid usage/assignments.

  7. Click integration properties icon to save your changes and close the dialog.
    You cannot edit a variable. Instead, click delete icon to delete the variable, then recreate the variable.

Define Ad-Hoc Mappings

As you add switches and their associated invoke connections to the switch branches, you can add ad-hoc mappers, as needed. You can also delete the mappers that were automatically created when you added your first trigger to the integration, if they are not needed.

To define ad-hoc mappings:

  1. Delete any mappings that are not needed. For this example, the following mapping is deleted.
    Description of delete_mapping.png follows
    Description of the illustration delete_mapping.png

  2. Add a map action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Map action to the appropriate location.
    • Click Plus icon at the location where you want to add the map action, then select Map.


    The Select Output dialog is displayed.


    The Select Output dialog, which lists the endpoints to map to and a Cancel button at the bottom.

  3. Select the endpoint to which to map.

    The mapper is displayed.

  4. Map appropriate elements from the source data structure to the target data structure.

  5. When complete, click Close, then click Apply when prompted to save your changes.

Import a Map File into an Orchestrated Integration

You can import an XSL map file that was previously exported from the same integration. This action overwrites the existing mapping file. Once imported, the map file cannot be edited. For example, you can export the map from a specific integration, edit the XSL file as per a user requirement, save it, and import it back into the same integration. You cannot import an XSL map file into an orchestrated integration that was exported from a different integration in Oracle Integration or from an application in Oracle JDeveloper.

  1. Right-click the map in which you want to import an integration, and select More Actions > Import.
    Description of import_xsl_file_to_orch.png follows
    Description of the illustration import_xsl_file_to_orch.png

  2. Browse for the map file to import, then click Import. You only import the map file of an exported integration into Oracle Integration. You do not import the entire integration in which the map file is included into Oracle Integration.

Add Actions to an Orchestrated Integration

You can add actions to your integrations.

Loop over Repeating Elements with a For-Each Action

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

Creating a For-Each Action

Note:

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

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

    The For Each dialog is displayed.

  2. Expand the Source tree to select an element.

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

    Note:

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

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

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

    • Global and nonglobal repeated elements can be selected.

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

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

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

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

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

    Note:

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

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

  6. Click Done.

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

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

Tracking the Status of a For-Each Action During Runtime

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

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

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

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

  3. Select View Activity Stream from the hamburger menu menu.

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

Route Expressions with Switch Action Branches

You can define switch action branches to add routing expressions in your integration.

To define switch action branches:

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

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

    Note:

    Nested switches are supported.
    Two branches are automatically created:
    • Undefined (first) branch: You must define a routing expression for this branch.

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

    Note:

    To add more branches, click the question mark in the switch activity to invoke a menu.
  2. Click the Undefined branch icon.

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

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

    For this example, the following expression is defined:
    $FetchContactAssign = "failed" 

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

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

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

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

Note:

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

Creating a Scope Action

To create a scope action:

  1. Add a scope action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Scope action to the appropriate location.
    • Click Plus icon at the location where you want to add the scope action, then select Scope.
  2. Enter a name and optional description when prompted, and click Create.

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

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

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

  4. Select appropriate named faults.

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

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

Note:

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

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

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

Add Nested Scopes to a Scope Action

You can add nested (child) scope actions to a basic scope action. This provides a more sophisticated way of organizing or separating actions into a subsection of the integration. A nested scope provides the following capabilities:
  • Behaves the same way as a basic scope. It provides its own container of child actions and fault handlers.
  • There is no limitation to the levels of nesting. Even a scope’s fault handlers can have nested scopes.
  1. Drag a scope inside an existing scope.

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

Reposition a Scope Action in an Integration

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

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

Note:

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

Tracking the Status of a Scope Action During Runtime

You can track the status of the scope action in the Tracking Details page through the tracking diagram and activity stream for an activated integration. This is only possible if there is a tracking instance.
  1. In the left navigation pane, select Home > Monitoring > Integrations > Tracking.

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

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

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

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

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

  3. Select View Activity Stream from the hamburger menu menu.

    Details about processing status are displayed.

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

Assign Values to Scalar Variables in an Assign Action

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

Note:

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

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

  1. Add an assign action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Assign action to the appropriate location.
    • Click Plus icon at the location where you want to add the assign action, then select Assign.
  2. Enter an assignment name and optional description when prompted by the Assignments dialog, then click OK.

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

    Note:

    Once you navigate away from the Assign page (for example, go to the Expression Builder or close the Assign page), you can no longer change the name of the assign variable.
  4. Build an expression, then click Close. See Create Routing Expression Logic in Both Expression Mode and Condition Mode. The expression is automatically saved in edit mode.
    Description of assign_action_expr.png follows
    Description of the illustration assign_action_expr.png

  5. Click Yes when prompted to save your changes.

    The expression value is displayed in the Value field.
  6. Click the Add icon to add multiple assignments to the assign action. For example:
    Description of assign_action_expr2.png follows
    Description of the illustration assign_action_expr2.png

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

  7. Click Save.

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

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

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

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

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

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

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

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

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

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

Creating a While Action

Note:

Variables used in while action statements must be of a number type, and not a string type. Otherwise, they must be explicitly cast to number.
  1. Add a while action to an integration in either of the following ways:

    • On the right side of the canvas, click Actions icon and drag the While action to the appropriate location.
    • Click Plus icon at the location where you want to add the while action, then select While.
  2. Enter a name and optional description for the while action when prompted, then click OK.

    The Expression Builder is displayed.

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

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


    Description of while_activity.png follows
    Description of the illustration while_activity.png
  5. Click Close. The values of the while action are displayed in the canvas.


    Description of while_activity_values.png follows
    Description of the illustration while_activity_values.png
  6. If you want to edit the name or expression, click the respective Edit icon. Otherwise, click Return icon to return to the integration canvas.

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

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

    Note:

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

Tracking the Status of a While Action During Runtime

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

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

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

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

  3. Select View Activity Stream from the hamburger menu menu.

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

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

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

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


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

  11. Click Done.

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

Note:

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

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

Set the content-type in a Notification Action

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

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

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

Creating a Wait Action

  1. Add a wait action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Wait action to the appropriate location.
    • Click Plus icon at the location where you want to add the wait action, then select Wait.
  2. Enter the following details when prompted, then click OK.
    • Name of the action.

    • Optional description of the action.

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

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

Tracking the Status of a Wait Action During Runtime

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

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

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

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

  3. Select View Activity Stream from the hamburger menu menu.

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

Add Global Fault Handling to Orchestrated Integrations

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

Adding a Global Fault

To add a global fault:

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

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

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

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

  3. Click the upper branch, then select the Edit icon.
    Description of global_fault_switch.png follows
    Description of the illustration global_fault_switch.png

    The Expression Builder is displayed. In the Source tree, the schedule (trigger) and target fault handling information are both displayed.
    Description of ics_source_target.png follows
    Description of the illustration ics_source_target.png

    Note:

    The Expression Builder includes the following functions under Functions > Integration Cloud for designing fault handling:
    • getFaultAsString (returns the fault as a string value)

    • getFaultAsXML (the fault as an XML element)

    • getFaultedActionName (returns the fault of the action)

    • getFaultName (returns the fault name)

    • getFlowId (returns the flow ID of the integration)

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

  4. Build an expression to capture fault handling information. For example:
    $TargetApplicationObject1/nssrcmpr:fault/nssrcmpr:details = "ERROR"
  5. Drag a Stop action to the Otherwise branch of the switch action.

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

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

  8. Complete design of the orchestrated integration.

  9. Click Save, then click Close.

  10. Activate the integration.

Tracking the Status of a Global Fault During Runtime

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

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

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

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

  3. Select View Activity Stream from the hamburger menu menu.

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

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

Catch Faults with a Re-throw Fault Action

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

To catch faults with a re-throw fault action:

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

    • On the right side of the canvas, click Actions icon and drag the Re-throw Fault action to the appropriate location.
    • Click Plus icon at the location where you want to add the re-throw fault action, then select Re-throw Fault.
  2. Create an integration that includes a scope action. See Manage a Group of Actions and Fault Handlers with a Scope Action.

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

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

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

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

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

    The Re-throw Fault icon is hidden.

  7. Design additional logic in the scope action.

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


    Description of raise_error_return.png follows
    Description of the illustration raise_error_return.png

Throw Faults with a Throw New Fault Action

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

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

    Click the Edit icon to create an expression in the Expression Builder. This is a mandatory field.

    Reason

    Click the Edit icon to define a reason for the error in the Expression Builder.

    Details

    Click the Edit icon to define additional error details in the Expression Builder.

    Skip Condition

    Define a condition to prevent the fault from being throw in the Skip Condition version of the Expression Builder.



    The throw new fault action is displayed in the integration.

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

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

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

Process Files in Scheduled Integrations with a Stage File Action

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

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

For example, you may include a stage file action in an integration as follows:
  • Configure an FTP Adapter with the following settings:

    • Download File operation

    • Unzip the File option

    • Input directory and download directory path

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

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

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

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

Note:

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

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

Process File References

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

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

    The following operations provide file references:

    • Attachment reference (REST Adapter attachments)

    • Stream reference (REST Adapter invoke response)

    • MTOM (for a SOAP Adapter invoke connection response)

    • FileReference (for an FTP Adapter)

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

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

Creating Local Files

Note the following details about local file behavior:

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

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

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

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

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

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

Configure a Stage File Action

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

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

When configuring the stage file action in the Configure Stage File Action wizard, note that there are restrictions on using some operations with the connectivity agent.
  • List File operation: Files uploaded through the connectivity agent are not available with the List File operation.
  • Read Entire File and Read File in Segments operations: Files uploaded through the connectivity agent can only be read with a file reference.
  • Zip File operation: Files uploaded through the connectivity agent are not available with the Zip File operation.
  • Unzip File operation: Files uploaded through the connectivity agent can only be unzipped using a file reference.

Start the Configure Stage File Action Wizard

  1. Add a stage file action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Stage File action to the appropriate location.
    • Click Plus icon at the location where you want to add the stage file action, then select Stage File.
  2. Complete the fields on the Basic Info page, and click Next.

    The Configure Operation page is displayed.

Configuring Stage File Operations

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

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

    Read Entire File

    Table 3-1 - Read Entire File

    Property Description

    Configure File Reference

    • Yes: Select to process an upstream operation that provides a file reference. Once selected, you specify the file reference.

    • No: Select to process a file name.

    Specify the File Reference

    (Appears if you select Yes for the Configure File Reference.)

    Click the Expression Builder icon to specify a file reference.

    Specify the File Name

    (Appears if you select No for the Configure File Reference.)

    Click the Expression Builder icon to build an expression to specify the file name (for example, /compress:schedule/compress:start Time).

    Note: The file size must be less than 10 MB. For files greater than 10 MB, use the Read File in Segments operation.

    Specify the Directory to read from

    Click the Expression Builder icon to build an expression to specify the directory from which to read files.

    Remove Trailer

    Select to not remove the trailer, to remove the last row, or to remove the last n rows.

    Decrypt Click the check box, then select the private key of the target location to use to decrypt the file.

    Read File in Segments

    This option enables you to read files in segments (chunks). Chunking files enables large files to be processed, one logical chunk at a time. A logical chunk (segment) is retrieved from a huge file, enabling the file to stay within memory constraints. You can also read large XML files containing repeating elements and multiple namespaces. A use case is provided. See Read Large XML Files Containing Multiple Namespaces.

    Note:

    If you select the Read File in Segments operation, you cannot specify an opaque or JSON schema. If you do, you receive the following runtime error:
    NXSD has infinite loop.
    Flow has bad NXSD or bad input file which is causing infinite loop.
    Either NXSD is not designed properly or input file is not compatible with
    NXSD. Processing of file at stage read was not advancing and looping at same
    location in input file.
    Please download ICS flow and review NXSD file or inspect input file to ensure
    there are no infinite loop.
    Stage Read Failed

    Table 3-2 - Read File in Segments

    Property Description

    Configure File Reference

    • Yes: Select to process an upstream operation that provides a file reference.

    • No: Select to process a file name.

    Specify the File Reference

    (Appears if you select Yes for the Configure File Reference.)

    Click the Expression Builder icon to specify a file reference.

    Specify the File Name

    (Appears if you select No for the Configure File Reference.)

    Click the Expression Builder icon to build an expression to specify the file name.

    The Read File in Segments option creates a stage file action that includes a scope part. This enables you to drag actions inside the scope (such as for-each actions, additional stage file actions, and others) for more complex scenarios.

    Specify the Directory to read from

    Click the Expression Builder icon to build an expression to specify the directory from which to read.

    Segment Size

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

    Note:
    • This field is not displayed when you add a new stage file action to an integration. The segment size defaults to 200 records and cannot be changed.

    • This field is only displayed in existing stage file actions in which a segment size of other than 200 records is specified. For these scenarios, you can specify a value between 10 and 200 records.

    Process Sequentially

    Select to read the segments sequentially.

    Remove Trailer

    Select to not remove the trailer, to remove the last row, or to remove the last n rows.

    Write File

    Table 3-3 - Write File

    Property Description
    Specify the File Name

    Click the Expression Builder icon to build an expression to specify the file name.

    Specify the Output Directory

    Click the Expression Builder icon to build an expression to specify the output directory.

    Append to Existing File

    Optionally select to append records to the existing file.

    Encrypt Click the check box, then select the public key of the target location to use to encrypt the file.

    Zip Files

    Table 3-4 - Zip Files

    Property Description
    Specify the File Name

    Click the Expression Builder icon to build an expression to specify the file name.

    Specify the Directory to zip

    Click the Expression Builder icon to build an expression to specify the directory to ZIP.

    Specify the Output Directory

    Click the Expression Builder icon to build an expression to specify the output directory in which to write a ZIP file.

    Unzip File

    Table 3-5 - Unzip File

    Property Description

    Configure File Reference

    • Yes: Select to process an upstream operation that provides a ZIP file reference. Once selected, you specify the file reference and the directory in which to unzip the file.

    • No: Select to process a ZIP file.

    Specify the File Reference

    (Appears if you select Yes for the Configure File Reference.)

    Click the Expression Builder icon to specify a ZIP file reference.

    Specify the Zip File Name

    (Appears if you select No for the Configure File Reference.)

    Click the Expression Builder icon to build an expression to specify the ZIP file name to read.

    Specify the Zip File Directory

    Click the Expression Builder icon to build an expression to specify the directory in which to unzip the file.

    Specify the Directory to Unzip

    Click the Expression Builder icon to build an expression to specify the directory in which to unzip files.

    Encrypt File

    Table 3-6 - Encrypt File

    Property Description
    Specify the File Reference

    Click the Expression Builder icon to specify a file reference.

    Specify the File Name

    Click the Expression Builder icon to build an expression to specify the file name.

    Specify the Output Directory

    Click the Expression Builder icon to build an expression to specify the output directory.

    Specify PGP Key to encrypt file Select the private key of the target location to use to encrypt the file. You can encrypt a file up to 1 GB in size.

    When using the mapper, note that encrypt is visible as an element for mapping.

    Decrypt File

    Table 3-7 - Decrypt File

    Property Description
    Specify the File Reference

    Click the Expression Builder icon to specify a file reference.

    Specify the File Name

    Click the Expression Builder icon to build an expression to specify the file name.

    Specify the Output Directory

    Click the Expression Builder icon to build an expression to specify the output directory.

    Specify PGP Key to decrypt file Select the private key of the target location to use to decrypt the file. You can decrypt a file up to 1 GB in size.

    When using the mapper, note that decrypt is visible as an element for mapping.

    List File

    Table 3-8 - List File

    Property Description
    Specify the Directory to List Files from

    Click the Expression Builder icon to build an expression to specify the directory from which to list files.

    Specify the File Pattern to use

    Specify the pattern of the file name to transfer to the output directory. Click the ? icon for the list of supported patterns.

    List Files Recursively

    Select to list the files recursively.

  2. When complete, click Next.

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

Defining the Schema File

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

  1. Provide the following details.

    Property Description
    Do you want to specify the structure for the contents of the file for the payload?

    Select Yes to define a schema format to use for the files to transfer. Select No if a schema is not required and you want to send opaque files (for example, a GIF or PNG file).

    Which one the following choices would be used to describe the structure of the file contents?
    Select an option:
    • Sample delimited document (erg. CSV): Select to create a new schema from a CSV file. On a subsequent page of this wizard, you are prompted to select the CSV file from which to create the schema.

    • XML schema (XSD) document: Select to create a new schema from an XML schema (XSD) file. You can upload a ZIP file with nested XML schema files.

    • Sample XML document (Single or No Name Space): Select to create a new schema from a sample XML file with a single or no name space.

    • Sample JSON document: Select to create a new schema from a JSON file.

    • EDI document: Select to create a new schema from an EDI X12 document, then select the character encoding that the imported EDI X12 document is expected to use. B2B for Oracle Integration supports the EDI X12 business protocol for the exchange of business documents between Oracle Integration and a trading partner. See Introduction to B2B for Oracle Integration in Using B2B for Oracle Integration.
  2. When complete, click Next.

Defining the Schema Format

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

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

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

    Element Description
    • Select the Delimited Data File

    Select the delimited comma-separated value (CSV) file from which to create the schema file. The content of the file is then displayed at the bottom of the page. This field appears if you selected to create a new schema on the Basic Info page of the wizard.

    • Enter the Record Name

    Enter the record name. This becomes the parent element in the created schema file for the record names selected as column headers from the CSV file.

    • Enter the Recordset Name

    Enter the recordset name. This becomes the root element of the created schema file.

    • Select the Field Delimiter

    Select one of the following supported file delimiter options:

    • Single space

    • Comma

    • Semicolon

    • Tab

    • Pipe (for example, Name|City|Country)

    • Character Set

    Select a character set. The selected value will be used as the encoding format while reading the sample data file.

    • Optionally Enclosed By

    This value causes occurrences of the selected delimiter to be ignored during processing. For example, when processing the following record:

    Fred,"2 Old Street, Old Town,Manchester",20-08-1954,0161-499-1718

    If the selected Field Delimiter is “,” and the Optionally Enclosed By value is quot; (), then the value 2 Old Street, Old Town,Manchester is treated as a single record column.

    • Use the First Row as Column Headers

    Displays by default the first row of the selected CSV file as the column headers.

    • Detach

    Select to edit the CSV file in a separate window.

    • Mark All As Optional

    Select to mark elements as optional in the schema file. By default, all elements are mandatory. You can also select the data type (for example, string, byte, integer, and so on) to use for each column in the table and mark specific elements as optional. While this option enables you to select all elements as optional, you must have at least one mandatory element to validate this page. This check box provides a convenient method to select the majority of elements as optional.

    Table 3-10 - XML Schema (XSD) Document

    Element Description
    • Select a New File

    Select an existing XML schema file or schema archive file from the file system.

    • Selected File Name

    Displays the selected schema file name.

    • Select the Element Name

    Select the schema element. This field is displayed after the XML schema file is selected. The element name is treated as the root element in the uploaded schema file.

    • Select Repeating Batch Element

    Click the Expression Builder icon to build an expression to identify the repeating node in the schema to support payload chunking.

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

    Element Description
    • Select a New File

    Select a sample XML document from the file system. The file must contain no namespace or a single namespace.

    • Selected File Name

    Displays the selected schema file name.

    • Select the Schema Element

    Select the schema element. This field is displayed after the sample XML file is selected. The element name is treated as the root element in the uploaded schema file.

    • Select Repeating Batch Element

    Click the Expression Builder icon to build an expression to identify the repeating node in the schema to support payload chunking.

    Table 3-12 - Sample JSON document

    Element Description
    • Select a New File

    Select a sample JSON document from the file system.

    • Selected File Name

    Displays the selected schema file name.

    • Select the Schema Element

    Select the schema element. This field is displayed after the JSON file is selected. The element name is treated as the root element in the uploaded schema file.

  2. Complete the fields, and click Next.

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

Reviewing the Stage File Action in the Integration Canvas

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

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


    This image shows a schedule connected to a stage file action.

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

    Note:

    If a variable is declared outside of a loop of a stage file action that was configured with the Read File in Segments operation and updated within the stage file action loop, the last updated value for that variable is available outside of the loop. In such a case, the DOP (degree of parallelism) is set to 1 to avoid concurrency issues.
  • If you designed a stage file action with an operation other than a Read File in Segments operation, a scope portion is not included.
    Description of stage_file_chunk3.png follows
    Description of the illustration stage_file_chunk3.png

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

Log Messages with a Logger Action

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

Creating a Logger Action

To create a logger action:

  1. Add a logger action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Log action to the appropriate location.
    • Click Plus icon at the location where you want to add the log action, then select Log.
  2. Enter a name and optional description, then click OK.

    The Logger page is displayed.

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

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

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

    concat(“The file ”,fileName, “has been uploaded to “,directory)
  6. When complete, click Close. For this example, a log action is included in the integration.
    Description of logger_action.png follows
    Description of the illustration logger_action.png

Tracking the Status of a Logger Action During Runtime

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

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

  2. Select View Activity Stream from the hamburger menu menu.

    Details about processing status are displayed.

  3. In the left navigation pane, click Dashboards.
  4. Select Diagnostic Logs from the Logs list.

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

Add a JavaScript Action

You can add JavaScript functions to the integration.

Creating a JavaScript Action

To create a JavaScript action:

Note:

Note the following restrictions when using the JavaScript action:

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

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

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

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

    • On the right side of the canvas, click Actions icon and drag the Javascript action to the appropriate location.
    • Click Plus icon at the location where you want to add the Javascript action, then select Javascript.
  2. Enter a name and optional description for the JavaScript action when prompted, then click OK.

  3. Click the +Function button.

    The Select a Function dialog appears.

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

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

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

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

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

Tracking the Status of a Javascript Action During Runtime

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

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

Add Placeholder Notes with a Note Action

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

The note action is a design-time feature that does not impact runtime. Any changes to upstream or downstream actions in your integration do not impact the note action.
To add a note action:
  1. Add a note action to an integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the Note action to the appropriate location.
    • Click Plus icon at the location where you want to add the note action, then select Note.
  2. Enter a name and description of the action, then click OK.
    The action is added to the integration.
  3. Click the Edit icon to add your notes. You can add up to 256 characters.
  4. Enter your notes, then click OK.
  5. Hover your cursor over the icon to display the note text.

Translate an EDI Document with the EDI Translate Action

You can translate a message to or from the Electronic Data Interchange (EDI) format in an orchestrated integration with the EDI translate action. This action invokes the EDI Translate Action Wizard to guide you through configuration with the EDI X12 document standard. The EDI translate action translates an incoming EDI document into an Oracle Integration XML message and translates an outgoing Oracle Integration XML message into an EDI X12 document.

  1. Add an EDI translate action to the integration in either of the following ways:
    • On the right side of the canvas, click Actions icon and drag the EDI Translate icon to the appropriate location.
    • Click Plus icon at the location where you want to add the action, then select EDI Translate.
    The EDI Translate Action Wizard is displayed.
  2. Enter a name and optional description, then click Next.
  3. Specify the message translation and document format details.
    Element Description
    Select the direction in which to translate the message
    • Inbound EDI message to Oracle Integration message: When an integration receives an EDI document from a business partner, it is considered an inbound document (an EDI document is translated to XML).
    • Oracle Integration message to outbound EDI message: When an integration sends an EDI document to a business partner, it is considered an outbound document (an EDI document is generated from XML).
    Document Standard The document standard identifies the business protocol to follow when exchanging business documents between partners. EDI X12 is automatically selected for use and cannot be deselected.
    Document Version Lists the supported versions of the EDI X12 standard. Select the document version to use.
    Document Type Select the document type (for example, purchase order, invoice, shipping notice, or others). The document types available for selection are based on the document version you selected.
    Document Definition Select the document definition (either Standard or a custom document definition that you created on the B2B Documents page).

    See Create Custom Document Definitions in Using B2B for Oracle Integration.

    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.


  4. Click Next.
  5. Specify to optionally upload sample data to test that translation is successful.
    Element Description
    Select sample data to upload Click Browse to upload a sample. To test inbound EDI message translation, upload an EDI document. To test outbound EDI message generation, upload an XML document.
    Translate Click to translate your sample data. Output is displayed in the Output of translation field. Any errors are displayed in the Error in translation field.
  6. Click Next.
  7. Review your selections on the Summary page, then click Done.

Use XPath Axis and Wildcard Expressions in the Expression Builder

You can include XPath axis and wildcard expressions in actions that support the Expression Builder (for example, assign and switch actions support the Expression Builder).

  1. Create an assign action or switch action and navigate to the Expression Builder.

  2. In the Expression field for an assign or switch action, build an expression using either option:
    • Wildcard expression:

      For this example, a wildcard is entered to select all elements below Answer.

      /nssrcmpr:process/nssrcmpr:Answer/*

      Or, to select all elements:

      /*
    • Axis expression:

      For this example, descendant is entered to select all descendants (child, grandchildren, and so on) of the current node. Any descendant with this ID and namespace (mb_v1_3:ID) is retrieved by the expression.

      /nssrcmpr:process/nssrcmpr:Answer/descendant::mb_v1_3:ID

      Axis expressions adhere to the following syntax:

      axisname::nodetest[predicate]

      The following table provides examples of axis expressions:

      Syntax Result
      child::book

      Selects all book nodes that are children of the current node.

      attribute::lang

      Selects the lang attribute of the current node.

      child::*

      Selects all element children of the current node.

      attribute::*

      Selects all attributes of the current node.

      child::text()

      Selects all text node children of the current node.

      child::node()

      Selects all children of the current node.

      descendant::book

      Selects all book descendants of the current node

      ancestor::book

      Selects all book ancestors of the current node.

      ancestor-or-self::book

      Selects all book ancestors of the current node and the current if it is a book node.

      child::*/child::price

      Selects all price grandchildren of the current node.

  3. Click the Expression Summary icon to validate the expression.

  4. When complete, click Close.

Use Lookups in Variable Assignments

You can create variable assignments that use lookups in the Expression Builder. You must have already created the lookup.

  1. Create a lookup in Oracle Integration. See Manage Lookups.

    For this example, a lookup named ZIP_CITY_DVM is created to map the ZIP codes (using a SOAP Adapter) and the city names (using a domain name).

    SOAP (Adapter) SOAPCITY (Domain Name)
    80112 Englewood
    85003 Phoenix
    80007 Arvada
    80220 Denver
  2. Create an orchestration into which a SOAP Adapter is added as the trigger.

  3. Drag the Assign icon to the plus sign for the SOAP Adapter in the integration canvas.

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

  5. Enter a name for the assignment in the Name field, then click the Expression Builder icon at the far right.

  6. In the Expression Builder, expand Functions > Oracle Integration.

  7. Drag the lookupValue function to the Expression field.

    This starts the Build Lookup Function wizard.

  8. Select the lookup table, and click Next. For this example, the lookup created in Step 1 (ZIP_CITY_DVM) is selected.

  9. Select the source and target columns. For example, select to pass the city to the ZIP code.


    Description of ics_lookups_source_target.png follows
    Description of the illustration ics_lookups_source_target.png
  10. Complete the remaining pages of the wizard, then click Done.

  11. In the Source tree, select the element to map. For this example, ZIP is dragged on top of srcValue in the Expression field.

  12. Click Close.

    The completed variable assignment is displayed.

  13. Click Exit Assignments.

  14. In the orchestrated integration, click the mapper icon, then click the Edit icon.

  15. Assign the variable you created to the city target element, then click Save.
    Description of ics_lookups_source_target3.png follows
    Description of the illustration ics_lookups_source_target3.png

  16. Click Close.

Define Fault Aggregation in Parallel Processing Scenarios

Oracle Integration includes a predefined fault object for fault aggregation. This object enables you to catch and aggregate faults in the context of parallel processing in scheduled orchestrated integrations and to send these faults to an external service to define more granular error handling. To define a fault object and aggregate the faults, you must use actions that support looping (for example, for-each loops, while loops, and so on).

Note:

The fault object is only supported with scheduled orchestrated integrations.
Two fault aggregation operations are available for selection in scheduled orchestrated integrations:
  • append: Adds a new fault to the end of a fault list.

  • clear: Removes all entries in a fault list.

These options are available for selection under the following scenarios:
Location Append Option Allowed? Clear Option Allowed?
Top level (that is, outside of any looping actions) Yes Yes
Inside a for-each action with the For Process items in parallel option selected Yes No
Inside a for-each action loop and a while action loop Yes Yes
Inside a stage file action configured with the Read File in Segments operation Yes No
Inside a scope action Yes Yes
Inside a global fault or a named fault (that is, inside a scope fault handler) Yes Yes

To configure fault aggregation:

  1. Created a scheduled orchestrated integration.

  2. Create an aggregated fault per the scenarios supported in the above table. For example, create a For-Each action, then drag an Assign action within the loop.

  3. Create an assignment and select faults from the Data Type list.

    The page is refreshed to display the Operations list with two options.


    Description of ics_fault_aggreg.png follows
    Description of the illustration ics_fault_aggreg.png
  4. Click the Expression Builder icon to build the fault object mapping.


    Description of ics_fault_aggreg2.png follows
    Description of the illustration ics_fault_aggreg2.png
  5. Complete your mapping.

  6. Define an invoke connection to send the aggregated faults to an external service.

    Note:

    Changing the name, data type, or both is only allowed during initial creation of the variable while not yet assigned a value.

Assign Business Identifiers for Tracking Fields

Business identifiers enable you to track payload fields in messages during runtime. You must assign business identifiers before you can activate an orchestrated integration.

  1. From the hamburger menu menu in the upper right corner of the integration canvas, select Tracking to assign business identifiers for tracking fields. See Assign Business Identifiers for Tracking Fields in Messages.

  2. When complete, click Done.

  3. When the orchestrated integration is complete, click Save, then click Close.

  4. Activate your integration. See Activate an Integration.

  5. Manage and monitor your integration. See Monitor Integrations and Track Business Identifiers in Integrations During Runtime.

Display Errors and Warnings in an Integration

If there are errors or warnings in an integration (for example, an empty or invalid map, a missing tracking attribute, or an invalid assign or switch action), an ERRORS section is displayed on the left side. These errors and warnings prevent you from activating an integration. You must first resolve these issues to activate an integration.

Note:

  • For integrations created prior to version 16.4.5, you must first save the integration once to enable error and warning validation functionality.

  • Error and warning validation of for-each actions is not supported.

  1. Design an orchestrated integration.

    If there are errors or warnings, an Errors section is displayed on the right side.

  2. Click the Errors section to display error and warning details. For this example, an invoke adapter was deleted for which mapping had previously been configured, causing the mapper to be invalidated. In addition, tracking is not configured.

  3. If you return to the Integrations page, note that the status of the integration is DRAFT. You cannot activate integrations in the DRAFT state.

  4. Return to the integration canvas and resolve any errors and warnings. Once these issues are resolved, the ERRORS section disappears.

  5. Save the integration and return to the Integrations page. Note that the DRAFT status is replaced with PENDING ACTIVATION. You can now activate the integration.