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

      Description of empty_canvas.png follows
      Description of the illustration empty_canvas.png
    • 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

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

      • Zoom Out: Click to decrease 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.

      • Home: Click to align the integration in normal size in the upper left corner of the page.

      • Start: Click to reset the integration to its normal size and place it in the middle of the page.

      • Multiple Select: Click and then drag the cursor around parts of the integration to select them. This action highlights the selected sections in blue.

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

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

    Integration Artifacts

    Displays integration artifacts 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.

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 to create two mappings for the defined and otherwise branches that output to the order invoke connection.
    Description of ics_orchest_del_map.png follows
    Description of the illustration ics_orchest_del_map.png

  2. On the right side, expand the Actions section.

  3. Drag a Map icon to a branch of the switch activity. For this example, the map is first dragged to the + sign of the defined branch.
    Description of ics_orchest_add_map.png follows
    Description of the illustration ics_orchest_add_map.png

    The Select Output dialog is displayed.
    Description of ics_orchest_sel_obj.png follows
    Description of the illustration ics_orchest_sel_obj.png

  4. Select the endpoint to which to map. For this example, the Order endpoint is selected.

    The mapper is displayed.

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

  6. When complete, click Close, then click Apply to save your changes.

  7. Drag a Map icon to the otherwise branch of the switch activity.

    The Select Output dialog is displayed.

  8. Select the endpoint to which to map, and click Select. For this example, the Order endpoint is also selected.

    The mapper is displayed.

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

  10. When complete, click Close, then click Apply to save your changes.

    Mappings for both branches of the switch activity are now displayed.
    • The inbound trigger connection is configured with an opportunity business object.

    • A switch activity is defined with two branches:

      • If the routing expression for the defined branch resolves to true, the mapping for that data is performed for the outbound invoke connection.

      • If the routing expression for the defined branch does not resolve to true, the otherwise branch is taken and the mapping for that data is performed for the outbound invoke connection.

      You can click the mappers to display a menu for editing or viewing the mapper. You can also click the invoke connections to edit or view their contents.


    Description of ics_orchest_both_map.png follows
    Description of the illustration ics_orchest_both_map.png
    You can make the integration as complex as is required. For example, you can:
    • Add additional switches to other parts of the integration.

    • Add additional ad-hoc mappings to the branches of the switches.

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. On the right side of the canvas, click Actions to expand the panel.

  2. Drag the For Each icon to the plus sign where you want to loop over an element.

    The For Each dialog is displayed.

  3. Expand the Source 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 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.

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

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

  7. Click Done.

    The for-each action is displayed in the canvas. A looping arrow indicates that this action performs repetitive looping.
    Description of repeating_element_scope.png follows
    Description of the illustration repeating_element_scope.png

  8. Drag other actions inside the for-each action to define what should happen during each iteration of the loop. For this example, an assign action is dragged to the plus sign below the for-each action.

    Enter a name for the assign action, and click OK.

  9. Click the Edit icon.

    The Expression Builder is displayed. Note that the value you entered in the Current Element Name field in Step 6 (currentFileName) is displayed as an expandable element in the Source tree.

  10. Expand $currentFileName in the Source tree.

    The repeatable element you added in Step 5 (ICSFile) is displayed.

  11. Drag the ICSFile element to the Expression field, and click Close.

  12. In the Assign dialog, enter a variable name in the Name field, and click Exit Assignments.

    The assign action is added to the scope of the for-each action. After integration activation, the for-each action loops over the assign action for each downloaded file.

Tracking the Status of a For-Each Action During Runtime

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

  1. In the navigation pane, select Monitoring > 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. In the upper right corner, click the Actions menu and select View Audit Trail.

    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 Branches

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

To define switch branches:

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

  2. Drag the Switch icon to the integration canvas. As you do, large + sections within circles are displayed that indicate where you can drop the switch activity. For this example, the switch activity is added immediately after the trigger connection.

    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.
  3. Click the Undefined branch icon.

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

  5. 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:
    /nssrcmpr:process/nssrcmpr:Contact_CustomObj/rnb_v1_3:LookupName = "Denver"

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

  6. Return to the left side of the canvas, and click Invokes to expand the panel.

  7. Drag an adapter to the appropriate + section within the circle. Two are available: one for the defined branch and another for the otherwise branch. For this example, the section for the otherwise branch is selected.
    Description of ics_orchest_switch_def.png follows
    Description of the illustration ics_orchest_switch_def.png

    This invokes the Adapter Endpoint Configuration Wizard.

  8. Complete the pages of the wizard to configure the selected adapter.

    This creates an extra invoke connection on the otherwise branch. You can use the data from this invoke connection to initiate an order with the endpoint.
    Description of ics_orchest_switch_inv.png follows
    Description of the illustration ics_orchest_switch_inv.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. On the right side of the canvas, click Actions to expand the panel.

  2. Drag the Scope icon to the appropriate plus sign location in the integration.

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

  4. 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.
    Description of scope_action_design.png follows
    Description of the illustration scope_action_design.png

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

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

Note:

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

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

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

Add Nested Scopes to a Scope Action

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

Reposition a Scope Action in an Integration

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

  1. Find the scope action to reposition.
  2. Inside the scope, click 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 audit trail for an activated integration. This is only possible if there is a tracking instance.
  1. In the navigation pane, select Monitoring > 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. In the upper right corner, click the hamburger menu menu and select View Audit Trail. Details about processing status are displayed. For example:

    • If scope execution succeeds, details similar to the following are displayed:

      
      Message processed successfully for Trigger GetWeather.
      Message entered Scope Scope.
      Message processed successfully for Invoke GetOrg.
      Message exited Scope Scope.
      Message processed successfully for Reply GetWeather.
      
    • If scope execution fails, but the fault handler succeeds in handling the fault, details similar to the following are displayed:

      Message processed successfully for Trigger GetWeather.
      Message entered Scope Scope.
      Error processing message in Invoke GetOrg.
      Scope fault handler started.
      Scope fault handler ended.
      Message exited Scope Scope.
      Message processed successfully for Reply GetWeather.
      
    • If both the scope and fault handler fail, details similar to the following are displayed:

      Message processed successfully for Trigger GetWeather.
      Message entered Scope Scope.
      Error processing message in Invoke GetOrg.
      Scope fault handler started.
      Error processing message in Invoke faultInvoke
      OSB-380001: Invoke JCA outbound service failed with application error, except...
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. On the right side of the canvas, click Actions to expand the panel.

  2. Drag the Assign icon to the appropriate plus sign location in the integration canvas.

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

  4. 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.
  5. 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 ics_orchestration_variables.png follows
    Description of the illustration ics_orchestration_variables.png

  6. Click Yes when prompted to save your changes.

    The expression value is displayed in the Value field. Description of ics_orchestration_var2.png follows
    Description of the illustration ics_orchestration_var2.png
  7. Click the Add icon to add multiple assignments to the Assign node. You can also define an assignment with a value from a previously defined assignment. In the following example, AccountId (the previously created assignment) is assigned as the value of assignment AccountIdNow.
    Description of ics_orchestration_var3.png follows
    Description of the illustration ics_orchestration_var3.png

  8. Click Exit Assignments.

  9. Click Save.

Variable assignments can be of greater complexity. For example, you can use assignments in switch activities and in maps. For example, in the following orchestration, the next organization ID is assigned.
Description of ics_orchestration_var4.png follows
Description of the illustration ics_orchestration_var4.png

  1. Click the ASSIGN node. NewOrgID is assigned a value of OrganizationId + 1.0. OrganizationId is the business object that comes from the trigger element that initiates this orchestration.


    Description of ics_orchestration_var5.png follows
    Description of the illustration ics_orchestration_var5.png
  2. View the switch activity in the orchestration. While OrganizationId is less than or equal to 15.0, another assignment is performed in VarNodeInSwitch.


    Description of ics_orchestration_var6.png follows
    Description of the illustration ics_orchestration_var6.png
  3. Click VarNodeInSwitch and note that it reverts to the original value.


    Description of ics_orchestration_var7.png follows
    Description of the illustration ics_orchestration_var7.png

    You can also map assignment values in the mapper.

    If there is an error in your assignments, an identifier is displayed next to the ASSIGN node and also in the mapper.

    Description of ics_orchestration_var8.png follows
    Description of the illustration ics_orchestration_var8.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. On the right side of the canvas, click Actions to expand the palette.

  2. Drag the While icon to the Plus sign where you want to create a looping condition.

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

    The Expression Builder is displayed.

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

  5. Drag an element 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
  6. Click Exit Condition Builder, then click Yes when prompted to save your changes. 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
  7. 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

  8. 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 audit trail for an activated integration. This is only possible if there is a tracking instance.

  1. In the navigation pane, click Integrations, then click the < arrow next to Designer.

  2. Click Monitoring, then click Tracking.

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

  4. In the upper right corner, click the hamburger menu menu and select View Audit Trail.

    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.
    Message processed successfully for Trigger trigger
    Message processed successfully for Assignment init
    Message processed successfully for Invoke invoke
    Message processing started for While outerwhile
    Message processing ended for While outerwhile
    Message processed successfully for Reply trigger

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 also create the body part of an email using parameters defined in the Expression Builder.

  1. On the right side of the canvas, click Actions to expand the panel.
  2. Drag the Notification icon to the Plus sign where you want to add a notification. For example, you may define notifications on the two branches of a switch action.
  3. Enter a name and optional description for the notification action when prompted, then click OK.
  4. 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.
  5. 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.
  6. To add a parameter name and value, click the Plus icon in the Parameters section.
  7. Enter a parameter name and description.
  8. Click the Expression Builder icons to define parameter values (for this example, ID. and LookupName are created).
    When complete, the page looks similar to the following:
    Description of edit_notification_act.png follows
    Description of the illustration edit_notification_act.png
  9. Click Done.

When the email notification is received during integration runtime, the two parameters of ID and LookupName are replaced with dynamic values:

All recipients;

This is an automatically generated e-mail from the Complex_Switch_REF_Trigger orchestration.

The ID passed is 20. The corresponding LookupName is TestOrg1.

BR,

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 LookupName or ID@id examples used in this section are modified, the parameter assignment become invalid. Or when $lastname or @firstname is deleted, the To field becomes 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 Tracking 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. On the right side of the canvas, click Actions to expand the palette.

  2. Drag the Wait icon to the Plus sign where you want to delay execution of the integration.

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

  4. 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 audit trail for an activated integration. This is only possible if there is a tracking instance.

  1. In the navigation pane, select Monitoring > Tracking.

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

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

  3. In the upper right corner, click the hamburger menu menu and select View Audit Trail.

    Details about processing status (including any wait actions) are displayed. For example:
    Schedule triggered successfully.
    Wait one_min triggerd.
    Message processed successfully for Invoke weather.
    Processing completed successfully.

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. From the hamburger menu menu in the upper right corner, select Global Fault.

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

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

  3. Select the Actions palette, and drag a Switch action into the integration.

  4. Click the Undefined branch, then select the Edit icon.
    Description of ics_edit_switch_activity.png follows
    Description of the illustration ics_edit_switch_activity.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 > ICS for designing fault handling:
    • getFaultAsString (returns the fault as a string value)

    • getFaultAsXML (the fault as an XML element)

    • getFaultName (returns the fault name)

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

  5. Build an expression to capture fault handling information. For example:
    $TargetApplicationObject1/nssrcmpr:fault/nssrcmpr:details = "ERROR"
  6. Click Close to return to the Global Fault Handler page.

  7. From the Actions palette, drag a Stop action to the Otherwise branch of the switch action.
    Description of ics_switch_stop.png follows
    Description of the illustration ics_switch_stop.png

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

    The Delete icon in the upper right corner of the page enables you to delete the designed faulting handling logic. You can also set integration tracking business identifiers on either the Global Fault Handling page or the integration canvas page.

  8. Click Save.

  9. From the hamburger menu menu in the upper right corner, select Orchestration to return to the integration canvas..

  10. Complete design of the orchestrated integration.

  11. Click Save, then click Close.

  12. 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 audit trail for an activated integration. This is only possible if there is a tracking instance.

  1. In the navigation palette, select Monitoring > 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. From the hamburger menu menu in the upper right corner, select View Global Fault.

    The fault handling logic you designed is displayed in view-only mode.

  4. Click Done.

  5. From the hamburger menu menu in the upper right corner, select View Audit Trail.

    Details about where the failure occurred and the global fault handler being triggered are displayed.
    Message processed successfully for Trigger trigger.
    Message routed through Switch Route Otherwise.
    Error processing message in Invoke invoke2
    Global fault handler triggered.
    In Global Fault Handler Message routed through Switch Route Otherwise
    In Global Fault Handler Message processed successfully for Reply trigger
    If the global fault handler successfully handled the error, the integration is displayed as COMPLETED on the Tracking 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. Create an integration that includes a scope action. See Manage a Group of Actions and Fault Handlers with a Scope Action.

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

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

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

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

    The Re-throw Fault icon is hidden.

  6. Design additional logic in the scope action.

  7. 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. On the right side of the canvas, click Actions to expand the palette or place your cursor at the appropriate place in the integration and click the + sign to invoke the inline menu.
  2. Drag the Throw New Fault icon into the integration or select it from the inline menu.
    The Create Action dialog is displayed.
  3. Enter a name and description of the action, then click OK.
    The Throw New Fault page is displayed.
  4. 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 references to files 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 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.

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

  2. Drag the Stage File icon to the plus sign where you want to perform file actions.

    The Configure Stage File Action wizard is displayed.

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

  1. From the dropdown list, select the stage file operation to perform. The page refreshes to display fields appropriate to your selection.

    • List File

    • Read Entire File

    • Read File in Segments (for chunking files)

      Note:

      If you select this operation, note the following restrictions when specifying a schema later in the Configure Stage File Action wizard:

      • 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
      • You cannot upload a ZIP file that includes multiple schemas in which one schema has a reference to the other schema file (for example, schema A imports schema B). In this case, the Read File in Segments option does not work when it reads the element that belongs to schema B.

    • Unzip File

    • Write File

    • Zip File

    Table 3-1 - 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.

    Table 3-2 - 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, /nssrcmpr:schedule/nssrcmpr:startTime).

    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.

    Table 3-3 - 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.

    Table 3-4 - 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.

    Table 3-5 - 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.

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

  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 (e.g. 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 NameSpace): Select to create a new schema from a sample XML file with a single or no namespace.

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

  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-7 - 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-8 - 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 Schema Element

    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-9 - 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-10 - 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.


    Description of stage_file_chunk.png follows
    Description of the illustration stage_file_chunk.png

    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. On the right side of the canvas, click Actions to expand the palette.

  2. Drag the Logger icon to the plus sign where you want to begin logging.

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

    The Logger page is displayed.

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

  5. 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)
  6. 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)
  7. When complete, click Close. For this example, two loggers are included in the integration.
    Description of integration_with_log.png follows
    Description of the illustration integration_with_log.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 navigation pane, click Integrations, then click the < arrow next to Designer.

  2. Click Monitoring.

  3. Click Activity Stream to view the messages.

    FILE_TRANSFER_SAMPLE - LogActivity - Thu May 25 16:03:11 PDT 2017 - The file 1KB170525160309105.zip has been uploaded to /upload 400028
    FILE_TRANSFER_SAMPLE - LogActivity - Thu May 25 16:03:07 PDT 2017 - Filename is: 1KB.zip 400028
  4. Click Download Diagnostic Logs to view the messages.

  5. Open the zip file and browser to ics_server1/ics-flow.log to 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. On the right side of the canvas, click Actions to expand the palette.

  2. Drag the Javascript icon to the Plus sign where you want to add a function.

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

    You can use the Menu icon menu to display information about the Javascript or to delete the JavaScript and return to the Actions palette.

  4. Click the +Function button.

    The Select a Function popup appears.

  5. Click a function and click the Select button in the function’s row.

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

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

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

  8. 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 audit trail for an activated integration. This is only possible if there is a tracking instance.

  1. In the navigation pane, click Integrations, then click the < arrow next to Designer.
  2. Click Monitoring, then click Tracking.
  3. Click the business identifier value of the integration to track.
  4. The integration (including any JavaScript actions) is displayed. Any JavaScript action failures are identified by red arrows.
  5. In the upper right corner, click the hamburger menu menu and select View Audit Trail.
    Details about processing status (including any JavaScript actions) are displayed, including any failures.
    Message processed successfully for Trigger FF_SOAP
    Message processed successfully for Callout callout1
    Message processed successfully for Assignment callout_return
    Processing completed successfully.

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. On the right side of the canvas, click Actions to expand the palette.
  2. Drag the Note icon to the location where you want to add a note.
    The Create Action dialog is displayed.
  3. Enter a name and description of the action, then click OK.
    The action is added to the integration.
  4. Click the Edit icon to add your notes. You can add up to 256 characters.
  5. Enter your notes, then click OK.
  6. Hover your cursor over the icon to display the note text.

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

  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.
    Description of ics_lookups_source_target2.png follows
    Description of the illustration ics_lookups_source_target2.png

  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, then click Save.
    Description of ics_lookups_source_target3.png follows
    Description of the illustration ics_lookups_source_target3.png

  16. Click Close.


    Description of ics_lookups_source_target4.png follows
    Description of the illustration ics_lookups_source_target4.png

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