Creating Integrations

Integrations use the connections you created to your applications, and define how information is shared between those applications. You can create new integrations, import integrations, modify or delete integrations, create integrations to publish messages, create integrations to subscribe to messages, and add and remove request and response enrichment triggers. Click one of the following topics for more information.

Creating an Integration

Creating an integration includes defining the trigger and invoke application connections, and defining how data is mapped between the two applications. The procedure below provides general instructions for creating an integration, with links to more detailed information for certain steps. As you perform each step, the progress indicator changes to let you know how close you are to completing the integration.

If you want to use a lookup table in your data mapping, create the lookup first. See Creating Lookups for instructions.
To create an integration:
  1. In the Oracle Integration Cloud Service home page, click Integrations.
  2. On the Integrations page, click Create.
    The Create Integration - Select a Style/Pattern dialog is displayed.
  3. Select the type of integration pattern applicable to your business needs. See Understanding Integration Patterns.
    The Create New Integration dialog is displayed.
  4. Enter the following information:
    Field Description

    What triggers this integration?

    Note: This field is only displayed if you selected Orchestration on the Create Integration - Select a Style/Pattern dialog.

    • Application event or business object: This integration uses an event or a business object to trigger the integration. For example, you create an integration with an Oracle RightNow Adapter as a trigger and an Oracle Sales Cloud Adapter as an invoke. The Oracle RightNow Adapter subscribes to an event from the Oracle RightNow application to trigger the integration.

    • Schedule: This integration uses a schedule to trigger the integration instead of an adapter. For example, you add an initial invoke adapter to read a trigger file and a second FTP adapter to download the file for further processing. After designing this integration, you schedule when to run it. See Scheduling Integration Runs.

    What do you want to call your integration?

    Provide a meaningful name so that others can understand the integration. You can include English alphabetic characters, numbers, underscores, and dashes in the identifier.

    Identifier

    Accept the default identifier value. The identifier is the same as the integration name you provided, but in upper case.

    Version

    Accept the default version number of 01.00.0000. Or, if you want to change the version number, enter the version using numbers only in this format: xx.xx.xxxx.

    Integrations are uniquely identified by an identifier and version. Note the version format of xx.yy.zzzz, where xx is the major version and yy.zzzz is the minor version.

    Integrations having the same identifier, but a different major version, can be active at the same time. For example, INT-A/1.00.0000 and INT-A/2.00.0000 can be active at the same time.

    When activating an integration while another integration of the same identifier and same major version is already active, the currently activated integration is deactivated prior to activating the selected integration.

    For example, if two integrations have the following integration states:
    • INT-A/2.00.0000 - Not active

    • INT-A/2.10.0000 - Not active

    Integration INT-A/2.00.0000 is then activated.
    • INT-A/2.00.0000 is now active.

    • INT-A/2.10.0000 is not active.

    Integration 2.10.0000 is then activated.
    • INT-A/2.00.0000 is now not active.

    • INT-A/2.10.0000 is now active.

    What does this integration do?

    Provide a meaningful description so that others can understand the integration.

    Which package does this integration belong to?

    Enter a new or existing package name in which to place your integration. As you enter the initial letters of an existing package, it is displayed for selection. See Managing Packages and About Oracle Integration Cloud Service Packages.

  5. Click Create.
    The integration designer is displayed with the type of integration pattern you selected in the previous step.
  6. If creating an integration pattern with blank trigger and invoke connections in which to add your own adapters:
    1. Create the trigger connection, as described in Adding a Source Connection.
    2. Create the invoke connection, as described in Adding a Target Connection.
    3. Map data between the two connections, as described in Mapping Data of Using the Oracle Mapper.
  7. If creating an integration in which to publish to Oracle Integration Cloud Service:
    1. Create an integration in which you add a trigger adapter to publish messages to Oracle Integration Cloud Service through a predefined Oracle Integration Cloud Service Messaging invoke, as described in Creating an Integration to Publish Messages to Oracle Integration Cloud Service. No data mapping between the trigger and invoke is permitted.
  8. If creating an integration in which to subscribe to Oracle Integration Cloud Service:
    1. Create an integration in which you add an invoke adapter to subscribe to messages from Oracle Integration Cloud Service through an Oracle Integration Cloud Service Messaging trigger, as described in Creating an Integration to Subscribe to Oracle Integration Cloud Service.
    2. Map data between the invoke adapter and the Oracle Integration Cloud ServiceMessaging trigger to which to subscribe, as described in Mapping Data of Using the Oracle Mapper.
  9. When complete, click Save and then click Close.
You now see your new integration in the Integrations list ready to be activated. See Activating an Integration for instructions.

Understanding Integration Patterns

You can select from several types of patterns when creating an integration in the Create Integration - Select a Style/Pattern dialog.

Pattern Description

Orchestration

Create a synchronous, asynchronous, or fire-and-forget orchestrated integration in Oracle Integration Cloud Service that uses Oracle BPEL Process Manager capabilities. Orchestration integration features include the following:

  • Switch activities to create multiple routing expressions.

  • For-each activities for looping over repeating elements.

  • Assign activities for assigning values to scalar variables.

  • Ad-hoc mappings on switch branches.

  • Callback activities (to end a process and respond back to the sender) and end activities (to end a process without responding back to the sender) in asynchronous integrations.

  • Schedule-based integrations

See Creating Orchestrated Integrations.

Map Data

Create an integration with a blank trigger and invoke in which to add your own adapters. You can also create a single routing expression and request and response enrichments, as needed. You cannot create multiple routing expressions. If your integration requires this feature, create an orchestrated integration.

Publish to ICS

Create an integration in which you add a trigger adapter to publish messages to Oracle Integration Cloud Service through a predefined Oracle Integration Cloud Service Messaging invoke. No configuration of the invoke subscriber is required.

The publisher and subscribers participating in this integration pattern can be activated and deactivated independently of each other.

See Creating an Integration to Publish Messages to Oracle Integration Cloud Service.

Subscribe to ICS

Create an integration in which you add an invoke adapter to subscribe to messages from Oracle Integration Cloud Service through an Oracle Integration Cloud Service Messaging trigger. You are prompted to select the publisher to which to subscribe. You must have already created a publisher to which to subscribe. The publisher does not need to be active, but must already be completely configured.

Any business identifiers defined on fields in the published integration are copied to the subscriber. Any changes made to the published integration’s business identifiers after copying are not reflected in the subscriber. The publisher and subscribers participating in this integration pattern can be activated and deactivated independently of each other.

See Creating an Integration to Subscribe to Oracle Integration Cloud Service.

See Oracle Integration Cloud Service Messaging.

Importing a Prebuilt Integration

You can import prebuilt integrations into your Oracle Integration Cloud Service environment.

There are two types of prebuilt integrations:
  • User-created integrations. These are integrations that you or another user created.

  • Oracle-created integrations from the Oracle Marketplace. You import integrations from the Oracle Marketplace as part of a package. These integrations are designated with a BUILT BY ORACLE message that is displayed next to the integration name on the Integrations page. You cannot edit these integrations, but you can view their contents, including mappings and business identifiers. You must edit the connections in these integrations to include endpoint credentials relevant to your business requirements. You can also clone these integrations, which enables you to edit the cloned version of the integration.

Importing a User-Created Integration

To import a user-created integration:

  1. In the Oracle Integration Cloud Service home page, click Integrations.

  2. In the upper right corner, click Import.

  3. Click Browse to select the file to import. If you are importing a single integration, select the JAR file to import. If you are importing a package of integrations, select the PAR file to import.

Importing a Prebuilt Integration from Oracle Marketplace

To import a prebuilt integration from Oracle Marketplace.
  1. In the upper right corner of the page, click the Oracle Marketplace icon.

  2. The Oracle Marketplace is displayed.

  3. Click Applications.

  4. Browse through the list of applications and select the prebuilt integration package to import.

  5. When prompted, select the server to which to upload the prebuilt integration file.

    The prebuilt integration is imported as a package file that is visible on the Packages page in Oracle Integration Cloud Service. If you go to the Integrations page, the individual integrations of that imported package file are designated with a BUILT BY ORACLE message to the right of the integration name.

You can customize the mappings in the prebuilt integrations imported from Oracle Marketplace. See Adding Customized Mappings to Prebuilt Integrations.

Adding a Trigger (Source) Connection

The trigger (source) connection sends requests to Oracle Integration Cloud Service. The information required to connect to the application is already defined in the connection. However, you still must specify certain information, such as the business object and operation to use for the request and how to process the incoming data.

To add a trigger connection:
  1. In the Integration Designer, drag a connection from the Connections or Technologies panel on the right to the Trigger (source) area on the canvas.
    Description of ics_canvas.png follows
    Description of the illustration ics_canvas.png
    The Adapter Endpoint Configuration Wizard for the selected connection is displayed.
  2. See the following guides for instructions:
    Adapter For Information

    DB2 Adapter

    Using the DB2 Adapter
    File Adapter Using the File Adapter
    FTP Adapter Using the FTP Adapter
    Oracle JD Edwards EnterpriseOne Adapter Using the JD Edwards EnterpriseOne Adapter
    MySQL Adapter Using the MySQL Adapter
    Oracle Advanced Queuing (AQ) Adapter Using the Oracle Advanced Queuing (AQ) Adapter
    Oracle Commerce Cloud Adapter Using the Oracle Commerce Cloud Adapter
    Oracle CPQ Cloud Adapter Using the Oracle CPQ Adapter
    Oracle Database Adapter Using the Oracle Database Adapter
    Oracle E-Business Suite Adapter Using Oracle E-Business Suite Adapter
    Oracle Eloqua Cloud Adapter Using the Oracle Eloqua Cloud Adapter
    Oracle ERP Cloud Adapter Using the Oracle ERP Cloud Adapter
    Oracle HCM Cloud Adapter Using the Oracle HCM Cloud Adapter
    Oracle Logistics Adapter Oracle Logistics Cloud Adapter
    Oracle Messaging Cloud Service Adapter Using the Oracle Messaging Cloud Service Adapter
    Oracle RightNow Cloud Adapter Using the Oracle RightNow Cloud Adapter
    Oracle Sales Cloud Adapter Using the Oracle Sales Cloud Adapter
    Oracle Siebel Adapter Using the Oracle Siebel Adapter
    Oracle Utilities Adapter Using the Oracle Utilities Adapter
    REST Adapter Using the REST Adapter
    Salesforce Adapter Using the Salesforce Adapter
    SAP Adapter Using the SAP Adapter
    ServiceNow Adapter Using the ServiceNow Adapter
    Oracle SOAP Adapter Using the SOAP Adapter

Adding an Invoke (Target) Connection

Oracle Integration Cloud Service sends requests or information to the invoke (target) connection. The information required to connect to the application is already defined in the connection. However, you still must specify certain information, such as the business object and operation to use for the request and how to process the data.

To add an invoke (target) connection:
  1. In the Integration Designer, drag a connection from the Connections or Technologies panel on the right to the Invoke (target) area on the canvas.
    Description of ics_target_canvas.png follows
    Description of the illustration ics_target_canvas.png
    The Adapter Endpoint Configuration Wizard for the selected connection is displayed.
  2. See the following guides for instructions:
    Adapter For Information
    Adobe eSign Adapter Using the Adobe eSign Adapter
    Concur Adapter Using the Concur Adapter

    DB2 Adapter

    Using the DB2 Adapter
    DocuSign Adapter Using the DocuSign Adapter
    Eventbrite Adapter Using the Eventbrite Adapter
    Evernote Adapter Using the Evernote Adapter
    Facebook Adapter Using the Facebook Adapter
    File Adapter Using the File Adapter
    FTP Adapter Using the FTP Adapter
    Gmail Adapter Using the Concur Adapter
    Google Calendar Adapter Using the Google Calendar Adapter
    Google Task Adapter Using the Google Task Adapter
    JMS Adapter Using the JMS Adapter
    LinkedIn Adapter Using the LinkedIn Adapter
    MailChimp Adapter Using the MailChimp Adapter
    Microsoft Calendar Adapter Using the Microsoft Calendar Adapter
    Microsoft Contact Adapter Using the Microsoft Contact Adapter
    Microsoft Email Adapter Using the Microsoft Email Adapter
    Microsoft SQL Server Adapter Using the Microsoft SQL Server Adapter
    MySQL Adapter Using the MySQL Adapter
    Oracle Commerce Cloud Adapter Using the Oracle Commerce Cloud Adapter
    Oracle CPQ Cloud Adapter Using the Oracle CPQ Adapter
    Oracle Database Adapter Using the Oracle Database Adapter
    Oracle Eloqua Cloud Adapter Using the Oracle Eloqua Cloud Adapter
    Oracle E-Business Suite Adapter Using Oracle E-Business Suite Adapter
    Oracle ERP Cloud Adapter Using the Oracle ERP Cloud Adapter
    Oracle Field Service Adapter Using the Oracle Field Service Cloud Adapter
    Oracle HCM Cloud Adapter Using the Oracle HCM Cloud Adapter
    Oracle JD Edwards EnterpriseOne Adapter Using the JD Edwards EnterpriseOne Adapter
    Oracle Logistics Adapter Using the Oracle Logistics Cloud Adapter
    Oracle Messaging Cloud Service Adapter Using the Oracle Messaging Cloud Service Adapter
    Oracle NetSuite Adapter Using the Oracle NetSuite Adapter
    Oracle Responsys Adapter Using the Oracle Responsys Adapter
    Oracle RightNow Cloud Adapter Using the Oracle RightNow Cloud Adapter
    Oracle Sales Cloud Adapter Using the Oracle Sales Cloud Adapter
    Oracle Siebel Adapter Using the Oracle Siebel Adapter
    Oracle Utilities Adapter Using the Oracle Utilities Adapter
    REST Adapter Using the REST Adapter
    Salesforce Adapter Using the Salesforce Adapter
    SAP Adapter Using the SAP Adapter
    SAP Ariba Adapter Using the SAP Ariba Adapter
    ServiceNow Adapter Using the ServiceNow Adapter
    Oracle SOAP Adapter Using the SOAP Adapter
    SuccessFactors Adapter Using the SuccessFactors Adapter
    SurveyMonkey Adapter Using the SurveyMonkey Adapter
    Trello Adapter Using the Trello Adapter
    Twilio Adapter Using the Twilio Adapter
    Twitter Adapter Using the Twitter Adapter
  3. After you configure the connection, the Summary page appears.
  4. Click Done, then click Save.
The connection information appears on the canvas, along with arrows depicting the configured operations. Because of space limitations on the canvas, names of connections that are more than 15 characters are truncated and ellipses are added. If you hover over a name, the complete name is displayed in a tool tip.
Description of ics_integ_canvas.png follows
Description of the illustration ics_integ_canvas.png

Creating Orchestrated Integrations

You can create orchestrated integrations in Oracle Integration Cloud Service that 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 your integration, you can add switch activities in your integration to create multiple routing expressions. You can create ad-hoc mappings on switch branches. You can also add callback activities (to end an integration and respond back to the sender) and end activities (to end an integration without responding back to the sender) in asynchronous integrations.

Creating 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. On the Oracle Integration Cloud Service home page, click Integrations.

  2. On the Integrations page, click Create.

    The Create Integration — Select a Style/Pattern dialog is displayed.

  3. Select the Orchestration integration pattern.

    The Create New Integration dialog is displayed.

  4. Select how you want to trigger the integration. See Understanding Integration Patterns for details.
    • Application event or business object

    • Schedule

    For this example, Application event or business object is selected. See Scheduling Integration Runs for details about creating scheduled integrations.

  5. Complete the fields in this dialog, and click Create.

    An empty integration canvas with the following sections is displayed:
    • The Triggers section in the upper right corner is automatically open to display the available adapters (for example, Oracle RightNow Adapter). Click an adapter to display the number of configured adapters 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 drag the trigger to define the inbound part of the integration.


      Description of ics_orchest_start.png follows
      Description of the illustration ics_orchest_start.png
    • Several icons are provided in the upper left corner of the integration for working with 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, and wait actions. You cannot reposition scope actions; stop, return, or error hospital elements; and repeat elements such as for-each, while, switch, and stage file 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. Any validation errors or warnings caused by the move are displayed in the Errors palette and on the individual actions or invokes. The Errors palette displays the element name and error/warning count. Hover your cursor or click the high level error warning in the palette. Click Reposition again to return to edit mode to resolve any errors.

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

Defining Inbound Triggers and Outbound Invokes

To define inbound triggers and outbound invokes:

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

  2. Click the adapter type to display the specific type and number of configured adapters. Synchronous, asynchronous, and fire-and-forget (no response) triggers are supported.

  3. Drag the configured adapter to the large + section within the circle in the integration canvas.

    This invokes the Adapter Endpoint Configuration Wizard.

  4. Complete the pages of the wizard to configure the selected adapter. For this example, an Oracle RightNow adapter is selected in which a request opportunity business object and an immediate response are configured.

    When complete, a configured trigger is displayed in the canvas. An unconfigured mapper icon is displayed in the middle. Because this trigger was configured to send a response, a return icon is displayed in green in the integration canvas. Green indicates that design is complete.
    Description of ics_orchest_add_trig.png follows
    Description of the illustration ics_orchest_add_trig.png

    Note:

    Asynchronous responses are also supported. You can select the Delayed (asynchronous) option on the Response page in the Adapter Endpoint Configuration Wizard for the Oracle RightNow Cloud Adapter. Creating an asynchronous response creates a return (Receive) activity in the integration. On the right side, the Triggers section is replaced by an Invokes section that enables you to add multiple outbound invoke connections to the integration.

    An Actions section is now displayed below Invokes. When expanded, this section displays the following options:
    • Assign: Enables you to assign variables to integrations.

    • Function Call: Enables you to add JavaScript functions to the integration.

    • Logger: Enables you to add log messages to the activity stream and diagnostic logs.

    • Map: Enables you to add ad-hoc mappers to the integration.

    • Notification: Enables you to send a notification email to relevant users at specific points in the execution of an integration.

    • Scope: Enables you to manage a collection of child actions and invokes that can have their own fault handlers.

    • Stage File: Enables you to process files in scheduled integrations.

    • Switch: Enables you to add a switch activity for defining routing expression branches in the integration.

    • For Each: Enables you to loop over a repeating element and execute one or more actions within the scope of the for-each action.

    • While: Enables you to loop over actions or invoke connections as long as a specific condition is met.

    • Raise Error: Enables you to send failed messages to the error hospital for further analysis.

    • Fault Return: Enables you to return a fault.
    • Callback: Enables you to end a process and return to the trigger. For example, you can add a switch activity and define a branch in which you add a Callback. If some defined expression logic is not met, this branch is taken. The integration is stopped and the trigger receives a response indicating that the integration is not continuing.

    • Return: Enables you to return an immediate response.

    • Stop: Enables you to terminate the integration. No response message is returned to the trigger.

    • Wait: Enables you to delay the execution of an integration for a specified period of time.

  5. On the right side of the canvas, click Invokes to expand the panel.

  6. Click the adapter type to display the specific type and number of configured adapters.

  7. Drag the specific configured adapter to the integration canvas. As you do, two large + sections within circles are displayed:

    • A section before the request mapper (this is similar to the enrichment feature that you can define in integrations that are not orchestrated).

    • A section after the request mapper.

  8. Drop the adapter in the appropriate section. For this example, the invoke is added before the request mapper.

    This invokes the Adapter Endpoint Configuration Wizard.

  9. Complete the pages of the wizard to configure the selected adapter. For this example, an Oracle Sales Cloud Adapter named Order with a selected business object is defined for a synchronous response.

    When complete, a configured invoke connection is displayed in the canvas.

    You can click the trigger and invoke connections to edit or view their contents. If you re-edit the selected connection in the Adapter Endpoint Configuration wizard and click Done (even without making any changes) you are prompted to update the configuration and regenerate the artifacts.

    • If you select Yes after making only minor changes, the system validates the flow and displays the warnings and errors (if there are any ) so you can fix any potential problems.

    • If you select Yes after making major changes to the trigger connection (for example, changing the message exchange pattern of the trigger from synchronous to asynchronous), all mappings, replies, and stop elements are deleted from the orchestration except for the system-generated reply or stop at the end of the integration. Tracking information is also deleted.

      Editing an invoke connection can also result in major change. However, the impact is minimal compared to editing a trigger. Invoke editing does not have flow-wide consequences such as with maps and other nodes being removed.

    You can place your cursor anywhere in the canvas to move the integration as needed. You can also move the integration from within the large box in the upper right corner.

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

Importing 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 Cloud Service 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 Cloud Service. You do not import the entire integration in which the map file is included into Oracle Integration Cloud Service.

Adding Actions to an Orchestrated Integration

You can add actions to your integrations.

Looping 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

  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

    Note:

    If you drag a for-each action into a scheduled integration or the for-each action is not inside a while action, for-each action, scope action, and so on, an additional field called Process items in parallel is visible at the bottom of the dialog. When selected, iterations of the for-each action are run in parallel. For example, if an integration processes a list of files with a for-each loop created over every file, the processing of the entire file is done in parallel for every file. If a variable is declared outside a for-each loop with Process items in parallel selected and updated within the for-each loop, the last updated value for that variable is available outside of the loop. Also, the degree of parallelism (DOP) is set to 1 to avoid concurrency issues.
  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.

Routing 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

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

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 Catching Faults with a Raise Error 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.

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 Tracking Business Identifiers in Integrations During Runtime for additional details.
Assigning Values to Scalar Variables in an Assign Action

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

Note:

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

Looping 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

  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, select Monitoring > 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. 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
Sending 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.
  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.
Delaying 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 to wait before executing the integration. Enter a positive integer value, including zero. The maximum value is six hours. This is a required field.

    • Number of minutes to wait before executing the integration. Enter a positive integer value between 0 and 59. The hours and minutes values you enter cannot both be zero. This is a required field.

      The wait action is added to the integration canvas.
      Description of wait_activity.png follows
      Description of the illustration wait_activity.png

  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.
Adding 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
    The Expression

    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.
Catching Faults with a Raise Error Action

You can send failed messages to the error hospital for further analysis with a raise error action. If the integration contains a defined global fault, the error captured by the raise error 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 raise error action can only be placed inside the fault handler section of a scope action or at the end of a switch action’s condition branch. The raise error action operates as a catch all block and is processed if a fault is thrown by an invoke action in the scope. However, the raise error action does not have a specific catch named for it. The following example describes how to define a raise error action in a scope action.

To catch faults with a raise error action:

  1. Create an integration that includes a scope action. See Managing 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 Raise Error 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 Raise Error icon is hidden.

  6. Design additional logic in the scope action.

  7. To return to the Raise Error 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
Processing Files in Scheduled Integrations with a Stage File Action

You can use the stage file action to process 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 Cloud Service. 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.

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

    Table 2-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 2-2 - Read Entire File

    Property Description
    Specify the File Name

    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 1 MB. For files greater than 1 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 2-3 - Read File in Segments

    Property Description
    Specify the File Name

    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

    Specify a file chunking size between 10 and 200 MB.

    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.

    Remove Trailer

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

    Table 2-4 - Unzip File

    Property Description
    Specify the Zip File Name

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

  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 define a schema for this endpoint?

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

    Do you want to create a new schema or use an existing one?
    Select an option:
    • Create a new schema from a CSV file: Select to create a new schema file 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.

    • Select an existing schema from the file system: Select an existing schema file. On a subsequent page of this wizard, you are prompted to select the existing schema (XSD) file from the file system.

  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 create a new schema from a comman-separated value (CSV) file or select an existing 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.

    • Create a New Schema from a CSV File (Table 2-7)

    • Select an Existing Schema from the File System (Table 2-8)

    Table 2-7 - Create a New Schema from a CSV File

    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 2-8 - Select an Existing Schema from the File System

    Element Description
    • Select a New File

    Select the existing schema file to use. This field appears if you selected an existing schema 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 schema 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 assigned within the loop of a stage file action that was configured with the Read File in Segments stage file operation (for chunking files), the updated values for that variable are available outside of the loop.
  • 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).

Logging 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 Activating 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, select Monitoring.

  2. 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
  3. Click Download Diagnostic Logs to view the messages.

  4. Open the zip file and browser to ics_server1/ics-flow.log to view the log messages you created.

Adding a Function Call Action

You can add JavaScript functions to the integration.

Creating a Function Call Action

To create a function call action:

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

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

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

    You can use the Menu icon menu to display information about the function call or to delete the function call 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 Function Call Action During Runtime

During runtime, you can track the status of the function call 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.
  3. The integration (including any function call actions) is displayed. Any function call 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 function call 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.

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

Using 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 Cloud Service. See Creating 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

Defining Fault Aggregation in Parallel Processing Scenarios

Oracle Integration Cloud Service 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.

Assigning 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 Assigning 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 Activating an Integration.

  5. Manage and monitor your integration. See Monitoring Integrations and Tracking Business Identifiers in Integrations During Runtime.

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

Creating an Integration to Publish Messages to Oracle Integration Cloud Service

You can create integrations that enable you to publish messages to Oracle Integration Cloud Service. Message publishing is accomplished through use of Oracle Integration Cloud Service Messaging.

To create an integration to publish messages to Oracle Integration Cloud Service:

Note:

Oracle Integration Cloud Service Messaging supports messages of up to 10 MB in size.
  1. Select Publish To ICS in the Create Integration - Select a Style/Pattern dialog, as described in Creating an Integration.
  2. Complete the fields of the Create New Integration dialog, as described in Creating an Integration.
    This creates an integration pattern with a predefined Oracle Integration Cloud Service Messaging invoke connection that enables you to publish messages to Oracle Integration Cloud Service.
  3. In the integration designer, drag an adapter from the Connections panel on the right to the trigger (source) area of the canvas. For this example, an Oracle Sales Cloud Adapter is selected.
    The Adapter Endpoint Configuration Wizard is displayed.
  4. On the Basic Info page, enter an endpoint name and optional identifier for this connection.
  5. Click Next.
  6. On the Request page, select a business object (for this example, Account is selected), then click Next.
  7. On the Response page, select None as the response type, then click Next.
  8. On the Summary page, click Done.
    The Oracle Sales Cloud Adapter is configured to publish messages to Oracle Integration Cloud Service through use of Oracle Integration Cloud Service Messaging. Note that there is no request mapper available with this type of integration pattern.

  9. Click Save, then click Close.
    To subscribe to the message configured in this section, you must now configure Oracle Integration Cloud Service to act as a publisher. This enables Oracle Integration Cloud Service to publish the messages to which other adapters can then subscribe. See Creating an Integration to Subscribe to Oracle Integration Cloud Service.

Creating an Integration to Subscribe to Oracle Integration Cloud Service

You can create integrations that enable you to subscribe to messages from Oracle Integration Cloud Service. Message subscription is accomplished through use of Oracle Integration Cloud Service Messaging.

To create an integration to subscribe to Oracle Integration Cloud Service:
  1. Complete the steps in section Creating an Integration to Publish Messages to Oracle Integration Cloud Service to first configure Oracle Integration Cloud Service as a subscriber to messages from an adapter.
  2. Select Subscribe To ICS in the Create Integration - Select a Style/Pattern dialog, as described in Creating an Integration.
  3. Complete the fields of the Create New Integration dialog, as described in Creating an Integration. This creates an integration pattern with Oracle Integration Cloud Service Messaging that enables you to subscribe to messages from Oracle Integration Cloud Service.
    The Select a Publisher dialog is displayed.
  4. Select the integration to which to subscribe, then click Use. For an integration to be displayed for selection, you must first configure Oracle Integration Cloud Service as a subscriber, as described in Creating an Integration to Publish Messages to Oracle Integration Cloud Service. Only integrations that are 100% completed and unlocked are displayed. Integrations that are locked (meaning that they are being edited) are not displayed.

  5. Drag an adapter to the invoke (target) area of the integration designer. For this example, an Oracle RightNow Cloud Adapter is added.
  6. On the Basic Info page, enter a name and optional identifier for this connection.
  7. Click Next.
  8. On the Operations page, select an appropriate operation and business object, then click Next. For this example, a CRUD Create operation and Organization business object are selected.

  9. On the Summary page, review your changes, then click Done.
    The request mapper is available with this type of integration pattern.
  10. Click the Request Mapping icon, then click Create.
  11. Map source fields to the corresponding target fields. See Mapping Data of Using the Oracle Mapper.
  12. When complete, click Close, then click Apply to save your changes.
    The Oracle RightNow Cloud Adapter is configured to subscribe to messages from Oracle Integration Cloud Service through use of Oracle Integration Cloud Service Messaging.

  13. Click Save, then click Close.
  14. Activate the publishing integration described in Creating an Integration to Publish Messages to Oracle Integration Cloud Service and the subscribing integration described in this section. See Activating an Integration.
    The completed publishing and subscription integrations enable you to:
    • Create an object in one application that causes the object to be created in other applications.

    • Enable multiple applications to subscribe to Oracle Integration Cloud Service and be registered for updates.

    • Enable additional subscribers to be added or removed without impacting other subscribers or publishers.

Business identifier tracking data is copied when a subscriber is created. If a publishing integration is updated later, you must update the subscribing integration.

For example, assume you create a publishing integration, then create a subscribing integration and select to subscribe to the publishing integration. Select the Tracking icon, and note that the tracking attributes of the selected publishing integration are displayed. Assume you then edit the publishing integration and change the operation of the trigger adapter (as an example), save, and exit the canvas. If you then edit the subscribing integration and click the Tracking icon, note that the business identifier tracking attributes of the publishing integration that are displayed are those that existed before the updates were made. The tracking fields are not updated as per the updated publisher integration. This is the expected behavior.

Adding Request and Response Enrichments

When you create an integration, you also have the option of adding both request and response message enrichment points to the overall integration flow. Enrichments participate in the overall integration flow and can be used in the request and/or response payloads between the trigger and invoke.

To add request and response enrichments:
  1. Design an integration with trigger and invoke connections and request and response mappings. For this example, the integration looks as follows when complete. Note the two enrichment point circles in the design; one appears on the inbound (request) side and the other appears on the outbound (response) side.

    The request and response mappings for this example are as follows:
    Mapping Source Target
    Request HelloRequest/FirstName sayHello/name
    Response sayHelloResponse/sayHelloReturn HelloResponse/Greeting
    You are now ready to add enrichments to the integration. For this example, a response message enrichment is added to the Drag and drop an enrichment source for the response message area. You can also add request message enrichments on the request (inbound) side.

  2. From the Connections panel on the right, drag an adapter to the enrichment area on the response message shown below.
    For this example, a SOAP Adapter is dragged to the Drag and drop an enrichment source for the response message area. This action invokes the wizard for configuring the SOAP Adapter.

  3. Complete the pages of the wizard to configure the SOAP Adapter, then click Done. For this configuration, a different operation for selecting timestamp details is chosen.
    You are prompted with a dialog to delete any impacted response mappings that you previously configured for the response mapper. The response mapper requires updates because of the enrichment response adapter configuration you just performed.
  4. Click Yes. You recreate the response mappings later in these steps.
  5. Click Save.
    A SOAP Adapter icon and response enrichment mapper are added to the response side of the integration. Note that because you deleted the response mappings in the previous step, that icon is no longer shaded in green. This indicates that the response mapper requires configuration.
  6. Click the Response Enrichment Mapping icon between the trigger and invoke.
  7. Click the Create icon that is displayed. This invokes the mapper.

  8. Map source elements to target elements to include a timestamp with the response, then click Save when complete.
    The response enrichment mappings are as follows:
    Mapping Source Target
    Response Enrichment sayHelloResponse/sayHelloReturn visitTimestampReq > reqMsg
    The Response Mapping icon is displayed in green, indicating that it has been configured.
  9. Click the Response Mapping icon to invoke the mapper again. This mapper requires updates because of the enrichment response mapping you performed.

  10. Remap the source elements to target elements in the response mapper.
    The response mappings are updated. Note that a different source is now mapped to the original target of HelloResponse/Greeting.
    Mapping Source Target
    Response $ResponseEnrichmentApplicationObject > visitTimestampResp > respMsg HelloResponse/Greeting
    The Response Enrichment Mapping icon is displayed in green, indicating that it has been reconfigured.
  11. Click Close, then click Apply when complete.
    The integration with response enrichments added to the invoke (target) area looks as follows:

  12. Click Save, then click Close when complete.
    You are ready to activate the integration. While not demonstrated in this example, you can also configure the enrichment area on the request message shown below by dragging and dropping an adapter to the Drag and drop an enrichment source for the request message area. This invokes the adapter configuration wizard.

You can also update existing enrichments at a later time, such as the objects selected in the adapter configuration wizard and the enrichment mappings.

Deleting Request and Response Enrichments

You can delete the request and response message enrichment point mappings added to an integration. After deleting the enrichment point mappings, the integration is returned to its original pre-enrichment state.

To delete request and response enrichments:
  1. On the Integration page, select the integration. The integration must not be active.
  2. Click the enrichment area on the request message or response message to delete.
  3. Select the Delete icon that is displayed.
    This deletes the mappings.
  4. Click Yes when prompted to confirm.
    Click Save, then click Close.

Creating Routing Paths for Two Different Invoke Endpoints in Integrations

You can create an integration in which you define routing paths for two different invoke endpoints. During runtime, the expression filtering logic for the routing paths is evaluated and, based on the results, the path to one of the invoke endpoints is taken. If the filtering logic for neither routing path is satisfied, then neither invoke endpoint is contacted.

The expression logic works as follows:
  • You define an expression filter on the first (upper) invoke endpoint.

  • You define either an ELSE condition or an expression filter on the second (lower) invoke endpoint.

During runtime, if the expression filtering logic for the first (upper) invoke endpoint evaluates to true, then the path to that invoke endpoint is taken. If the expression evaluates to false, then that invoke endpoint is skipped, and the path to the second (lower) invoke endpoint is taken through either an ELSE condition or an expression filter.

In addition to creating routing paths, you also define request and response (and optionally, enrichment) mappings on both invoke endpoints.

To create routing paths for two different invoke endpoints in integrations:

  1. On the Integrations page, select the integration in which to define a routing filter. Ensure that the integration is fully defined with trigger and invoke connections, business identifier tracking, and mappings.
  2. Click the Filter icon on the trigger side of the integration to create a filtering expression. Routing is created after any defined request enrichment and before the initial request mapping.
    Description of routing_filter.png follows
    Description of the illustration routing_filter.png
  3. Click the Routing icon in the menu that is displayed.
    The Expression Builder is displayed for building routing expressions. The Expression Builder supports multiple source structures. You can create OR expressions using both source structures. You can also name expressions and calculate expression summaries with the Expression Summary icon. Elements and attributes with and without namespace prefixes are also supported.

    You can filter the display of source structures by clicking the Filter link. This enables you to filter on whether or not fields are used and on the type of field (required fields, custom fields, or all fields). You can also select to filter both required and custom fields together.

  4. Drag an element from the Source area to the Expression field.
  5. Define a value.
    For this example, the ClassificationCode element is defined as equal to Org. This means that Org is retrieved when this expression evaluates to true.
  6. If you want to calculate the expression, click the Expression Summary icon. This shows the summary of the expression and defines a more user-friendly, readable version of the expression you just created.
  7. If that name is not sufficiently user-friendly, copy and paste the expression to the Expression Name field for additional editing.
    Description of ics_express_bld_names.png follows
    Description of the illustration ics_express_bld_names.png
  8. Click Close to save your changes.
    The defined expression is displayed above the integration. The Filter icon has now changed to indicate that an expression is defined.
    Description of routing_expression_integ.png follows
    Description of the illustration routing_expression_integ.png
  9. On the right side of the integration, click the Routing Drawer icon to display a graphical routing diagram with two potential paths. The first route that you just defined (the upper trigger and invoke) shows the defined expression above the line. The second route (the lower trigger and invoke) is displayed as a dotted line because it is not yet defined.

    You can activate the integration now if additional filtering is not required or define an additional routing filter. For this example, a second route is defined.
  10. Click the bull’s eye icon in the lower trigger icon to define routing on the second trigger and invoke route.
    Description of routing_drawer2.png follows
    Description of the illustration routing_drawer2.png
    This refreshes the integration to display the lower trigger and invoke route in the integration. The trigger side remains as defined for the first route, but the invoke route is undefined.
  11. Click Show Palette to display the list of available connections and technologies.
  12. Drag an adapter to the invoke (target) area of the integration (for this example, an Oracle RightNow adapter is added).
    The Adapter Configuration Wizard is invoked.
  13. Configure the pages of the wizard for the Oracle RightNow adapter. For this example, the Get operation and Account business object are selected on the Operations page.
    Description of routing_target_config.png follows
    Description of the illustration routing_target_config.png
    The integration is now defined for the second invoke. You now need to create a filtering expression for the second invoke.
  14. Click the Filter icon to create a filtering expression.
  15. If no additional expression is required, click the E icon (to create an ELSE condition).
    Description of routing_filter_edit.png follows
    Description of the illustration routing_filter_edit.png
    This defines an ELSE condition for the second trigger and invoke. The ELSE condition is taken if the first route evaluates to false (that is ClassificationCode does not equal Org). You can toggle back and forth between the two trigger routes by clicking the adapter icon on the individual line. The line in blue is the currently visible invoke in the integration.
    Description of routing_logic_else.png follows
    Description of the illustration routing_logic_else.png
  16. If you want to define your own expression filter for the second route instead of using the ELSE condition, perform the following steps:
    1. Click the Filter icon.
    2. Select Clear Expression to remove the ELSE condition.
    3. Click Yes when prompted to confirm.
    4. Click the Filter icon again and select the Edit icon to invoke the Expression Builder as you did in Step 3.
    5. Define an expression.
    6. Click Close to save your changes.
      Request and response mappings must now be defined.
  17. Click the Request Mapper icon to define the mapping.
    For this example, the following mapping is defined.
    Source Target

    process > Organization > Organizationid

    Get > Account > ID > id

  18. Click the Response Mapper icon to define the mapping.
    For this example, the following mapping is defined.
    Source Target

    process > GetResponse > Account > ID > LookupName

    processResponse > Organization > Name

    Integration design in now 100% complete.

  19. Activate the integration.

Creating Routing Expression Logic in Both Expression Mode and Condition Mode

You can create XPath expressions for routing conditions in two different user interface modes:

  • Expression mode: This mode provides an interface for creating and viewing the entire XPath expression.

  • Condition mode: This mode provides an easier-to-read interface to create and view XPath condition expressions. This mode is useful for business analysts who may be less experienced with XPath expressions.

You can toggle between expression mode and condition mode when creating and viewing your expressions. Elements and attributes for which mapping is required are identified by a blue asterisk (*) to the left of their names. You can also place your cursor over elements and attributes to display specific schema details such as the data type, if mapping is required, and so on. When creating an expression, note the following functionality in the tree:
  • Three levels of elements are loaded by default in the tree in the Source area. When you reach the third level, a Load more link is displayed. Click this link to display all the direct children of that element. Only base types are loaded automatically. To load the extended types of the base type, click the base type, which is identified by a unique icon. This invokes a menu of extended types that you can select to load one by one into the tree.
    Description of ics_logic_express_base.png follows
    Description of the illustration ics_logic_express_base.png

  • Elements in the tree in the Source area that you have already dragged to an expression are identified by green checkboxes. These elements are displayed even if they are deeper than three levels in the tree.

  • You can search for an element that is not yet loaded in the tree by entering the name in the Find field and clicking the Search icon. This action loads that specific element into the tree.

This section provides an example of building an expression using both modes.

To create routing expressions in both expression mode and condition mode:

  1. Click the Filter icon on the source side of an integration to create a filtering expression.
    Description of routing_filter.png follows
    Description of the illustration routing_filter.png
  2. Click the Routing icon in the menu that is displayed.
    The Expression Builder is displayed for building routing expressions. Expression mode is the default mode.
  3. In the field immediately below Expression Name, optionally enter a short description about the expression you want to build.

  4. Add an element from the Source area on the left side to the expression field immediately below the short description field. If needed, you can also add functions from the Components section.
    There are two ways to add an element to the expression field:
    1. Drag the element from the Source area.
    2. Select the row of the element in the Source area, then click the Move icon in the middle of the page to move the element.

      The expression for the selected element is displayed in the expression field (for this example, the expression for the Country element was added). The selected element is identified by green checkbox in the Source area.

  5. To the right of the added expression, define an operator and a value within single or double quotes (for this example, = “USA” is defined).
  6. Click the Expression Summary icon to view a simplified, user-friendly version of the expression. Easy-to-read output is displayed.
    Description of ics_logic_express_bldnw.png follows
    Description of the illustration ics_logic_express_bldnw.png

    Note:

    • To add additional elements to the expression, you can place your cursor in the exact location of the expression, select the row of an element in the Source area, and click the Move icon. These actions add that element to the exact location of your cursor.

    • You can drag an element to the exact location of your cursor in the expression, and the expression of the element is added to the cursor location, and not the location in which you drop the element.

    • You can drag an element on top of an existing expression element to replace it.

  7. In the upper right corner, click Condition Mode to view the expression you created in condition mode. Condition mode provides an easy-to-read interface for creating and viewing your expressions.

    Note the following details about accessing condition mode:

    • Condition mode can only be accessed if the expression field is empty or completely defined with an expression that returns true or false. If you only partially define an expression (for example, you drag an element to the expression field, but forget to define expression logic and a value such as = “USA”), you receive an error saying that you must provide a valid condition to access condition mode.

    • The Condition Mode button toggles to Expression Mode.

    Note:

    At any time, you can click Expression Mode to view the entire XPath expression.
  8. Click the expression.

    Description of ics_logic_express_add2.png follows
    Description of the illustration ics_logic_express_add2.png

    This refreshes the page to display icons for adding additional conditions and conditions groups. Groups enable you to combine multiple conditions into a single logical expression.


    Description of ics_logic_express_build3.png follows
    Description of the illustration ics_logic_express_build3.png
  9. Click the Add Condition icon (first icon) to add additional condition expressions.
    This creates an additional field for entering additional expression logic. The message Drag and drop or type here is displayed in this field.
    Description of ics_logic_express_add_cond2.png follows
    Description of the illustration ics_logic_express_add_cond2.png
  10. Drag an element from the Source area to the first Drag and drop or type here field (for this example, the Country element is again added).
  11. Select an operator (for example, =, >,!=, and so on) and enter a value (for this example, “Mexico” is added).
  12. From the Match list, select an option. This list is hidden until at least two conditions are defined.
    • Any of: Select if any of the added expressions must be true. This equates to an OR condition in the entire XPath expression shown in expression mode.

    • All of: Select if all expressions must be true. This equates to an AND condition in the entire XPath expression shown in expression mode.



  13. Select the Add Group icon (second icon) to group a series of conditions. This option enables you to build a number of conditions within a single group. The group is identified by the gray outline and the indentation.
  14. Add an element from the Source area.
    For this example:
    • The DisplayName element is added to the first Drag and drop or type here field.

    • The not equal operator (!=) is selected.

    • The Country element is added to the second Drag and drop or type here field.

  15. Click the Add Condition icon (first icon) to add an additional condition expression within the group.
    For this example:
    • The DisplayOrder element is added to the first Drag and drop or type here field.

    • The less than operator (<) is selected.

    • A value of 10 is entered in the second Drag and drop or type here field.

  16. Continue building your group condition, as necessary.
    When complete, the expression is displayed. For this example, there are the conditions: if Country is USA OR Country is Mexico OR DisplayName does not equal country and DisplayCount is less than 10, the integration continues.
    Description of ics_logic_express_add_gr3.png follows
    Description of the illustration ics_logic_express_add_gr3.png
  17. Click Expression Mode.
    Note the entire XPath expression and the expression summary at the bottom. The selected elements are displayed (no matter their level of depth in the tree) and identified by green checkboxes in the Source area.
    Description of ics_logic_express_final2.png follows
    Description of the illustration ics_logic_express_final2.png
  18. If you want, you can place your cursor in the XPath expression and edit it as necessary (for example, change USA to Canada), then click the Expression Summary icon to refresh the calculation. If you make an error when editing the XPath expression (for example, forget to add a double quote to a value), an error message is displayed.
  19. Click Save to view the expression in read-only mode. You can also click Done Editing at any time during the creation process to view the expression in read-only mode.
  20. Click Close to return to the integration. The user-friendly expression is displayed in the blue banner above the integration.

Deleting Routing Paths

You can delete routing paths that have been created on different target endpoints in an integration.

There are two methods for deleting routing paths:
  • Delete the routing path and expression filter.

  • Delete the endpoint and routing path, but retain the expression filter.

Deleting the Routing Path and Expression Filter

To delete the routing path and expression filter:

  1. In the Integrations page, select the integration in which to delete a routing path.

  2. Expand the Routing Drawer icon to display the diagram of routing paths.

  3. Above the integration, select the routing path to delete.
    Description of routing_select_delete.png follows
    Description of the illustration routing_select_delete.png

  4. Click the Filter icon.

  5. Select Delete Route from the menu that is displayed.


    Description of routing_delete.png follows
    Description of the illustration routing_delete.png
  6. Click Yes when prompted to confirm.

    This action deletes the routing path, including the expression filter and the request mapping for the selected path. The diagram above the integration shows that the routing path is deleted.
    Description of routing_delete_complete.png follows
    Description of the illustration routing_delete_complete.png

Deleting the Endpoint and Routing Path

To delete the endpoint and routing path:

  1. In the integration, click the target endpoint to delete.

  2. Click Delete in the menu that is displayed.

  3. Click Yes when prompted to confirm.

    This action deletes the target endpoint and routing path. The diagram above the integration shows that the routing path is deleted. Within the integration, only the expression remains defined in the integration because it is not using anything from the deleted target endpoint.
    Description of routing_delete_endpt.png follows
    Description of the illustration routing_delete_endpt.png

Editing the Endpoint Information in an Integration

You can edit the endpoint information in an integration that is not active. The changes that you make can impact your mappings. For example, minor edits such as changing the endpoint description do not delete the existing mappings. Major edits such as changing the selected business objects or operations delete the mappings. In these cases, you must recreate your mappings. Before you save your updates, you are prompted to confirm your changes.

The impact of major and minor endpoint changes on an integration are as follows:
  • If a minor change is detected, for example:

    • If a map is using either the request or response of the application as a primary input, output, or secondary input, the map is validated.

    • If a map is using a fault of the application as a primary input or output, the map is deleted.

    • If a map is only using a fault of the application as a secondary input, the secondary input is removed.

  • If a major change is detected, for example:

    • If a map is using a request, response, or fault of the application as a primary input or output, the map is deleted.

    • If a map is only using a request, response, or fault of the application as a secondary input, the secondary input is removed.

The following are examples of major endpoint changes:

  • If the application message exchange pattern changes (for example, from synchronous to asynchronous).

  • If a root element name or root element namespace of the input request changes.

  • If a root element name or root element namespace of the output response changes.

If none of the above changes occur, then the change is considered minor.

  1. On the Oracle Integration Cloud Service home page, click Integrations.
  2. Select the integration to edit.
  3. In the integration, select the trigger or invoke endpoint to edit, then click the Edit icon.
  4. Make appropriate changes in the Adapter Endpoint Configuration Wizard, then click Done.
  5. Select to confirm your changes when prompted. Minor edits do not delete your mappings. Major edits delete your mappings.