Managing Integrations

When you are ready for your integration to go live, you must activate the integration in Oracle Integration Cloud Service. You can also deactivate a running activation if you must make changes to it or if it is no longer needed.

Activating an Integration

Once you create an integration and the progress indicator shows 100 percent, you can activate that integration to the runtime environment. An integration shows as 100% and is eligible for activation after you have specified the source connection, the target connection, the data mappings, and the tracking fields.

To activate an integration:

Note:

If you activate a new version of an existing integration, tracking instances or logs of the old version are not deleted. However, related artifacts are deleted and redeployment is performed on the back end. Monitoring data is also removed.
  1. On the Oracle Integration Cloud Service home page, click Integrations.
  2. In the Integrations list, locate the integration you want to activate and go to the far right end.
  3. Click the icon to activate the integration.
    Description of ics_pending_activate.png follows
    Description of the illustration ics_pending_activate.png
    The Confirmation dialog is displayed.
  4. If you want to enable detailed tracing information in the activity stream, click the Enable tracing checkbox.
    When this checkbox is selected, detailed logging information about messages processed by this integration flow at runtime is collected. This can aid in troubleshooting issues. However, detailed tracing may also impact performance. To disable tracing, you must deactivate the integration, then reactivate it without selecting the Enable tracing checkbox.
    1. If you want to enable payload tracing to log input and output payloads to the activity stream, click the Include payload checkbox.
      When this checkbox is selected, information from the payload is also written to the log files, which can be downloaded and viewed. For example, you see more detailed logging information about payload activity at several points in the integration flow, such as the payload prior to data mapping and the payload after data mapping. This action can present a security risk and also impact the performance of your system. This setting is not recommended for a production environment.
  5. Select an activation method:
    1. Click Activate.
    2. Click Activate and Schedule.
      The Run integration_name page is displayed. Create a schedule for running this integration, and click Save. See Creating an Integration Schedule.
    An activation progress bar is displayed at the top of the dialog. If activation is successful, the status of the integration changes to ACTIVE in the list. If you selected to enable tracing, the words TRACE ENABLED are displayed under the icon you clicked to activate the integration. If you selected to enable tracing with payloads, the words TRACE WITH PAYLOAD are displayed under the icon. If you click the integration instance on the Tracking page, the hamburger menu menu includes an option called View Activity Stream for viewing payload details.

    To access the detailing trace logging information:

    1. In the navigation pane, click the Monitoring tab.

    2. Click Download Diagnostic Logs to download Oracle Integration Cloud Service logs and diagnostics logs.

    Note:

    If activation fails, an error message is displayed at the top of the Integrations page. To troubleshoot the activation error, click Download diagnostic logs to download the logs for diagnosing the issue.
  6. View active integrations by clicking the integration name or selecting View from the menu at the far right of the integration. The active integration is displayed with a message saying Viewing.
Note the following details about read-only mode:
  • No Save button and Actions button are displayed.

  • There is no Connections Palette for adding adapters.

  • You can click through multiple parts of the integration to view configuration details, such viewing the business identifiers under the Tracking tab, viewing the source-to-target and target-to-source mappings in the mapper, and viewing the configurations on the pages of the connection wizards, but you cannot modify anything.

Deactivating an Integration

You can deactivate an integration to stop it from processing any new messages. If you want to modify an active integration, you need to deactivate it first.

Deactivation is equivalent to undeployment of a project, which means all existing history, monitoring, and runtime data are lost. Oracle Integration Cloud Service does not support the notion of starting and stopping projects. With asynchronous patterns, the queue for the deactivated project is deleted and all messages associated with this queue are also deleted. Therefore, if there are pending requests unprocessed, they are lost after deactivation. The previous version is deactivated and all existing history, monitoring, and runtime data is lost.
  1. On the Oracle Integration Cloud Service home page, click the Integrations diagram.
  2. On the Integrations page, find the integration you want to deactivate.
    To view only active integrations, select Active in the Integrations list. You can also filter by integration name or integration type (prebuilt, custom, or developed) to narrow down the list.
  3. In the row containing the integration you want to deactivate, click the Active icon to deactivate the integration.
  4. Click Deactivate on the dialog that appears. A deactivation progress bar is displayed at the top of the dialog.

Modifying an Integration

You can modify an existing integration, including changing a source or target connection, reconfiguring the connection, and updating the data mapping. Changes to the source or target can cause changes to the existing mappings.

If the integration you want to modify is active, deactivate it first. See Deactivating an Integration for instructions.
To modify an integration:
  1. On the Oracle Integration Cloud Service home page, click the Integrations diagram.
  2. On the Integrations page, find the integration you want to modify.
    You can search by entering a partial or complete integration name in the Search field or filter integrations by selecting an option from the Filter By list. From this list, you can filter by Type (Customized, Developed, and Prebuilt), Pattern (Schedule, File Schedule, Map Data, Notification, Publish to ICS, Subscribe To ICS, and Undefined), Status (Draft, Configured, Active, or Failed ), or Style (Template or Orchestration). Search or filter criteria are displayed in the banner above the returned list of integrations. To remove search or filter criteria, click the x icon in the banner.
  3. On the row that contains the integration you want to change, click the hamburger menu menu, and select Edit.
  4. To modify the source or target configuration, click the connection on the canvas and click Edit on the menu that is displayed.
  5. Modify any of the open fields in the wizard that appears. See Connection Configuration Reference for instructions.
  6. To assign a new connection as the source or target, click the connection to delete, then click Delete on the menu that is displayed.
  7. From the right side, drag the new adapter from the panel to the connection on the canvas that you want to replace. Configure the new connection. See Connection Configuration Reference for instructions.
  8. To modify a data mapping, click the appropriate map icon and update the mappings. See Mapping Data of Using the Oracle Mapper.
  9. When you are done making changes, click Save and then click Close.

Note:

If you have an integration that is locked and stuck in Draft mode, wait for the lock to expire. Expiration typically occurs within 30 minutes. This situation can occur if your browser crashes while editing an integration.

Viewing the Trigger, Invoke, and Enrichment Details of an Integration

You can view the details associated with trigger, invoke, and enrichment endpoints of an integration.

To view the trigger, invoke, and enrichment details of an integration:
  1. On the Oracle Integration Cloud Service home page, click the Integrations diagram.
  2. On the Integrations page, find the integration you want to view. You can filter the display of integrations by their current status on the left side of the page.
  3. Click the trigger, invoke, or (if configured) enrichment endpoint of the integration.
  4. Click the View icon.
  5. View the connection name, endpoint name, input payload, and output payload of the integration.

Cloning an Integration

Cloning an integration creates a new copy with identical connections and data mappings. You give the clone a new name, identifier, version number, and package name, but the remaining configuration is the same. You can reconfigure the clone after you create it. You can also clone a locked integration.

Note:

Integration versions follow a formatting convention of xx.yy.zzzz, where xx is the major version and yy.zzzz is the minor version. If you clone an integration (for example, version 1.00.0000) and change the minor version of the cloned integration to 1.10.0000, version 1.00.0000 is deactivated when you activate version to 1.10.0000. To keep both integrations active, change the major version of the cloned integration to 2.00.0000. This enables integration versions 1.00.0000 and 2.00.0000 to be active at the same time. See Creating an Integration.
To clone an integration:
  1. On the Oracle Integration Cloud Service home page, click the Integration diagram.
  2. On the Integrations page, find the integration you want to clone. You can filter the display of integrations by their current status on the left side of the page.
  3. In the row containing the integration you want to clone, click the hamburger menu icon on the far right, then click Clone.
  4. In the dialog that appears, enter a name, unique identifier, version number, package name, and an optional description.
    You can include English alphabetic characters, numbers, underscores, and dashes in the identifier. Enter the version using numbers only in this format: xx.xx.xxxx.
  5. Click Clone.
  6. You can modify the clone in any of the ways described in Modifying an Integration.

Creating a Draft of an Integration

Creating a draft of an integration creates a new copy with the same integration information. This action represents an easier way to create an integration. During draft creation, you must update the version of the integration and optionally update the package and description. However, unlike a cloned integration, you cannot update the integration name or identifier. You can also create a draft of a locked integration.

To create a draft of an integration:
  1. On the Oracle Integration Cloud Service home page, click the Integrations diagram.
  2. On the Integrations page, find the integration for which you want to create a draft. You can filter the display of integrations by their current status on the right side of the page.
  3. In the row containing the integration for which you want to create a draft, click the hamburger menu menu, and select Create Version.
  4. In the dialog that appears, modify the version number. Not modifying this field results in the following error:
    The version of Integration "integration_name" you are trying to create already exists in the system.
  5. Optionally modify the package name and description. You cannot modify the integration name or identifier.
  6. Click Create Version.

Deleting an Integration

You can delete an integration that is no longer needed.

Make sure the integration you want to delete is not active. To deactivate the integration, see Deactivating an Integration.
To delete an integration:
  1. On the Oracle Integration Cloud Service home page, click Integrations.
  2. On the Integrations page, find the integration you want to delete. You can filter the display of integrations by their current status on the left side of the page.
  3. In the row containing the integration you want to delete, click the hamburger menu menu on the far right, then click Delete.
  4. Click Yes on the dialog that appears.

Unlocking an Integration

When an integration is in edit mode and the browser crashes, the integration becomes locked, which prevents it from being edited. There are several ways to unlock the integration.

To unlock the integration:

  1. Log in as a user with the Administrators role.

  2. On the Oracle Integration Cloud Service home page, click the Integrations diagram.

  3. For the integration that is locked, click the hamburger menu menu at the far right, then select Unlock.

Canceling an Integration That Does Not Complete

If an integration is not completing as expected, there may be several causes and steps you can take to cancel the integration. This may occur for a variety of reasons. For example, a looping action (for example, a while action) does not complete or agent connections or cloud adapter connections do not complete.

To cancel an integration, perform one of the following steps:

  • Deactivate the integration.

  • Change the user credentials to cause integration connectivity to fail. If the integration still does not stop, raise a service request for Oracle Support Services to physically delete the integration instance.

Downloading Generated Artifacts for an Integration

You can download artifacts of an integration as a zip file for viewing and analysis. You can download completed integrations, locked integrations, and active integrations, but not integrations that are in a draft state. The artifacts of active integrations are regenerated when downloaded. However, this action does not fetch the previously deployed artifacts from runtime. Instead, it regenerates and provides artifacts for download only (has no impact on the deployed artifacts). Therefore, these artifacts may not be fully identical with the previously deployed artifacts.

Downloading artifacts differs from exporting an integration. Exporting creates an IAR file that consists of the design time metadata of the integration. The generated artifacts downloaded are the same JAR files that are deployed to runtime through the activation process. Therefore, they are generated from the design time metadata and also contain the runtime metadata.

To download generated artifacts for an integration:

  1. On the Oracle Integration Cloud Service home page, click the Integrations diagram.
  2. On the Integrations page, find the integration for which to download artifacts.
  3. In the row containing the integration, click the hamburger menu menu on the far right, and click Download Artifacts.
  4. Specify a directory in which to save the zip file when prompted.

Viewing the Contents of an Incomplete Integration

You can open an integration with incomplete connection details on the Integrations page and view its contents. These integrations can only be viewed, and not edited.

To view the contents of an incomplete integration:

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

  2. Open an integration with incomplete connection details (for example, an integration imported from another instance or from the Oracle Marketplace).

  3. A message is displayed at the top of the page describing why you cannot edit the integration.

    Edit is not possible for Integration_Name (version_number) because the connection settings for this integration are incomplete. 
    Update the configuration information for the connections: Connection_Name. Integration is displayed in view mode.
  4. Open individual adapters, mappings, actions (for orchestrated integrations), and other components in the integration for viewing.

  5. Go to the Connections page for the adapter connection requiring configuration, and update the necessary credential and security details.

  6. Return to the integration and note that the message is gone.

Reactivating Integrations After Instance Upgrade to View the Latest Business Identifier Tracking Behavior

After your Oracle Integration Cloud Service instance is upgraded to a newer version, you must reactivate your integrations to view the latest and correct business identifier behavior in the Tracking page.

Filtering the Display of Integrations By Type

You can filter the display of integrations by their type (custom, user-developed, or prebuilt).

To filter the display of integrations by type:
  1. On the Oracle Integration Cloud Service home page, click the Integrations diagram.
  2. Select the Filter by list to filter the display of integrations.
  3. Select the Sort By list to filter the display of integrations by the last update or name.

Changing the Time Zone

You can change the time zone that is displayed in Oracle Integration Cloud Service.

To change the time zone:
  1. In the upper right corner, click the username dropdown list, then select Preferences.
  2. From the Time Zone Settings list, select the time zone you want to use.
  3. Click Save.
  4. Go to the Integrations page and note that the time zone is changed in the message below the status of the integration and inside the information icon at the far right.
    The time zone change is also shown in other parts of Oracle Integration Cloud Service in which the time is displayed (for example, on the Tracking page).

Managing an Integration as an API with Oracle API Platform Cloud Service

You can manage integrations as APIs and group several integrations as a single API using the API Platform Cloud Service integration.

Creating a New API in Oracle API Platform Cloud Service Using an Integration

You can create APIs in API Platform Cloud Service from your integrations with the API Platform Cloud Service integration.

Before you begin:

To manage an integration as an API:
  1. If you are not already on the Integrations page, open the Navigation Menu, click Designer, and then click Integrations.
  2. In the row containing the integration you want to manage with API Platform Cloud Service, click the Actions icon on the far right and then click Manage API with APIP CS.
    Description of conn_actions_menu.png follows
    Description of the illustration conn_actions_menu.png
  3. From the Operation list, select. Create New API.
  4. In the API Name field, enter a name for the API.
  5. In the Version field, enter a version for the API.
  6. In the API Endpoint URL field, enter the endpoint you want the API to receive requests at when deployed to an API Platform Cloud Service gateway. The API Endpoint URL must be unique for each API deployed to an API Platform Cloud Service gateway.
  7. (Optional) In the API Description field, enter a brief description of your integration. This description is displayed in the API Platform Cloud Service Management and Developer Portals.
  8. (Optional) To deploy the API to a gateway, select Deploy API, and then select the gateways you want to deploy the API to. Only gateways the user (specified in Connecting to Oracle API Platform Cloud Service) has deployment rights for are displayed. This option is grayed out if the user doesn’t have the Deploy to Gateway or Request Deployment to Gateway grant for any gateways.
  9. (Optional) To publish the API to the Developer Portal, select Publish API, and then enter a vanity name into the API Portal URL field. The vanity name must be unique for each API managed by API Platform Cloud Service. This option is grayed out if the user doesn’t have the required grants to publish to the Developer Portal.
  10. Click Create.
The API is created in the API Platform Cloud Service Management Portal. It is also deployed or published if you chose those options.
After creating the API, you can manage it in the API Platform Cloud Service Management Portal.

Grouping an Integration in an API in Oracle API Platform Cloud Service

You can group multiple integrations together to manage them as a single API in API Platform Cloud Service.

This makes it easy for you to combine multiple related integrations into a single API in API Platform Cloud Service.

Each integration you group adds a condition to a Resource Based Routing Policy applied to the API in API Platform Cloud Service. When a request is sent to a deployed API requesting the resource you specified for your integration, this policy routes the request to your integration’s endpoint (if the request is passed by all policies in the execution flow before the Resource Based Routing policy).

Example: You have two integrations, one for managing orders and another for managing inventory for your pet store. You want to expose these to application developers, but you want to manage who uses them and how many requests are routed to your integrations. To make management and discovery easier, you can group these integrations in a single API in API Platform Cloud Service. When it’s deployed, the API will route requests to each integration based on the resource the client requests.

Before you begin:

To group an integration in an API:
  1. If you are not already on the Integrations page, open the Navigation Menu, click Designer, and then click Integrations.
  2. In the row containing the integration you want to manage with API Platform Cloud Service, click the Actions icon on the far right and then click Manage API with APIP CS.
    Description of conn_actions_menu.png follows
    Description of the illustration conn_actions_menu.png
  3. From the Operation list, select. Add to Existing API.
  4. In the API Name field, enter the name of the API you want to add the integration to.

    Tip:

    Click the Search: API Name icon to view the APIs you can add the integration to.

  5. (Optional) To deploy the API to a gateway, select Deploy API, and then select the gateways you want to deploy the API to. Only gateways the user (specified in Connecting to Oracle API Platform Cloud Service) has deployment rights for are displayed. This option is grayed out if the user doesn’t have the Deploy to Gateway or Request Deployment to Gateway grant for any gateways.
  6. (Optional) To publish the API to the Developer Portal, select Publish API, and then enter a vanity name into the API Portal URL field. This option is grayed out if the user doesn’t have the Manage API grant for the API you selected.
  7. Click Create.
The integration is grouped with the API.
After grouping an integration with an API, you can manage it in the API Platform Cloud Service Management Portal.

Ungrouping an Integration from an API

You can ungroup an integration from an API it was previously grouped in.

When you ungroup an API, the condition for the ungrouped integration is removed from the Resource-Based Routing policy applied to the API. If the API is redeployed if it is deployed to a gateway and republished if it is published to the Developer Portal.

Note:

This task removes an integration that has been grouped with others in an API, described in Grouping an Integration in an API in Oracle API Platform Cloud Service. Don’t use this operation if the integration is the only endpoint added for an API. Delete the API in the API Platform Cloud Service Management Portal instead.

To ungroup an integration from an API:
  1. If you are not already on the Integrations page, open the Navigation Menu, click Designer, and then click Integrations.
  2. In the row containing the integration you want to ungroup from an API, click the Actions icon on the far right and then click Manage API with APIP CS.
    Description of conn_actions_menu.png follows
    Description of the illustration conn_actions_menu.png
    The Manage API with APIP CS dialog appears.
  3. In the Operation list, ensure that Remove from Existing API is selected, and then click Remove.

The integration is ungrouped from the API. The condition in the Resource Based Routing policy for the integration is removed from the API.

Note:

  • If the target API has only one integration grouped to it, ungrouping fails with this error: Remove from existing API failed due to the following reason: Operation failed: Unable to remove from a API which contains a single endpoint.

  • If the API is removed from API Platform Cloud Service, then ungrouping succeeds. You can then create an API from or group this integration to an API as usual.

After ungrouping an integration from an API, you can manage the API in the API Platform Cloud Service Management Portal.