23 ICS Connector APIs

Oracle Mobile Cloud Enterprise (OMCe) enables you to create Integration Cloud Service (ICS) connector APIs to access on-premises and cloud services through ICS. You can then call these connector APIs from the implementations of your custom APIs.

You can also use SOAP connector APIs to connect to enterprise services. However, using ICS together with ICS connector APIs has the following advantages:

• You write far less code.

• You connect to services more because the integrations are done for you.

• You let the connector API handle the details of interacting with Oracle Integration Cloud Service.

ICS also makes it easy to map business objects from one application to another. For example, a service can be created that synchronizes data from a purchase order between Oracle Sales Cloud to an Oracle CPQ (Configure, Price, and Quote) Cloud application.

How ICS Connector APIs Work

ICS connector APIS enable you to access services that you have exposed in Integration Cloud Service (ICS).

ICS itself is a service designed to simplify connectivity between your services and applications, both cloud-based and on premises. When you work with ICS, you work with integrations that connect applications and map data between them.

You create an ICS connector API with the ICS Connector wizard, in which you enter the SOAP proxy for the integration. Once you have done so, you are shown a list of integrations that correspond with that proxy and can select one. For each ICS integration, there is a single operation per endpoint. After you select the integration, you can proceed to test the endpoint.

Once you have created an ICS connector API, you can call it from the implementation of a custom API.

Note:

Only SOAP-based integrations are supported.

ICS Connector API Flow

Here’s the process for designing an ICS connector API:

Description of the illustration ics_dt_flow.png

1. Create ICS Connector API. You create an unbound ICS connector API with the Integration Cloud Service Connector API wizard.

2. Authenticate with ICS Instance (Design Time Credentials). You pass design time credentials to connect to the ICS instance. These credentials are the username and password received when you subscribe to the Oracle Integration Cloud Service.

3. Connect to the ICS Instance. OMCe locates the ICS instance via the service URL provided.

4. Discover the Integrations. When authentication is confirmed, a list of active integrations in the ICS instance is displayed.

5. Select an Integration. You select an integration instance from a list of the integrations.

6. Access the Integration (Runtime Credentials). You pass credentials to allow access to the runtime instance of the integration. Runtime credentials are the username and password you received from the ICS administrator that allow you to run the integration.

7. Test the ICS Connector API. You test the endpoint using mobile user credentials.

Here’s how the connector API works at runtime:

Description of the illustration ics_runtime_flow.png

1. The custom code implementation of one of your custom APIs calls the connector API. Information is then passed to the connector implementation, and the implementation extracts the payload from the request.

2. A connection is made to the ICS service via the service URL. The service verifies the design-time credentials passed to it and the active integrations are exposed.

3. Runtime credentials are passed from ICS to either the on-premises agent or to a single cloud service to access the selected service integration.

4. Information is passed back through the integration (and, for on-premises applications, via the on-premises agent) to the connector API and back to the custom API.

How Do I Create an ICS Connector API?

Creating an ICS Connector API consists of four stages:

1. Creation: You’ve named the API and provided a description. Once created the API exists in a Draft state.

2. Connection: You’ve provided the URL to the ICS service and your design time credentials, which give you access to the ICS service.

   Note:

   The design time credentials can be saved so you only need to do it once per ICS instance. It’s important to note that you can only use the credentials that you saved. That is, if other developers want to access this instance, they’ll have to enter their own credentials at least once themselves.

3. Discovery: OMCe locates the ICS service and obtains instances of the active integrations available from the service.

4. Configure: You’ve selected (or created) a CSF key for the security policy and provided your runtime credentials.

5. Test: Now you can test your endpoint to validate the connection to the service.

Setting the Basic Information for Your ICS Connector API

Before you begin configuring your connector, you must provide some initial basic information like the connector API name, a brief description, and connection timeout settings.

1. Click and select Mobile Apps > APIs.
   The Connectors page appears. If no connector APIs have been created yet, you'll see a REST Connector icon, a SOAP Connector icon, and an ICS Connector icon. If at least one connector API exists, you'll see a list of all the connector APIs. You can filter the list to see only the connector APIs that you're interested in or click Sort to reorder the list.
2. Click ICS (if this is the first connector API to be created) or New Connector and from the drop-down list, select ICS.
   Each time you create an ICS Connector API, the New ICS Connector API dialog appears. This is where you enter the basic information for your new connector API.

   
   Description of the illustration ics_newapi.png
3. Identify your new ICS Connector API by providing the following:

   • API Display Name: Enter a descriptive name (an API with an easy-to-read name that qualifies the API makes it much simpler to locate in the list of connector APIs).

     For example, myICSService.

     For new connectors, a default version of 1.0 is automatically applied when you save the configuration.

   • API Name: Enter a unique name for your connector API. The default value is a simplified form of the value that you entered for the API Display Name.

     For example, myICSService.

     By default, this name is appended to the relative base URI as the resource name for the connector API. You can see the base URI below the API Name field.

     Note:

     The connector API name must consist only of alphanumeric characters. It can’t include special characters, wildcards, slashes /, or braces {}. A validation error message is displayed if you enter a name that is already in use.

     If you enter a different name for the API here, the change is automatically made to the resource name in the base URI.

     Other than a new version of this connector API, no other connector API can have the same resource name.

   • Short Description: Provide a brief description, including the purpose of this API.

     This is the description of the API that will be displayed on the Connectors page when this API is selected. The character count below this field lets you know many characters you can add.

4. Click Create.
   Tthe General page of the ICS Connector API wizard is displayed.
5. Set the timeout values if needed.

   Connecting to the ICS instance can take several minutes. You can increase the timeout values to reduce the chances of a connection time out but be aware that the values that you apply at design time are also applied at runtime when the connector calls on the instance. If you do set timeout values, be sure to save your edits to the General page before proceeding to the next step of the wizard.

   Note:

   If you’re a mobile cloud administrator, you can open the policies.properties file to see the value for the network policies for the environment that you’re working in from the Administrator page. Otherwise, ask your mobile cloud administrator for the values. To learn about environment policies, see Oracle Mobile Cloud Enterprise Policies.

   
   Description of the illustration ics_timeout.png

   • HTTP Read Timeout: The maximum time (in milliseconds) that can be spent on waiting to read the data. If you don’t provide a value, the default value of 20 seconds is applied.

   • HTTP Connection Timeout: The time (in milliseconds) spent connecting to the remote URL. A value of 0 mms means an infinite timeout is permitted.

6. Click Save to save your current settings.
   If you want to stop and come back later to finish the configuration, click Save and Close. You can always click Cancel at the top of the General, Integration, and Runtime Security pages to cancel that particular configuration operation. You’ll be taken back to the Connector APIs page.
7. Click Next (>) to go to the next step in configuring your connector API.
   After the basic information is provided, you can specify the interaction details for your connector API.

You can always edit your configuration when it's in a Draft state. You can make changes to a connector API that's in the Published state by creating a new version of it. For information on creating a new version, see Creating a New Version of a Connector.

Connecting to an Integration Cloud Service Instance

This is where you select the Integration Cloud Service (ICS) instance that you want or create a connection to an ICS instance. If this is the first time that you’re creating an ICS connector API, the Select Connection drop-down list won’t be available and you’ll have to create a connection to the instance.

Making a connection consists of the following phases:

• Selecting or creating an ICS instance and authentication

• Connecting to the server hosting the active integrations

• Selecting the active integration

You perform or observe these operations on the Integrations page of the Integration Cloud Service Connector API wizard.

Selecting or Creating an ICS Instance Connection

1. If at least one integration instance exists, select an integration instance from the Select Connection drop-down list; otherwise, go to Step 2 to create an instance.
   
   Description of the illustration ics_integration_pt1.png
2. Enter a name to identify this Integration Cloud Service instance in the Connection Name field.
   This name will be added to the list of integration instances.
3. Enter the address of the server that hosts the integrations in the Service URL field.
   You get the URL of the service from the service administrator of the Oracle Cloud Integration Service. The URL takes the form hostname/ics.

   You can save time by verifying that the URL you’re providing is trusted at trustedsource.orgs, otherwise, even if you’re connector API is configured correctly, the connection will fail. See Common Custom Code Errors.

4. Enter your user name and password that you were given to access the integration.
   These are the design time credentials that enable you to access the Oracle Integration Cloud Service. These are the user name and password you received when you subscribed to the service.
5. Select Remember My Credentials so that the next time you select or create an integration instance, your credentials are already preloaded.
   These credentials are specific to the individual OMCe user and aren’t provided if another OMCe user tries to access the same integration instance.
6. Click Connect.

After you’ve created an integration instance, you’ll be able to select it from the Select Connection drop-down list the next time you come back to the wizard.

Selecting an Active Integration

When the connection to the server hosting the integrations is made, the Integrations page of the wizard displays all the active integrations where a single cloud service or on-premises solution is exposed as an integration-friendly API. Non-active integrations or integrations that push events from one cloud service or on-premises solution to another aren’t listed. Each integration is displayed with its name, version, and description.

1. Filter the list by entering part of its name, description, or integration type.
   You can sort the list in either ascending or descending order based on name, creation date, last update, or type.
2. Select the integration you want.
   
   Description of the illustration ics_integration_pt2.png

   Click the information icon to see details about the integration including a link to the WSDL for the integration.

   Note:

   Remember, that currently, only SOAP-based integrations are supported.

   
   Description of the illustration ics_integ_info.png
3. Click Save.
4. Click Next (>) to go to the next step in configuring your connector API.

Editing the ICS Connector API

If you go to the RunTime Security page and change your mind about the integration you selected, you can go back and select a different integration. The list of integrations you see might not be the latest available though. If you do go back, be sure to refresh the page before selecting another integration. Also, you’ll have to re-authenticate yourself to access the list of integrations if you didn’t save your credentials previously.

Note:

Once you’ve moved on to the Test page, you won’t be able to go back to the Integrations page to select a different integration. If you return to the Integrations page from the Test page, you’ll see only the integration that you’ve selected.

1. Click Integrations in the navigation links at the top of the wizard.
   The page displays only the integration you originally selected.
2. Click Refresh on the Integration page of the wizard.
3. Confirm the refresh action.
   The Integrations page is displayed at the authentication phase. The connection name and service URL you provided previously are shown as information only.
4. If you previously selected the Remember My Credentials option, click Connect.
   If you didn’t select that option, enter your design time user credentials and click Connect.

   Credentials are saved securely in the OMCe backend. You only need to save them once for that user’s devices and browsers. Note that no sensitive information is stored locally.

5. Select the active integration you want from the list after the connection is completed.
6. Click Save.
7. Click Next (>) to go to the next step in configuring your connector API.

Setting Runtime Security for the ICS Connector API

You must set the csf-key property with your runtime credentials to allow you access and test the active integration.

Description of the illustration ics_security.png

Provide a CSF Key in one of the following ways:

• Click Select Existing and select an existing key from the Available Keys list in the Select or Create a New API Key dialog. A description of the selected key is displayed below the list. The list displays only the keys supported by the client policy, which could be http_basic_auth_over_ssl_client_policy, wss_http_token_over_ssl_client_policy,or wss_username_token_over_ssl_client_policy.

  When you select the key, its name appears in the Key Name field. Click Select to add the key. The other fields in the CSF Key Details pane are used only when creating a key.

• Create a new basic (CSF) credentials key directly on the Security page.

  For the steps on creating a key, see Creating a New CSF Key. Alternatively, you can click Select Existing and create the key in the Select or Create a New API Key dialog.

Regardless of which security policy is used, the ICS adapter API determines the correct authentication mode. Once you’ve configured the ICS Connector API for a given ICS instance, the runtime credentials that you provided for that instance are remembered the next time you configure an ICS Connector API.

To learn about security policies for the ICS Connector, see Security and ICS Connector APIs.

Creating a New CSF Key

1. Click the Security navigation link.
2. Enter a key name that is descriptive and easy-to-read. Note that after you create the key, you can’t change the key name.
3. Enter a brief description of the key's purpose.
4. Enter your runtime credentials for the service to which you are connecting.

   Contact your ICS administrator to obtain the credentials used to call the Oracle Integration Cloud Service at runtime. Most likely, you’ll only need to do this once per ICS instance (all integrations are called with the same app credentials).

5. Repeat the password in the confirmation field.
6. Click Save to continue working in the dialog.
   Click Save and Close to save your actions and return to the Security page. Click Cancel to quit the task.

The key name value will appear as the override value on the Security page. Note that the value of the key that you create pertains only to the environment in which it’s set.

If you want to edit some aspect of an existing CSF key, select it from the Available Keys list and modify the fields as needed.

If you’ve already selected a key but then decide to create a new key, click Clear Selected to clear all the fields.

To learn about CSF Keys, see CSF Keys.

Testing the ICS Connector API

When you’ve finished configuring your ICS Connector API, test the endpoint:

1. Click the Test navigation link.
   There is only one endpoint per integration. The resource banner displays the method, the resource name, and the URI of service.
2. Expand Examples to see examples of a request, response, and fault payloads that were obtained from the WSDL.
   
   Description of the illustration ics_test_examples.png

   When you select a connection, all the fields on the page are populated with data for that connection with the exception of credentials.

   If this is the first time a connection is being created, skip this step and go to Step 3.

3. Add one or more request or response HTTP headers as needed.
   
   Description of the illustration ics_test_headers.png
4. Click in the HTTP Body field to create your message body (the payload) in the source editor. For example:

   {
    "$schema":"http://json-schema.org/draft-04/schema#",
    "title":"Object",
    "description":"An object for this service",
    "type":"object"
   }

5. Provide your runtime credentials for testing this endpoint:

   1. Enter the name of the mobile backend associated with this connector API.

   2. Enter the version of the mobile backend.

   3. (Optional) Enter your mobile user credentials, that is, your runtime credentials.

6. (Optional) Click Save as current mobile backend default credentials to allow the ICS Connection API to remember your credentials. Only your credentials will be stored. These credentials are applied when you test another ICS Connector API, REST or SOAP Connector API, or a custom API.
7. Click Test Endpoint.
   
   Description of the illustration ics_test_success.png

   Test Endpoint toggles to Cancel Test. If you want to stop the test for any reason, click Cancel Test.
8. Click Done when you’ve finished testing your endpoint.
   You’re returned to the Connectors APIs page.

If you want to make changes to the testing parameters, click Reset to clear all the fields.

Getting the Test Results

Test results are displayed at the bottom of the Test ICS API page. The result indicator is the response status:

• 2xx: indicates a successful connection

• 4xx: indicates a user error occurred

• 5xx: indicates a server error occurred

The following table lists the most common status messages you’ll see:

Status Code	Description
200 OK	Successful connection.
400 BAD REQUEST	General error when fulfilling the request, causing an invalid state, such as missing data or a validation error.
401 UNAUTHORIZED	Error due to missing or invalid authentication token.
403 FORBIDDEN	Error due to user not having authorization or if the resource is unavailable.
500 INTERNAL SERVER ERROR	General error when an exception is thrown on the server side.

Click Request to see the metadata for the transaction, such as header information and the body of the request.

Click Response to see the details of the response returned. The response code tells you whether or not the connection was successful.

After your connector API is tested, published, and deployed, you can go to the Connectors page to see analytical information about it, such as how often the connector is being called and what apps are using the connector. See Managing a Connector.

Getting Diagnostic Information

You can view the response code and returned data to determine if your endpoints are valid. A response status other than 2xx doesn't necessarily mean the test failed. If the operation was supposed to return a null response, a response should show a 4xx code.

For every message that you send, OMCe tags it with a correlation ID. A correlation ID associates your request with other logging data. The correlation ID includes an Execution Context ID (ECID) that’s unique for each request. With the ECID and the Relationship ID (RID), you can use the log files to correlate messages across Oracle Fusion Middleware components. By examining multiple messages, you can more easily determine where issues occur. For example, you can retrieve records from Oracle Fusion Middleware Logging using the call's ECID. From the Administration page, you can click Logs to view logging data: the connector API call received by a single MBE outbound connector API call.

Depending on your OMCe access permissions, you or your mobile cloud administrator can view the client and server HTTP error codes for your API's endpoints on the Request History page allowing you to see the context of the message status when you're trying to trace the cause of an error. Every message sent has a set of attributes such as the time the event occurred, the message ID, the Relationship ID (RID), and the Execution Context ID (ECID).

To obtain and understand diagnostic data, see Diagnostics.

Security and ICS Connector APIs

HTTP Basic Authentication is used for runtime security. Basic authentication allows an HTTP user agent to pass a user name and password with a request and is often used with stateless clients, which pass their credentials on each request.

ICS Connector APIs use one of the following security policies:

• http_basic_auth_over_ssl_client_policy. It includes the username and password credentials in the HTTP header for outbound client requests. This policy verifies that the transport protocol is HTTPS.

• wss_http_token_over_ssl_client_policy. The username and password credentials are included in the HTTP header for outbound client requests. Also a timestamp is sent to the SOAP security header. If the connector detects that the ICS integration that’s being connected to is protected by the wss_http_token_over_ssl_service_policy, the connector uses the corresponding client policy. This policy verifies that the transport protocol is HTTPS.

• wss_username_token_over_ssl_client_policy. The username and password credentials are passed as SOAP headers and are added automatically by the connector. If the security policy is defined in the WSDL for a SOAP-based integration, this is the policy that’s used. This policy verifies that the transport protocol is HTTPS.

Although you can set the Oracle-Mobile-External-Authorization header in custom code to configure a secure connection, it isn’t necessary since authorization to connect to a service is set when configuring the ICS Connector API.

CSF Keys

In OMCe, the Oracle Credential Store Framework (CSF) is used to manage credentials in a secure form. A credential store is a repository of security data (credentials stored as keys) that certify the authority of users and system components. CSF lets you store, retrieve, update, and delete credentials (security data) for a web service and other apps.

A CSF key is a credentials key. It uses simple authentication (composed of the user name and the password for the system to which you’re connecting) to generate a unique key value. You can select an existing CSF key or create one through the Select or Create a New API Key dialog. To select or create a CSF key, see Creating a New CSF Key.

CSF keys and their values are specific to the environment in which they’re defined. That is, if the Development environment is selected, then only the CSF keys and certificates for the security policies in use by artifacts in that environment are listed in the CSF Keys dialog. A different set of keys and certificates will be displayed in another environment, such as Staging. It’s also possible for keys with the same key name but with different values to exist in multiple environments.

A CSF key can be deployed to another environment, however, because CSF keys are unique to an environment, only the key name and description are carried over to the target environment. You won’t be able to use that key in the new environment until it’s been updated with user name and password credentials by the mobile cloud administrator.

Using Your Connector API in an App

To use a connector in a mobile app, you need to have a custom API that can call the connector API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.

The syntax for a call to a connector API is the same as you would use when calling any other API from custom API implementation code. See Calling Connector APIs from Custom Code.

Description of the illustration connector-calling1.png

When you implement a custom API, you can view the available connectors in the API Catalog tab in the API Designer. While creating your custom API, you might find it beneficial to open the Test page of the connector API so that you can refer to any headers, parameters, and schemas that you’ve configured for the connector API.

Troubleshooting ICS Connector APIs

System message logs are great sources for getting debugging information. Depending on your role, you or your mobile cloud administrator can go to the Administration view and click Logs to see any system error messages or click Request History to view the client (4xx) and server (5xx) HTTP error codes for the API's endpoints and the outbound connector calls made within a single mobile backend.

Here are some areas of particular interest when troubleshooting:

• Security Errors are Occurring

  Take a look at the integration WSDL and see if you can determine what security policy is being used. Use the SOAP connector directly to create a connector API and test with different security policies.

• An Integration Isn’t Showing Up

  Go to Oracle Integration Cloud Service and look at your integrations there. The status must be activated, and the source connection type should be SOAP.

• Constructing a Valid ICS Instance URI

  Your instance URI must begin with https:// and should end in /ics. Look for the Email that you received when your user account was provisioned for the ICS instance. From there, you can find the URI to reach the ICS UI. The same URI should be used to create the connection in OMCe.

• Identifying Where the Failure Is Occurring

  As with other connectors generally finding where a fault was thrown can be difficult. A 401 or 404 for instance could be returned by the test endpoint, OMCe itself, the ICS instance that OMCe is connecting to, or the system to which ICS is connecting.

  401 and 404 errors are difficult because they return no message body that might indicate where the error occurred. However, the headers associated with a 401 and 404 error can sometimes act as a signature to indicate where it originated from. Likewise, trace the end-to-end flow by searching for corresponding log entries at each step in the flow.

• Can’t Make a Connection Using Default Protocols

  By default, only TLSv1.1 and TLSv1.2 protocols are used for outbound connections. If you need to use an older version of a SSL protocol to connect to an external system that doesn't support the latest versions of SSL, you can specify the SSL protocol to use for the connector by setting the Security_TransportSecurityProtocols environment policy. The policy takes a comma-separated list of TLS/SSL protocols, for example: TLSv1, TLSv1.1, TLSv1.2. Any extra space around the protocol names is ignored. You can use the SSLv2Hello protocol to debug connectivity issues with legacy systems that don't support any TLS protocol. Note that this policy can’t be used to enable SSLv3 endpoints. See OMCe Policies and Values for a description of the policy and the supported values. Be aware that this policy must be manually added to a policies.properties file that you intend to export.

  Caution:

  Be aware when setting the policy that older protocols are vulnerable to security exploits.