Connectors

21 Connectors

In Oracle Mobile Cloud Enterprise (OMCe), you use connectors to simplify calls to external services, such as enterprise systems and third-party APIs.

OMCe provides connector types for REST, SOAP, Oracle Integration Cloud Service (ICS), and Oracle Fusion Applications.

What Is a Connector API?

A connector API is an interface for connecting to an external service. Connectors APIs give you a standard way to connect to external services and at the same time benefit from OMCe’s built-in security, diagnostics, and analytics features.

Each connector is based on a configuration where you define any connection details, security policies, and rules for things such as default parameter values and proxy path.

You can call a connector API with a simple REST call from the implementation code of a custom API.

REST Connector APIs

You can create connector APIs to connect to external REST services. You can then call these connector APIs from the implementations of your custom APIs.

How REST Connector APIs Work

A REST connector API is an intermediary API for calling REST endpoints in enterprise systems or third-part APIs. The connector API takes the form of a configuration that gives your apps a standard way to connect to these REST services and take advantage of the security, diagnostics, and other features provided by OMCe.

The connector communicates and passes information between the client and the server using the HTTPS protocol. The information passed can be in the form of XML or JSON (but only in JSON for services based on Swagger descriptors).

The REST Connector API wizard walks you through creating REST Connector APIs, from specifying a remote service and setting security policies to testing your endpoints.

Why Use Connectors Instead of Direct Calls to External Resources?

Using a REST Connector API provides you with the following benefits over making direct calls from your app code to external resources:

Allows for simplified declarative connection and policy configuration.
With a Swagger descriptor, determines the available resources and creates endpoints for you.
Provides you with extensive diagnostic information as its tightly integrated with the OMCe diagnostics framework. Any outbound REST calls made through connector APIs are logged, which greatly helps with debugging.
Allows for tracking and analytics on remote API usage.
Lets you define interaction with the service at design time when you test the validity of your endpoints so that the terms of that interaction aren’t dependent on user input at runtime. This protects both the end system and your mobile backend from harm.
Provides a consistent design approach among multiple connector types for interacting with external services.
With any change in the interface for a service, lets you can handle any necessary updates, testing, and migration in one place.

Creating a REST Connector API

Use the REST Connector API wizard to create, configure, and test your connector API.

To get a basic working connector API, you can provide as little as a name for the connector API and a URL to the external service.

From there, you can:

Define rules to form specific requests or responses for the data that you want to access.
Configure client-side security policies for the service that you’re accessing.
Test the connection and test the results of calls made to the connection.

You must create a custom API and implementation to enable your apps to call the connector APIs. To generate the API and implementation automatically, see Generating Custom APIs for Connectors. If you want to do this manually, create a custom API with the appropriate resources, and then implement the custom code as described at Calling Connector APIs from Custom Code.

Basic Connector Setup

You can create a functioning connector by completing the first two pages in the REST Connector API wizard.

Click and select Mobile Apps > APIs from the side menu.
Click REST (if this is the first connector API to be created) or New Connector and from the drop-down list, select REST.
Identify your new REST Connector API by providing the following:
1. API Display Name: The name as it will appear in the list of connector APIs.
2. API Name: The unique name for your connector API.
  
  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.
  
  Other than a new version of this connector API, no other connector API can have the same resource name.
3. Short Description: This description will be displayed on the Connectors page when this API is selected.
Click Create.
In the General page of the REST Connector API dialog, set the timeout values:
- 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 0mms means an infinite timeout is permitted.
  
  The HTTP timeout values must be less than the Network_HttpRequestTimeout policy, which has a default value of 40,000 ms. To learn more about policies, see Oracle Mobile Cloud Enterprise Policies.
  
  Note:
  If you have a mobile cloud administrator role in addition to your service developer role, you can open the policies.properties file to see the value for the network policies for the current environment from the Administrator view. Otherwise, ask your mobile cloud administrator for the values.
Click Descriptor and enter the connection info for the service.

If you provide a Swagger descriptor URL, the available resources are identified and displayed, and you can select which ones you want.

Note:
Only standard internet access ports 80 and 443 are supported. Connection to a service can't be made using a custom port.
Click Save.
Optionally, click Test, select authentication credentials, and make test calls to the service.

From there, you can further configure the connector in the following ways:

(If you have provided a descriptor on the Descriptor page) navigate to the Resources page and select the methods for the exposed resources.
Define rules.
Set security policies.

To be sure your connector API configuration is valid, you should test it thoroughly (not just from the Connector API Test page) before publishing it. That is, you should also test the custom API (with its implementation) that uses this connector API. See Testing and Debugging Custom Code. Essentially, if you’re ready to publish the connector API, you should also be ready to publish the custom API that calls it.

If you’ve already published the connector API and then find that you need to change it, you must create a new version of it. See Creating a New Version of a Connector in Managing Oracle Mobile Cloud, Enterprise.

Rules

You set rules to define the interactions between your mobile app and a service. Rules provide a way for you to add default parameter values for all calls to resources on the service, calls to a specific proxy path, and calls for certain types of operations (verbs). This helps enforce consistent syntax of the URL string, saves the custom code developer from having to insert these values, and makes it possible to track the different calls through analytics.

You can create one or more rules. Each rule can have one or more parameters of type Query and Header.

If no rules are applied, all calls are passed through the proxy to the existing service.

(If the connector is not already open) click and select Mobile Apps > APIs from the side menu.
Select the connector API that you want to edit and click Open.
Select Roles.
Click New Rule.
Click Add Parameter and select a Query or Header parameter type and enter the query or header name, and its value.

Note:

Although you can define rules to set certain headers by default, the rules aren’t applied if the client that called the connector directly through custom code or indirectly, such as from a web browser or mobile app, has already set the same headers.

In particular, setting the format of the request body is usually done in the custom code with the Content-Type header, not as a REST Connector rule. Similarly, setting the format of the response body is also done in the custom code with the Accept header, not as a REST Connector rule.

You can add as many parameters to a rule as you want but it's better not to overload a rule with too many operations. A simpler rule construct is easier to troubleshoot.
Expand Resources and edit the remote URL to provide a resource for the rule to be applied to. The base URL value is what you entered in the setting basic information step and it can’t be edited.

Description of the illustration rest_rule_url.png
Select Do not apply to lower level resources if you want the rules applied only to the resource level specified in the Remote URL.
(Optional) Unselect the HTTP methods that you don’t want applied to rules that you just defined. By default, all methods are selected.
(Optional) Click New Rule to create another rule.

Note:

If you define a rule that conflicts with another rule, the first rule applied takes precedence and the conflicting rule is ignored.

When you're done, click Save and then Next (>) to go to the next step in configuring your connector API.

The description of the rule that you just defined is shown in the Rule banner just above the Default Parameters section. For example, let's say the following values have been provided:

Remote URL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
Local URI = myMapAPI
Rule with the following parameter: Query:key:A3FAEAJ903022
GET and PUT HTTP methods

The rule description would read as follows:

For GET to https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle available at myMapAPI/directions, Include Query:key=A3FAEAJ903022.

If no rules were created, the description would simply read:

For ALL METHODS to https://maps.googleapis.com/maps/api/directions available at myMapAPI, No default parameters will be applied.

Now you have a base URI that maps to the existing service. Using our example:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattle maps to https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle

Security Policies and Overriding Properties

Before you finalize your connector API, you should consider how to handle its security. You can use either security policies or authorization headers. Selecting a security policy that describes the authentication scheme of the service to which you’re connecting to is the recommended approach.

If you want to use headers, see Security and REST Connector APIs.

Every security policy has properties, called overrides, which you can configure. One reason to override a policy configuration property is to limit the number of policies that you have to maintain: rather than creating multiple policies with slightly varied configurations, you can use the same generic policy and override specific values to meet your requirements.

To select a security policy and set the policy overrides:

(If the connector is not already open) click and select Mobile Apps > APIs from the side menu.
Select the connector API that you want to edit and click Open.
Select Security.

Description of the illustration rest_security.png
Select the security policy from the list of available policies and click the right arrow to move it to the Selected Policies list.
Select only a single policy for your connector API. A description of a selected policy is displayed below the list. To find out more about the supported security policy types for the REST Connector API, see Security Policy Types for REST Connector APIs.
Specify overrides, if applicable, to the selected policy if you don't want to use the default values.
To override a property, enter or select a value other than the default. For a description of policy properties, see Security Policy Properties.
To set a Credential Store Framework (CSF) Key value, see Setting a CSF Key. To learn about credential keys and certificates, see CSF Keys and Web Service Certificates.
Click Save to save your work or Save and Close to save your work and exit the REST Connector API wizard.
Click Next (>) to go to the next step, testing the connector, Testing in Advanced Mode.

Setting a CSF Key

If you want to authenticate the user, you must set the csf-key property. You must set the csf-key property if you’ve selected http_basic_auth_over_ssl_client_policy, http_samle20_token_bearer_client_policy, or http_samle20_token_bearer__over_ssl_client_policy.

Note:

If you set the csf-key and the security policy has a subject.precedence property, that property should be set to false. If you need to set subject.precedence to true, you must also set the propagate.identity.context property. In the latter case, don’t set csf-key.

Click Keys in the csf-key field in the Security Overrides section to open the Select or Create a New API Key dialog.

Provide a CSF Key in one of the following ways:

Select an existing key from the Available Keys list.

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.

To create a new CSF key:

Click New Key.
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.
Enter a brief description of the key's purpose.
Enter the user name and password (the user credentials) for the service to which you are connecting.

Repeat the password in the confirmation field.
Click Save to add the key to the Available Keys list.
The key name value will appear as the override value on the Security page.

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. To learn more about CSF keys, see CSF Keys and Web Service Certificates.

Testing in Advanced Mode

The advanced test page lets you manually set path parameters, add headers, and the request and response payloads.

To manually configure a connector test:

Click the Test navigation link.
If you provided a descriptor, turn Test in Advanced Mode to On.

The advanced test page displays automatically if you provided a remote service url.
Select the HTTP method that you want to test from the drop-down list.
Specify any resource path parameters in the Local URI field as needed for testing purposes. For example:
```
directions/json?origin=los+angeles&destination=seattle
```
The field is automatically prefixed with the local URI that you defined when you entered an API name. Following our example, the full contents of the field would look like this:
```
myMapAPI /directions/json?origin=los+angeles&destination=seattle
```
Notice that if you defined any rules, the Rules Applied field (below the Body field) displays numbers that correspond to the rules that are applicable for the selected operation. The Remote URL field shows the exact string that will be passed to the service for the test.
Add one or more request or response HTTP headers as needed.

These headers are for testing purposes only and won't be added to your REST Connector API configuration.
Click in the HTTP Body field to create your message body (the payload) in the source editor.
For example:
```
{
  "status":"ZERO_RESULTS",
  "routes":[ ]
}
```
Keep the content of the message body relevant to the purpose of the connector, that is, don’t bloat the message by adding extraneous data. Including only pertinent data in the message body facilitates quick transmission of the request or response.
If the service that you're connecting to requires authentication, open the Authentication section and enter your mobile user credentials for each method you test. If you’re using default test credentials, you can skip this step.

With SAML-based security policies, the identity of the user making the call is propagated to the external service. For other security policies such as HTTP Basic Authentication and username token, the credentials used to authenticate with the external service are provided in the policy overrides as CSF keys. Depending on the operation that you’ve defined, you may have to enter specific credentials for each operation or you might be able to use one set of credentials for all the methods to authenticate your connector with the service.
Click Save as current mobile backend default credentials to save the user name and password that you provide as the default.
If you’re in the design phase of creating your connector and you just want to see if your endpoints are valid, click Default API Designer Test Credentials and select a mobile backend that you’re registered with and its version number.
Optionally, you can enter your mobile user credentials (user name and password).
These default test credentials are persistent across all the methods that you test. They remain valid during the current OMCe session.
Click Test Endpoint.

Test Endpoint toggles to Cancel Test when you click it. If you want to stop the test for any reason, click Cancel Test.

Click Reset to clear the fields and modify the test parameters.
Click Done when you’ve finished testing your endpoints.

Getting the Test Results

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

2xx: indicates a successful connection
3xx: indicates a redirection occurred
4xx: indicates a user error occurred
5xx: indicates a server error occurred

Here's a list of the more common status codes that you'll want to use:

Code	Description
200 OK	Successful connection.
201 CREATED	Successful creation through either a `PUT` or `POST` operation.
204 NO CONTENT	Successful connection but no response body (used for `DELETE` and `UPDATE` operations).
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.
404 NOT FOUND	Error due to the resource not being found.
405 METHOD NOT ALLOWED	Error that although the requested URL exists, the HTTP method isn’t applicable.
409 CONFLICT	Error due to potential resource conflict caused, for example, by duplicate entries
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.

Test each of your operations and modify them as needed to validate your endpoints.

After your connector API is tested and published, 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 in Managing Oracle Mobile Cloud, Enterprise.

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.

By examining multiple messages, you can more easily determine where issues occur. 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. Click Logs on the Administration page to view logging data. You can also retrieve records from Oracle Fusion Middleware Logging using the call's ECID.

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 REST Connector APIs

OMCe gives you the flexibility to configure a secure connection to external services through the use of security policies or authorization headers.

Here are the different ways that you can configure a REST Connector API to communicate with a secured service:

Configure a security policy.

On the Security tab of the REST Connector UI, decide which policies describe how the external service that you’re communicating with is secured, and configure it as necessary. Configuring a security policy is the recommended practice and takes precedence over setting or configuring authorization headers.
Set the Oracle-Mobile-External-Authorization header on each request.

If you decide not to configure a security policy, then the next best course of action is to set the Oracle-Mobile-External-Authorization header for every request that the connector makes. When calling a connector API through custom code, an OMCe-specific authorization header is automatically set as the Authorization header. This original Authorization header that’s set on the connector API request is used to pass only OMCe authorization and is never passed through to the external service call. If you set Oracle-Mobile-External-Authorization on the request, the value of this header will be set as Authorization on the request to the external service. Set an Oracle-Mobile-External-Authorization header only when the service that you’re connecting to is secured in a way that isn’t described by an existing security policy. It won't take effect if one is configured. Passing the Oracle-Mobile-External-Authorization header in the connector request takes precedence over an Authorization header rule.

When setting this header, include BASIC to denote HTTP Basic Authorization or BEARER to denote OAuth. For OAuth, setting this header is applicable in cases where the OAuth token is passed by way of the Authorization header, such as in the following cases:
- A REST connector is used to call another Oracle Cloud service. The same access token that was used to authenticate with OMCe is reused to authenticate with the other service.
- An access token generated by a service is passed to an OMCe custom code call and set on a REST connector call to obtain the information about the individual who received the access token as part of an enterprise mashup.
- A person logs on to Facebook and obtains a Facebook access token. The token is passed to an OMCe custom code call and set on a REST connector call to retrieve the person’s friends list.
Configure a rule for the Authorization header.

Lastly, when the Authorization header isn't already being set by other means, you can create a rule to apply a default Authorization header. On the Rules tab of the REST Connector UI, create a rule of type Header for Authorization and provide a value. This approach isn’t recommended as usually the Authorization header is dynamic or contains sensitive information (passwords). All sensitive information should be stored in a CSF key, which is why you should configure a security policy when possible.

Security Policy Types for REST Connector APIs

You'll need to set a security policy to protect the information you want to send or receive unless the service you’re accessing isn't a secure service or doesn’t support security policies, in which case, you can’t set a security policy for the connector. When determining what policies to set, consider whether the connection to the service involves transmitting proprietary or sensitive information. Adding a security policy ensures the authentication and authorization of the data transmitted.

From the Security page, you can select one or more Oracle Web Services Manager (Oracle WSM) security policies, including OAuth2, SAML, and HTTP Basic Authentication.

Security Policy Type	Description
OAuth2 and the Client Credential Flow	OMCe supports OAuth2, a system where an Authentication server acts as a broker between a resource owner and the client who wants to access that resources. Of the different flows (security protocols) offered by OAuth2, the Client Credentials Grant Flow is used in OMCe to secure REST connections. This flow is used when the client owns the resources (that is, the client is the resource owner).
HTTP Basic Authentication	HTTP Basic authentication allows an HTTP user agent to pass a user name and password with a request. It's often used with stateless clients, which pass their credentials on each request. It isn't the strongest form of security though as basic authentication transmits the password as plain text so it should only be used over an encrypted transport layer such as HTTPS.
Security Assertion Markup Language (SAML)	SAML is an XML-based open standard data format that allows the exchange of authentication and authorization credentials among a client, an identity provider, and a service provider. The client makes a request of the service provider. The service provider verifies the identity of the client from the identity provider. The identity provider obtains credentials from the client and passes an authentication token to the client, which the client then passes to the service provider. The identity provider verifies the validity of the token for the service provider and the service provider responds to the client.

Ask yourself the following questions to determine what kinds of security policies you need:

What are the basic requirements of your security policy? Do you need to only authenticate or authorize users, or do you need both?
If you need only authentication, do you need a specific type of token and where will the token be inserted?

For a list of the security policies supported for REST Connector APIs, see Security Policies for REST Connector APIs. For descriptions of security policy properties that can be overridden, see Security Policy Properties.

CSF Keys and Web Service Certificates

Depending on the security policy that you selected, you may be able to override a property that sets a CSF key or a Web Service Certificate. 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. A credential can hold user name and password combinations, tickets, or public key certificates. This data is used during authentication and authorization.

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 Setting a CSF Key.

A Web Service Certificate allows the app to securely communicate with the web service. It can be a trusted certificate (that is, a certificate containing only a public key) or a certificate that contains both public and private key information. You override a certificate key by selecting an alias from the drop-down list. The certificate key available in some security policies for a REST Connector API is the keystore.sig.csf.key, which is the alias for this property that’s mapped to the alias of the key used for signing.

Important:

For security policies for REST Connector APIs, don’t override the default value for the keystore.sig.csf.key property. Currently, orakey is the only valid value for all certificate keys.

Not all security policies contain the same properties. When you select a policy, you can see which properties are listed in the Policy Overrides. For example, if you selected http_basic_auth_over_ssl_client_policy, then you’ll see that the policy contains the csf-key property but none of the certificate keys. However, if you selected http_saml20_token_bearer_over_ssl_client_policy, then you’ll see both the csf-key and the keystore.sig.csf.key certificate key.

Note:

It isn’t necessary to set all the overrides for a policy; however, you should be familiar enough with the security policies that you’ve selected to know which overrides to set for each policy.

CSF keys, certificates, and their respective values are specific to the environment in which they’re defined. That is, if there are multiple environments, A and B, and you’re working in environment A, 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 environment B. 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.

Query and Header Parameters

A Query parameter is the most common type of parameter. Use it to filter, sort, and search for information. Add a question mark (?) to the end of the URL followed by a name-value pair. For example:

/directions/distance?origin=Los+Angeles&destination=Seattle

The query specifies that the information wanted is the distance from one location (origin=Los+Angeles) to another (destination=Seattle).

You can see in the example above that the space in the query parameter, Los Angeles, is encoded by a plus sign, (+). The Url_PercentEncodeQueryParameterSpaces policy determines how spaces in query parameters are encoded. If set to true, a space is encoded as a percent sign, (%). If set to false (the default value), a space is encoded as a plus sign (+).

For example, if Url_PercentEncodeQueryParameterSpaces is set to true , the outbound URL would be .../distance?origin=Los%Angeles&destination=Seattle.

Note:

If you specify a parameter in the custom code and you also specify that same parameter in a REST connector rule, the parameter in the custom code takes precedence and overrides the parameter’s value defined in the rule.

Query parameters are usually set in rules, however, you can have query parameters in the remote URL. In such cases, there’s a precedence order for how the parameters are combined at runtime. See Setting Query Parameters in Remote URLs.

Use a Header parameter for outgoing requests. REST headers are a means of providing HTTP metadata. For example, the header, Expires, can be used to specify the amount of time after which a response is considered stale.

Setting Query Parameters in Remote URLs

You can add query parameters to the remote URL. If the remote URL contains a query parameter and you’re adding query parameters to the runtime resource through rules, then there is a precedence order of how the parameters are combined:

1. If you're adding a remote URL that has a query parameter U?qp=a to a runtime resource /r, the query parameter should come after the runtime resource.

For example, if you have the remote URL directions?origin=Pasadena and want to specify the runtime resource /zones, the full URL should be directions/zones?origin=Pasadena. Note that a simple concatenation of the URL isn’t done.

2. If you're combining a remote URL with a query parameter U?qp=a with a default rule qp=b , both query parameters should come after the URL.

For example, if you have a remote URL directions/zones?origin=Pasadena and you want to add the default rule destination=Anaheim, the resulting URL should be directions/zones?origin=Pasadena&destination=Anaheim. It’s orthogonal to rules.

3. If you're combining a remote URL U?qp=a with a runtime request /r?qp=c, the request parameter is appended to the URL.

For example, if you add the request /r?date=2015–04_07T14:30:00.000Z to the remote URL directions/zones?origin=Pasadena, the result isdirections/zones?origin=Pasadena&date=2015–04_07T14:30:00.000Z.

Adding Parameters

Parameters can be added as part of the URI path as a child (nested) resource or added as a query. There are no hard and fast rules as to whether to add parameters to the URI path or to add the parameters in a query. One possible consideration is whether the parameter is essential to the request. For example, you could use an identifier, id, to the directions resource in the URI path to get data for a specific area. If you’re using the parameter as a filter to narrow down the data, then add it in the query. For example, you could define office as a query parameter, .../directions/zones?office=Inglewood, to filter locations of offices only in the Inglewood area.

Besides the remote URL, you can set parameters in the following ways:

Setting a rule
Defining a request body
Defining a test endpoint
Creating custom code

The parameters are considered to be URL-encoded. If a parameter isn’t already URL-encoded, it will be encoded when sent to the external service.

Editing a REST Connector API

If you need to change some aspect of a connector API, you can as long as it’s in the Draft state. After you publish an API, the API can’t be changed. You’ll have to create a new version of a published connector and make your changes to the new version.

To edit a REST Connector API:

Click and select Mobile Apps > APIs from the side menu.
Select the draft connector API that you want to edit and click Open.
Click Refresh ( ) if you’re using the same descriptor and just want to get the latest resources.
Click Save to test your changes immediately or click Save and Close to save your current changes and finish the rest of your changes later.
Test your changes.

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

You have two options for creating such a custom API for a REST connector API:

Generate a custom API for the connector, as described in Generating Custom APIs for Connectors.

This only works for connector APIs that are based on a descriptor URL.
Design a custom API and add calls to the connector in the custom API’s implementation code as described in Calling Connector APIs from Custom Code.

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 REST 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 Administration in the side menu 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.

Sometimes a connection fails because the service URL provided is untrusted. You can add the URL to the list of trusted URLs at trustedsource.org. To learn more about what happens when you use an untrusted service URL and other common errors that can occur when configuring your connector API, see Common Custom Code Errors.

Issues can also arise when connecting to an external service such as when the service has an invalid SSL certificate or the request is redirected but the cookies aren’t preserved over the redirect. You can resolve these issues by using the options argument in custom code to customize the outgoing HTTP requests. See Overriding SSL Settings for Connectors for details.

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.

SOAP Connector APIs

You can create connector APIs to connect to SOAP services. You can call these connector APIs from the implementations of your custom APIs.

How SOAP Connector APIs Work

A SOAP connector API is an intermediary API for calling SOAP endpoints. The connector API takes the form of a configuration that gives your apps a standard way to connect to these SOAP endpoints and take advantage of the security, diagnostics, and other features provided by OMCe.

The key steps to creating a SOAP connector API are establishing a connection to an external system, examining and selecting a set of possible interactions, and then modeling them into a reusable API.

The SOAP Connector API wizard walks you through creating SOAP connector APIs, from specifying the WSDL location of a remote service, setting a port, setting security policies, to testing your endpoints.

Why Use SOAP Connectors Instead of Direct Calls to External Resources?

Allows for simplified declarative connection and policy configuration.
Allows calls to an external service, along with security policy setup and credentials, to be encapsulated and used consistently across the mobile API.
Provides automatic translation of JSON requests to XML and XML responses to JSON, enabling you to interact with SOAP services without having to work expressly with XML. In addition, it provides you with the ability to provide the SOAP envelope itself, giving you the choice of using XML or JSON.
Lets you dynamically modify HTTP timeout properties via the user interface without having to bring down the service. This feature is particularly beneficial when the external SOAP service or network connectivity suffers a slowdown.
Provides you with extensive diagnostic information as its tightly integrated with the OMCe diagnostics framework. Any outbound calls made through connector APIs are logged, which greatly helps with debugging.
Allows for tracking and analytics on remote API usage.
Lets you define interaction with the service at design time when you test the validity of your endpoints so that the terms of that interaction aren’t dependent on user input at runtime. This protects both the end system and your mobile backend from harm.
Provides a consistent design approach among multiple connector types for interacting with external services.
With any change in the interface for a service, lets you can handle any necessary updates, testing, and migration in one place.

Creating a SOAP Connector API

Use the SOAP Connector API wizard to quickly configure your connector API by providing a name and description, specifying a port, setting security policies, and testing it.

Creating a connection to an existing SOAP service can be a simple two-step operation:

Name your connector API.
Provide the WSDL of the external service.

Note:

A timeout can occur when downloading a large WSDL file or when connecting to a WSDL over high latency networks, which prevents the creation of the SOAP Connector API. To ensure the WSDL is downloaded, set the following environment policies before you create the API:

*.*.Network_HttpConnectTimeout
*.*.Network_HttpReadTimeout

Set these policies in the development environment in which you’re creating the SOAP Connector API. A mobile cloud administrator can export the policies file from the Administration view, edit these values, and import the modified file back to the development environment.

These policies affect only the connector APIs during design time. The timeout values that you set while configuring a connector API take effect during runtime.

For more information on policies, see Oracle Mobile Cloud Enterprise Policies.

You also have the ability to configure client-side security policies for the service that you’re accessing and testing and checking the results of your connection.

As soon as it’s created, your connector API appears in the list of connector APIs. When at least one connector API exists, you’re taken directly to the Connector API landing page when you click Connectors from the side menu. From there, you can select the connector API you want and edit it, publish it, create a new version or update an existing version, or move it to the trash.

To call a connector API, you can create a custom API and configure the API’s implementation to call the connector. See Calling Connector APIs from Custom Code.

Setting the Basic Information for Your SOAP Connector API

Before you begin configuring your connector, you must provide some initial basic information like the connector API name, the address to the remote service, and a brief description:

Click and selectMobile Apps > APIs from the side menu.

The Connectors page appears. If no connector APIs have been created yet, you'll see icons for each of the connector APIs that you can create. If at least one connector API exists, you'll see the 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.
Click SOAP or New Connector and select SOAP from the drop-down list.

Each time you create a SOAP Connector API, the New SOAP Connector API dialog appears. This is where you enter the basic information for your new connector API.

Description of the illustration soap_newapi.png
Identify your new SOAP Connector API by providing the following:
1. 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, myOrderApi.
  
  Note:
  The names you give to a connector API (the value you enter in the API name field) must be unique among connector APIs.
  
  For new connectors, a default version of 1.0 is automatically applied when you save the configuration.
2. API Name: Enter a unique name for your connector API.
  
  For example, myorderapi.
  
  By default, this name is appended to the base URI as the resource name for the connector API. You can see the base URI below the API Name field.
  
  The connector API name must consist only of lowercase alphanumeric characters. It can’t include special characters, wildcards, slashes /, or curly braces {}. A validation error message is displayed if you enter a name that’s already in use.
  
  If you enter a different name for the API here, the change will automatically be 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.
3. WSDL Location: Enter the address of the existing SOAP service that this connector API will call. For example: http://example.com/incidentreport/reports.wsdl
  
  You can also copy and paste a WSDL address into this field. To ensure the WSDL you’re using is valid within the scope supported by OMCe, see Troubleshooting SOAP Connector APIs.
  
  Note:
  When specifying a port in the URL, only standard internet access ports 80 and 443 are supported. Connection to a service can't be made using a custom port.
  
  You can save time by verifying that the URL you’re providing is trusted at trustedsource.org, otherwise, even if you’re connector API is configured correctly, the connection will fail. See Common Custom Code Errors.
4. Short Description: Provide a brief description, including the purpose of this API.
  
  The character count below this field lets you know many characters you can add.
  
  After you've filled in all the required fields, click Create, which displays the General page of the SOAP Connector API dialog.
Set the timeout values:

Description of the illustration conn_timeouts.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 0mms means an infinite timeout is permitted.
  
  The HTTP timeout values must be less than the Network_HttpRequestTimeout policy, which has a default value of 40,000 ms. To learn about policies, see Oracle Mobile Cloud Enterprise Policies.
  
  Note:
  If you have a mobile cloud administrator role in addition to your service developer role, you can open the policies.properties file to see the value for the network policies for the current environment from the Administrator view. Otherwise, ask your mobile cloud administrator for the values.
Click Save to save your current settings.

If you want to stop and come back later to finish the configuration, the click Save and Close. You can always click Cancel at the top of the General, Port, and Security wizard pages to cancel that particular configuration operation. You’ll be taken back to the Connector APIs page.
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.

You can always edit your configuration when it's in a Draft state; however, after you publish your connector API, no changes can be made to it. You can make changes by creating a new version of an existing connector API.

Selecting a Port

The services and their associated ports that are available for the WSDL that you provided are listed on the Port page. A port is a set of actions that define the collaboration and interaction with a web service. A service defines the operations and structures of the WSDL and exposes those operations as explicit endpoints. Although a WSDL can contain multiple ports, the SOAP Connector API can only use a single port at a time. If you need to expose more than one port, you must create one SOAP Connector API for each port.

On the Port page, you select a single port that lists the available operations for that service. Optionally, you can provide alternate names for those operations to make them more meaningful or easier to read.

Click the Port navigation link at the top of the SOAP Connector API wizard.
Select a port from the service you want in the list.

You can select only one port. Filter the list by entering a string in the Filter field and click the magnifying glass .

The endpoint field is populated with the service and port endpoint (URL) that are extracted from the WSDL. By default, the original operation name of the SOAP service is used to form the REST resource at which the functionality of the operation would be exposed by the SOAP Connector API.

For example, an operation, CreateIncident, of the service, IncidentReport and port, ReportPort, can be mapped to the REST resource: /mobile/connector/myIncidentReportAPI/CreateIncident.

This is the resource path to which custom code would send requests to. You could expose it differently if you wanted to, for example as the REST resource: /mobile/connector/myIncidentReportAPI/Create.

Note:
If you save the connector configuration without explicitly selecting a port, the first available port for the WSDL is selected for you by default. This action ensures your connector configuration is complete and valid for testing purposes. You can always change the port as long as the connector is in Draft state.
(Optional) Rename one or more operations to make them more meaningful.

All the operations available in the selected port are listed.

Each operation is mapped to the relative base URI that you entered. For example: the operation Create maps to Create resource.

Click Next (>) to go to the next step in configuring your connector API.

Setting Security Policies and Overriding Properties for SOAP Connector APIs

Select one or more security policies that describe the authentication scheme of the service to which you’re connecting. The security policies have properties, called overrides, which you can configure. One reason to override policy configuration properties is to limit the number of policies that you have to maintain: rather than creating multiple policies with slightly varied configurations, you can use the same generic policy and override specific values to meet your requirements.

You don’t need to set all the overrides for a policy; however, you should be familiar enough with a security policy to know which overrides to set.

Click the Security navigation link at the top of the SOAP Connector API wizard.

Description of the illustration soap_security.png
Select one or more security policies from the list of available policies and click the right arrow to move them to the Selected Policies list.
For example, you might want to have wss10_message_protection_client_policy for message protection and wss_username_token_client_policy for authentication. Although you can move all the policies to the Selected Policies list, it’s unlikely that all policies are required for your connector API.
To learn about supported security policy types for SOAP Connector APIs, see Security Policy Types for SOAP Connector APIs .
Select a policy to read its description.
Specify any other overrides, if applicable, to the selected policy if you don't want to use the default values.
To override a policy property, enter or select a value other than the default. For descriptions of policy properties, see Security Policy Properties.
To set or create a csf-key property, see Setting a CSF Key. To learn about credential keys and certificates, see CSF Keys and Web Service Certificates.
Click Save to save your work or Save and Close to save your work and exit the SOAP Connector API wizard.
Before you can test your connection, you must save your configuration. If you proceed to the testing page without saving the API configuration, you'll see a dialog asking you to save it. You can check the Always save before testing option to automatically perform a save operation for you every time you go to the Testing page.
Click Next (>) to go to the next step, testing the connector API.

Setting a CSF Key

Click Keys in the csf-key field in the Security Overrides section to open the Select or Create a New API Key dialog.

Description of conn_csfkey_dialog.png follows

Description of the illustration conn_csfkey_dialog.png

Provide an CSF key in one of the following ways:

Select an existing key from the Available Keys list (a description of the selected key is displayed below the list). The list displays only the basic credentials keys supported by the given policy property.

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 CSF credentials key.

To create a new key:

Click New Key.
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.
Enter a brief description of the key's purpose.
Enter the user name and the password (the user credentials) for the service to which you are connecting. Repeat the password in the confirmation field.
Click Save to add the key to the Available Keys list. You can create another key by clicking New Key or edit an existing one. Save toggles to Select allowing you to select a key in the list. 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 credentials (CSF) key, select it from the Available Keys list and modify the fields as needed.

Setting a Web Service Certificate

Here the steps for setting the overrides for a Web Service certificate. However, for this release, don’t override the values for keystore.sig.csf.key and keystore.enc.csf.key because orakey is the only valid value for all of these certificate keys.

Select a security policy.
The properties for the policy are displayed in the Policy Overrides section.
Select an alias from the drop-down list in the field for the certificate key (certificate keys are denoted by the keystore prefix) and select an alias.
Unlike CSF Keys, you can’t modify a Web Service certificate. You can only select a different alias. Only mobile cloud administrators can create a new Web Service Certificate. If you don’t know the alias for the certificate you want, ask your mobile cloud administrator for the alias.

Testing a SOAP Connector API

Now that you've defined your connector API, you might want to verify your endpoints and ensure that you’re able to receive the expected results from the web service. Testing a connection is also an optional step but can save you time by identifying and fixing problems with your endpoints using the mock JSON body provided before you finalize the connector API.

Testing Your Connector

Now its time to validate your connector. The Test page lets you test the connection to a service using sample response data. You’ll see a list of all the operations that you defined for the port.

Click the Test navigation link.
Select the operation that you want to test.

The base URI is displayed below the operation name. If you provided an alternate name for the operation, that name appears, otherwise the default operation name is shown.
Click Examples to see Request, Response, and Fault payload examples (in JSON format).
These examples are generated based on the request and response definitions in the WSDL file and can’t be edited. The request and response examples display a message body. Fault examples may show one or more faults depending on the operation. They display the error messages returned.

For example, here is what a sample GET request looks like:
```
{
    "Header": null,
    "Body": {
            "GetIncidentById" :  {
				"IncidentId" : 2
            }
        } 
    }
}
```
Here is the request in XML:
```
<soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:beta="http://xmlns.fixitfast.com/fif/beta">
   <soapenv:Header/>
   <soapenv:Body>
      <beta:GetIncidentById>
         <beta:IncidentId>2</beta:IncidentId>
      </beta:GetIncidentById>
   </soapenv:Body>
</soapenv:Envelope>
```
(Optional) Click Add HTTP Header to add one or more HTTP headers to apply to the operation.

You can select a predefined header or a custom header. For each header, select a header name and provide a value.

These headers are for testing purposes only and won't be added to your SOAP Connector API configuration.

The default format for the request body and the response body is JSON. You can set the format of one or both to XML if you prefer. See Using XML Instead of JSON.

Use the sample JSON body provided to test your connector or create your XML body in the source editor. A JSON sample body that you can edit is generated for you from the operation that you’ve defined. For example:

        "Body" : {
            "CreateIncident" :  {
				"Title" : "new title",
				"EmailAddress" : "jack@oracle.com",
				"ImageLink" : "http://example.com/something"
            }
        }

For comparison, here's what the body looks like in XML:

   <soapenv:Envelope
   xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
   xmlns:beta="http://xmlns.fixitfast.com/fif/beta">
    <soapenv:Body>
      <beta:CreateIncident>
         <beta:Title>new title</beta:Title>
         <beta:EmailAddress>jack@oracle.com</beta:EmailAddress>
         <beta:ImageLink>something</beta:ImageLink>
      </beta:CreateIncident>
    </soapenv:Body>
   </soapenv:Envelope>

Click in the editor and enter your own body (in JSON or XML format) if you prefer. To learn about JSON conventions and the mapping between JSON and XML, see How Does XML Get Translated into JSON?

If you’ve selected a SAML-based security policy, open the Authentication section and enter your mobile user credentials for each method that you test. If you’re using default test credentials (Step 7), you can skip this step.

With SAML-based security policies, the identity of the user making the call is propagated to the external service. For other security policies such as HTTP Basic Authentication and username token, the credentials used to authenticate with the external service are provided in the policy overrides as CSF keys. Depending on the operation you’ve defined, you may have to enter specific credentials for each operation or you might be able to use these credentials for all the methods to authenticate your connector with the service.
Click Save as current mobile backend default credentials to save the user name and password you provide as the default.
If you’re in the design phase of creating your connector and you just want to see if your endpoints are valid, click Default API Designer Test Credentials and select a mobile backend that you’re registered with and its version number.
Optionally, you can enter your mobile user credentials (user name and password).
These default test credentials are persistent across all the methods that you test. They remain valid during the current OMCe session.
Click Test Endpoint.

Test Endpoint toggles to Cancel Test when you click it. If you want to stop the test for any reason, click Cancel Test.

Click Reset to clear the fields and to change the header types and values and test body.
Repeat Steps 1 through 4 for each method.
Click Done when you’ve finished testing your endpoints.
You’re returned to the Connector APIs page.

Getting the Test Results

After the test is run, the results are displayed at the bottom of the Test SOAP Connector API page. The result indicator is the response status:

2xx - indicates a successful connection
3xx - indicates a redirection occurred
4xx - indicates a user error occurred
500 - indicates an internal server error

Here's a list of the more common status codes that you'll want to use:

Code	Description
`200 OK`	Successful connection.
`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 or when the service returns a SOAP fault response.

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 the connection was successful.

Test each of your operations and modify them as needed to validate your endpoints. 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 in Managing Oracle Mobile Cloud, Enterprise.

Getting Diagnostic Information

By examining multiple messages, you can more easily determine where issues occur. 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 include 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.

SOAP Connector API Design Tips

When you configure your SOAP Connector API, you want to ensure that you have a well-formed API. You want to make a valid SOAP Connector API but you should create an API that can be used and understood by others as well.

Here are some design recommendations to consider when you define a SOAP Connector API:

Most important, test your connector using the Test page after it’s created and at every update.
When setting the read and connection timeouts for the connector API, you should set them for a shorter duration than the API timeout. See API Timeouts.
Provide an HTTPS endpoint wherever possible.
When calling SOAP services protected with HTTP Basic Authentication, you should configure the appropriate security policies on the Security page and store credentials in a CSF key instead of providing the credentials from custom code.
While writing custom code to call SOAP Connector APIs, make use of the sample request and response payloads available in the Test page of the SOAP Connector API wizard. See Calling Connector APIs from Custom Code.
Keep the payload content relevant to the purpose of the connector, that is, don’t bloat the payloads by adding extraneous data. Include only pertinent data in the message body to facilitate quick transmission of the request or response.
When you're working with complex WSDLs, refer to How Does XML Get Translated into JSON? for a discussion of JSON translator limitations.
Date formats should follow the ISO-8601 International Standard for date and time: YYYY-MM_DD[THH:mm:ss.sss]Z. For example: 2014-10-07T18:35:50.123Z (see Date and Time Formats for a description of the standard).

How Does XML Get Translated into JSON?

The WSDL file, which describes the service that you want to access, is an XML-based protocol. The WSDL contains the XML schemas that define the structure of the SOAP XML requests and responses.

While XML is a standard means of defining SOAP messages, it’s cumbersome and not well-suited to data-interchange. JSON is the preferred format because it’s a lightweight and easy-to-read and write data interchange format (compared to XML). It’s much easier to handle JSON in (Node.js-based) custom code than XML. Here’s a comparison of XML and JSON features:

XML	JSON
Human readable	Easier to read and write for developers and machines
Provides a structure to data making it more informative	Same as XML
Easily processed due to simplicity of data structure	Even simpler structure making it even easier to process
Structure of the data must be translated into a document structure	Structure is based on arrays and records

To make the transmission of data via SOAP Connector APIs possible, OMCe uses a JSON translator. The JSON translator uses a set of mapping conventions when converting a JSON request into XML prior to passing the information to a remote service and translates the XML response back into JSON to be passed on to the mobile app.

OMCe provides sample JSON messages that you can use as a template to construct JSON requests and process JSON responses. A sample payload (body), which gets created for you based on the information in the WSDL, is also translated into JSON.

If you choose to provide your own XML sample payload, then you should adhere to the mapping conventions of XML to JSON to ensure a successful translation. The next section demonstrates those mapping conventions.

Using XML Instead of JSON

Using JSON isn’t required. You might prefer to use XML instead or you might encounter XML schema constructs that aren’t supported by the translator. You can still interact with the connector using XML requests and responses.

The response format is determined by the Accept header in custom code, which has a default value of application/json. To set the format of the request body, add the XML request body and set the contentType header in the custom code to application/xml; charset=utf-8. If you want the response in XML format, change the accept header value to application/xml. For example,

/**
 *  The following example calls the 'CreateIncident' resource
 *  on a SOAP connector named '/mobile/connector/RightNow'.
 *  The request and response are in XML and not JSON.
 *
 */
var options = {
    contentType: 'appplication/xml;charset=UTF-8',
    accept: 'application/xml'
};

//Here we suppose an XML message has been
//stored in the XML variable
var body = xml;

req.oracleMobile.connectors.RightNow.post('CreateIncident', body, options).then(
  function(result){
    //result.result  contains  the response XML
    res.status(result.statusCode, result.result);
  },
  function(error){
    res.status(500, error.error);
  }
);

Remember to wrap your XML in a SOAP envelope. Your XML request must contain the entire SOAP envelope (including any SOAP headers):

<?xml version="1.0" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemad.xmlsoap.org/soap/envelope">

  <SOAP-ENV:Header>
    <!-- Add any SOAP headers here -->
  </SOAP-ENV>

  <SOAP-ENV:Body>
    <!-- Add the Body element here -->
  </SOAP-ENV:Body>

</SOAP-ENV:Envelope>

If you configured a security policy on the connector that requires a SOAP header to be sent in the message, that header is added automatically to the envelope you provide so you don’t need to include it in your message. You can see an example of an XML request wrapped in a SOAP envelope in Testing Your Connector.

Security Policy Types for SOAP Connector APIs

When determining what policies to set, consider whether connection to the service involves transmitting proprietary or sensitive information. A few reasons for adding security policies are:

Ensuring confidentiality by encrypting messages
Ensuring the integrity of the data transmitted by using digital signatures
Authenticating the source or destination

From the Security section, you can select one or more Oracle Web Services Manager (Oracle WSM) security policies, including SAML, Username Token, and HTTP Basic Authentication. Oracle WSM supports a wide range of security standards, including Authentication Policies and Authorization.

Security Policy Type	Description
HTTP Basic Authentication	HTTP Basic authentication allows an HTTP user agent to pass a user name and password with a request. It's often used with stateless clients, which pass their credentials on each request. It isn't the strongest form of security though because basic authentication transmits the password as plain text so it should be used only over an encrypted transport layer such as HTTPS.
Security Assertion Markup Language (SAML)	SAML is an XML-based open standard data format that allows the exchange of authentication and authorization credentials among a client, an identity provider, and a service provider. The client makes a request of the service provider. The service provider verifies the identity of the client from the identity provider. The identity provider obtains credentials from the client and passes an authentication token to the client, which the client then passes to the service provider. The identity provider verifies the validity of the token for the service provider and the service provider responds to the client.
Username Token	A username token is supplied by a web services client as a means of identifying the requestor by using a user name, and optionally by using a password or password-equivalent to the web services provider.

Ask yourself the following questions to determine what kinds of security policies you need:

What are the basic requirements of your security policy? Do you need to authenticate or authorize users? Do you require only message protection, do you need both?
If you need only authentication, do you need a specific type of token and where will the token be inserted?
If you need both authentication and message protection, will message protection be handled in the transport layer?

For a list of supported security policies, see Security Policies for SOAP Connector APIs.

For descriptions of security policy properties that you can override, see Security Policy Properties.

CSF Keys and Web Service Certificates

keystore.recipient.alias: The alias for this property is used to identify the certificate in the keystore.
keystore.sig.csf.key: The alias for this property is mapped to the alias of the key used for signing. If no value is selected, the default value, orakey, is used (for this release, the only valid value for this property is orakey).
keystore.enc.csf.key: The alias for this property is mapped to the alias of the private key used for decryption. If no value is selected, the default value, orakey, is used (for this release, the only valid value for this property is orakey).

Not all security policies contain all three properties. When you select a policy, you can see which properties are listed in the Policy Overrides. For example, if you selected wss11_username_token_with_message_protection_client_policy, you’ll see that you need to set only keystore.recipient.alias . However, if you selected wss10_username_token_with_message_protection_client_policy, you’ll need to set all three properties.

Note:

It isn’t necessary to set all the overrides for a policy; however, you should be familiar enough with the security policies that you’ve selected to know which overrides to set for each policy.

CSF keys, certificates, and their respective values are specific to the environment in which they’re defined. That is, if there are multiple environments, A and B, and you’re working in environment A, 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 environment B. It is also possible for keys with the same key name but with different values to exist in multiple environments.

Editing a SOAP Connector API

If you need to change some aspect of a connector API, you can as long as it’s in the Draft state. After you publish an API, the API can’t be changed.

To edit a SOAP Connector API:

Click and selectMobile Apps > Connectors from the side menu.
Since at least one connector API exists, the Connectors page is displayed.
Select the draft SOAP Connector API that you want to edit and click Open.
You can filter the list by version number or status. You can also sort the list alphabetically by name or by last modified date.
Edit the fields for general information, ports, and security policies as needed.

Remember you can always click Save and Close to save your current changes and finish the rest of your changes later.
Save your changes if you didn't select the option to always save the configuration before testing when you created the API.
Test your changes.

Your edited version is still in a Draft state and you can continue to edit your connector API until you’re satisfied with the configuration. At that point, you’re ready to publish your connector API. A published connector API can’t be changed. If you need to make changes, you can create a new version of the connector API.

Using Your Connector API in an App

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 connector-calling1.png follows

Description of the illustration connector-calling1.png

Troubleshooting SOAP Connector APIs

Sometimes a connection fails because the service URL provided is untrusted. You can add the URL to the list of trusted URLs at trustedsource.org. To learn more about what happens if you provide an untrusted URL and other common errors that can occur when configuring your connector API, see OMCe Policies and Values.

Caution:

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

SOAP Connector API Scope

To be sure you’re creating a valid SOAP Connector API in OMCe, keep in mind the following WSDL constraints:

Only SOAP version 1.1 and WSDL version 1.2 are supported.
Only the WS-Security standard is supported. Other WS-* standards, such as WS-RM or WS-AT, aren’t supported.
Only document style and literal encoding are supported.
Attachments aren’t supported.
Of the possible combinations of input and output message operations, only input-output operations and input-only operations are supported. These operations are described in the Web Services Description Language (WSDL) Version 1.2 specification.

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

Create ICS Connector API. You create an unbound ICS connector API with the Integration Cloud Service Connector API wizard.
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.
Connect to the ICS Instance. OMCe locates the ICS instance via the service URL provided.
Discover the Integrations. When authentication is confirmed, a list of active integrations in the ICS instance is displayed.
Select an Integration. You select an integration instance from a list of the integrations.
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.
Test the ICS Connector API. You test the endpoint using mobile user credentials.

Here’s how the connector API works at runtime:

Description of ics_runtime_flow.png follows

Description of the illustration ics_runtime_flow.png

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.
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.
Runtime credentials are passed from ICS to either the on-premises agent or to a single cloud service to access the selected service integration.
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:

Creation: You’ve named the API and provided a description. Once created the API exists in a Draft state.
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.
Discovery: OMCe locates the ICS service and obtains instances of the active integrations available from the service.
Configure: You’ve selected (or created) a CSF key for the security policy and provided your runtime credentials.
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.

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.
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
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.
Click Create.
Tthe General page of the ICS Connector API wizard is displayed.
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.
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.
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

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

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.
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
Click Save.
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.

Click Integrations in the navigation links at the top of the wizard.
The page displays only the integration you originally selected.
Click Refresh on the Integration page of the wizard.
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.
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.
Select the active integration you want from the list after the connection is completed.
Click Save.
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

Click the Security navigation link.
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.
Enter a brief description of the key's purpose.
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).
Repeat the password in the confirmation field.
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:

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.
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.
Add one or more request or response HTTP headers as needed.

Description of the illustration ics_test_headers.png

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"
}

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

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.

Using Your Connector API in an App

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

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.

Fusion Applications Connector APIs

Oracle Mobile Cloud Enterprise (OMCe) enables you to create Fusion Applications (FA) Connector APIs to connect to Oracle Fusion Applications. As a service developer, you can create connector APIs to make it easier to call these external services from the implementations of your custom APIs.

A Fusion Applications Connector API enables a mobile backend to use and expose data from one or more resources available from an Oracle Fusion Applications instance.

How Fusion Applications Connector APIs Work

A Fusion Applications Connector API enables a mobile backend to use and expose data from resources available from Fusion-based software-as-a-service (SaaS) instances, such as Oracle Human Capital Management Solution (HCM), Oracle Supply Chain Management (SCM), and Oracle Customer Relationship Management Solution (CRM). These suites of modular services help you with customer and employee management, sales and supply chain management, and more.

Use the Fusion Applications Connector API wizard to quickly and easily create a connector API with a customized selection of resources from a Fusion Applications service or Fusion-based service.

Here are the some of the advantages to using a Fusion Applications Connector API:

Makes it easier for customer to explore Fusion-based services through resource discovery.
Makes it easier for you to see all the resources, child resources, and resource attributes available in a given resource instance.
Lets you provide easy to identify and comprehend user-friendly names and descriptions for the resources and their attributes in the connector.
Provides a rich test client that lets you test with Fusion Applications query parameters.

Fusion Applications Connector API Flow

Here’s how the design-time flow for a Fusion Applications Connector API design-time goes:

Description of fa_designtime.png follows

Description of the illustration fa_designtime.png

Connector Creation phase. An unbound Fusion Applications Connector API is created with the Fusion Applications Connector API wizard.
Connection phase. Design time credentials are passed and a connection to the Fusion Applications instance is made. The design time credentials are saved in the Credentials Store Framework (CSF) in OMCe. The Fusion Applications service description, the Fusion Applications Describe, is retrieved from the external service.
Resource Discovery phase. OMCe locates the Fusion Applications instance via the Describe URL provided. When authentication is confirmed, OMCe downloads and parses the Describe resource and displays the list of resources exposed by the Fusion Applications service. The resources list is examined and the desired resources to access from the custom code are enabled.

In addition, descriptions for each attribute may be provided. Attribute values are available only at runtime and can’t be changed during design time.

Whenever you enable or disable resources or refresh the list of available resources, the changes are time stamped and tracked in a work area. Each instance of the connector API has one work area and the contents of that work area are saved as part of the configuration when the connector API is saved.
Attribute Setting phase. Attributes are selected or de-selected based on the requirements for the connector. Values for resource attributes are modified as needed.
Runtime Security phase. The Oracle Web Services Manager (Oracle WSM) security policy to be used at runtime is configured.
Testing phase. The configuration is saved. The enabled resources are displayed on the Test page and tested. Mobile user credentials are provided to test the connector API.

Here’s how the runtime flow goes:

Description of the illustration fa_runtime.png

Custom code calls the Fusion Applications Connector API. Information is then passed to the connector implementation. The implementation extracts the payload from the request.
The connector implementation checks whether or not the resource is enabled. If the endpoint is a GET request, a fields query parameter is added to the request so that the attributes returned by the Fusion Applications service are limited to only those attributes that were enabled for the resource at design time.
Runtime credentials (which are based on the security policies selected during design time) are added to the request and the request is sent to the Fusion Applications service.
Information is passed back from the Fusion Applications service to the connector API and finally back to the custom code.

How Do I Create a Fusion Applications Connector API?

The Fusion Applications Connector API wizard will walk you through the following stages of creating the connector API:

Setting Up the Basics. Name the API and provide a description. When you click Create, the API exists in a Draft state.
Connecting To and Selecting Resources. Locate the Fusion Applications service through the Describe URL that you provide and select the resources available from the service.
Selecting Attributes. Choose the attributes for each resource and child resource.
Setting the Runtime Security. Select the runtime security policies you need to connect to the runtime Fusion Applications instance.
Testing the Connector API. Test your endpoint to validate the connection to the service.

Setting the Basic Information for Your Fusion Applications Connector API

Before you begin configuring your connector, you must provide some initial basic information like the connector API name, a brief description, and a local URI (from which the connector API will available to the custom code):

Click and selectMobile Apps > Connectors from the side menu.
The Connectors page appears. If no connector APIs have been created yet, you'll see icons for REST, SOAP, ICS, and Fusion Applications. When at least one connector API exists, you'll see the connector landing page where existing connector APIs are listed. You can filter the list to see only the connector APIs that you're interested in or click Sort to reorder the list.
Click Fusion Applications if this is the first connector API to be created or New Connector and select Fusion Applications.

Each time you create a Fusion Applications Connector API, the New Fusion Applications Connector API dialog appears. This is where you enter the basic information for your new connector API.

Description of the illustration fa_create.png
Identify your new Fusion Applications Connector API by providing the following:
1. 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, myFAServiceAPI.
  For new connectors, a default version of 1.0 is automatically applied when you save the configuration.
2. 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, myFAServiceAPI.
  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.
3. 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.
After you've filled in all the required fields, click Create.The connector API is created and the General page of the Fusion Applications Connector API wizard is displayed.
Set the timeout values if needed.
Connecting to the Fusion Applications 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 of the network policies for the environment that you’re working in from the Administration page. Otherwise, ask your mobile cloud administrator for the values. To learn about environment policies, see Policies in Managing Oracle Mobile Cloud, Enterprise.

Description of the illustration conn_timeouts.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, then the default value (20 seconds) of the environment-level HTTP Read Timeout policy is applied.
- HTTP Connection Timeout: The time (in milliseconds) spent connecting to the remote URL. A value of 0mms means an infinite timeout is permitted.
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 edit your configuration when it's in a Draft state. You can always click Cancel at the top of the General, Rules, and Security wizard pages to cancel that particular configuration operation. You’ll be taken back to the Connector APIs page.
Click Next (>) to go to the next step in configuring your connector API.

Connecting to a Fusion Applications Instance

This is where you specify the Oracle Fusion Applications instance that you want to create a connection to via the Describe resource.

Making a connection consists of the following actions:

Providing the Describe URL to access the metadata of the Fusion Applications instance that you want
Providing access authentication (that is, your design time credentials)
Connecting to the server hosting the resources

You perform these operations on the Resources page of the Fusion Applications Connector API wizard.

Creating a Fusion Applications Instance Connection

Click the Resources navigation link.

Description of the illustration fa_resources1.png
In the Describe URL field, enter the address of the describe resource where the Oracle Fusion Applications instance can be accessed.
Use the describe resource to retrieve the metadata of a resource, which includes the fields and attribute values in the resource, the resource operations, and any child resources.
You get the Describe URL from the administrator of the Oracle Fusion Applications.

The URL takes the form http://host:port/api-name/resources/version/resource-path/describe.

For example: https://myhost:8080/CommonAPI/resources/1.1/incidents/describe.

You can save time by verifying that the URL you’re providing is trusted at trustedsource.org, otherwise, even if you’re connector API is configured correctly, the connection will fail. See Common Custom Code Errors.
Enter the user name and password that you were given to access the resource.
These are the design time credentials that enable you to access the Oracle Fusion Applications instance. You should’ve received these credentials when you registered with Oracle Fusion Applications.
Click Connect.
The resources in the Fusion Applications instance are retrieved. Making the connection can take a few minutes. You can stop the connection by clicking Abort in the Connecting dialog to stop the process. You’ll be returned to the Resources page.

After the connection is made, the Describe URL and your design time credentials are preserved for this connector API.

Selecting Fusion Applications Resources

When the connection to the server hosting the resources is made, the Resources page of the wizard displays a list of all the resources in the given Oracle Fusion Applications resource instance. You create a custom configuration by selecting a combination of top-level resources and child resources. You can see the address of the server hosting the fusion application services (http://host:port/api-name/resources/version) in the Service Root field along with the design time credentials user name above the resources.

A list of resources is displayed on one side of the Resources page. All the resources are unselected by default. Select at least one resource to include it in your Fusion Applications Connector API configuration. When you select a resources, its description, resource paths, and any child resources are displayed in the right panel.

Select a resource to enable it and add it to the connector API configuration.

If the list is long, enter a resource name or its description in the Search field to locate a resource.

When you perform a search and the resource is a child of another resource, it’s displayed at the same level as the parent resource in the list. Child resources are displayed in the form <parent_resource>/<child_resource>.

If you change your mind about a selection, you can disable a resource to exclude it by selecting it again. If the resource has child resources, the parent resource and all of its child resources are removed
Select a resource to see its details, including any child (nested) resources in the right panel of the page.

Description of the illustration fa_resources2.png

The details panel always shows the top-level resource and all of its child resources even if the resource you currently have selected in the resources list is not a top-level resource.

Click Refresh to get the most up-to-date list of resources. When you click Refresh, the current list of resources is discarded. To get the latest set of resources, OMCe must make a connection to the Describe resource again. You’ll get a confirmation dialog asking you to confirm that you want to discard the current set of resources. If you click Confirm, you’ll be taken back to the initial display of the Resources page where you’ll have to re-enter the Describe URL and your design time credentials.
(Optional) Provide a friendly name for the resource or a description in the Name field in the Details section.

Friendly names for resources are displayed on the following Attributes page.

The Collection and Single Item paths for the top-level resource, which you can see just above the child objects are the relative paths at which the resource collection and the single item resource are available. These paths are relative to the service root shown at the top of the page.
(Optional) Select individual child resources to include in your configuration.

Click Child Objects to include all the child resources of the selected top-level resource in your configuration

All child resources are displayed at the same level. That is, nested child resources are not visibly distinct in the list.

Each child resource is listed in the form of a relative path of the collection containing the child resource.

Click Remove in the dialog box to continue or Cancel to stop the removal.
(Optional) Provide a friendly (identifiable) name for the child resource in the Name field.
Click Next (>) to go to the next step in configuring your connector API.

Setting Resource Attributes

On the Attributes page, you can select the optional attributes you want for each of your selected resources. Any required attributes are automatically added to the configuration. Select a resource from the Resources list, view the available attributes for the resource in the next column, and then select the specific attributes you want to include in the connector configuration:

Click the Attributes navigation link.

Description of the illustration fa_attributes.png

On the Attributes page, you’ll see three columns. The first column, Resources, is the list of resources you previously selected. The second column, Attributes, lists all the attributes that you can select for a particular resource. The last column, Selected Attributes, lists required and optional attributes that are pre-selected for you. When you select an attribute in the second column, it’s added to the list of selected attribute.
Select a resource from the Resources list.
Add an attribute for the selected resource in the Attributes to your configuration by clicking Select Attribute:

Description of the illustration fa_select_attrib.png

Use your browser’s search function to locate specific attributes.

Click Select All to move all the attributes to the Selected Attributes list.
(Optional) Click an attribute in the Selected Attributes list and provide a friendly name and description for it:

Description of the illustration fa_attribute_description.png

Click Remove All to clear all attributes except the required ones from the list.
Click Save to save your configuration.
If you change your mind about the attributes your want, remove the ones you don’t want (don’t worry, they’ll be added back to the Attributes list) and make new selections.
Click Next (>) to go to the step in configuring your connector API.

Editing the Fusion Applications Connector API

If you know that the resources available through the describe resource have changed, you can refresh it to see the most up-to-date list of resources.

Note:

As long as the Fusion Applications connector API is in Draft state, you can edit the connector configuration

Click the Resources navigation link.
The page displays only the resources you originally selected.
Click Refresh.
When you click Refresh on the Resources page, you’ll be told that the current resources will be discarded. If you click Confirm in the dialog, you’ll be taken back to the initial view of the Resources page, where you’ll have to re-enter the Describe URL and your design time credentials. The URL is re-queried and the latest resources are then displayed. The refresh action doesn’t change any of the resource selections, friendly names, or descriptions that you’ve already provided. However, if you connect to a different service by entering a different Describe URL, you’ll see a completely new set of resources and you’ll have to provide friendly names for the ones you select.
Confirm the refresh action.
The Resources page is displayed at the authentication phase. The Describe URL and the design time credentials you provided previously are shown.
Click Connect to reconnect to the Fusion Applications service or enter a new Describe URL and your design time credentials if you want to change to a different Fusion Applications service.
Change the enabled settings for the resources as needed.
If you reconnected to the same service, your previous selections are kept.
Click Save.
Click Next (>) to go to the step in configuring your connector API.

Setting Runtime Security for the Fusion Applications Connector API

The Fusion Applications service determines the security policies used by the service. You have the option of selecting the corresponding client policies for the connector API from the Runtime Security page.

Description of the illustration fa_security.png

The Fusion Applications Connector API supports OAuth Authentication, HTTP Basic Authentication, and Security Assertion Markup Language (SAML). To learn more about these policies, see Security Policy Types for Fusion Applications Connector APIs.

Click the Runtime Security navigation link.
Select one or more security policies and move them to the Selected Policies column.
When you select a policy, you can see its description below the Available Policies panel.
Specify values for the policy overrides for each policy (if applicable) if you don’t want to use the default values.
To override a property, enter or select a value other than the default. For a description of policy properties, see Security Policy Properties.
To set a Credential Store Framework (CSF) Key value, see Providing a CSF Key.
Click Save to save your work or Save and Close to save your work and exit the Fusion Applications Connector API wizard.
Click Next (>) to go to the next step, testing the connector.

Providing a CSF Key

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

Provide a CSF Key in one of the following ways:

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.

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.
Click New Key in the dialog and create a new basic (CSF) credentials key as described in Create a New CSF Key.

To learn about CSF keys, see CSF Keys and Web Service Certificates.

Creating a New CSF Key

Click the keys icon in the csf-key field.
Click New Key in the Select or Create a New API KEy dialog box.
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.
Enter a brief description of the key's purpose.
Enter your runtime credentials for the service to which you are connecting.
Contact your Fusion Applications administrator to obtain the credentials used to call the Oracle Fusion Applications service at runtime. Most likely, you’ll only need to do this once for each Fusion Applications instance (all services are called with the same app credentials).
Repeat the password in the confirmation field.
Click Save to continue working in the dialog.
The key name value appears 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, then select it from the Available Keys list and modify the fields as needed. To learn about CSF Keys, see CSF Keys and Web Service Certificates.

Setting a Web Service Certificate

Here the steps for setting the overrides for a Web Service certificate. However, for this release, don’t override the values for keystore.sig.csf.key because orakey is the only valid value for all of these certificate keys.

Select a security policy.
The properties for the policy are displayed in the Policy Overrides section.
Select an alias from the drop-down list in the field for the certificate key (certificate keys are denoted by the keystore prefix) and select an alias.
Unlike CSF Keys, you can’t modify a Web Service certificate. You can only select a different alias.

Only mobile cloud administrators can create a new Web Service Certificate. If you don’t know the alias for the certificate you want, ask your mobile cloud administrator for the alias. To set CSF keys and certificates from the Administration page, see Credentials (CSF Keys and Certificates) in Managing Oracle Mobile Cloud, Enterprise.

Testing the Fusion Applications Connector API

When you’ve finished configuring your Fusion Applications Connector API, test the endpoints. You test one endpoint at a time.

Click the Test navigation link.
Select the endpoint you want to test.
Endpoints are listed on the left side of the page. Enter a partial resource name in the filter field to narrow the list to make it easier to find the endpoint you want. When you select an endpoint, the method, the resource name, and the URI of service is displayed on right side of the page.
Set the default test credentials if you’re in the design phase and just want to see if your endpoints are valid, or if you want to test multiple endpoints during the session. Otherwise, skip this step and fill out the fields in the Authentication section for each method you test.
1. Click Default Test Credentials at the top of the page.
2. Select a mobile backend to associate the API with and the version of the mobile backend.
3. If both OAuth and HTTP Basic Authentication are enabled for the mobile backend, select one in the Authentication Method field to use for testing.
4. Click Save to apply the credentials.
Click Request and expand Parameters.
When you select a GET method, all the available query parameters are displayed on the Request tab.
1. For a GET method, enter a parameter value.
  You can enter a value in the empty field next to the parameter description to test with or use the value, if any, provided in the example.
  
  Description of the illustration fa_testget.png
  
  Ordinarily, when invoking Fusion Application services, you could use the expand parameter to include the data for a child resource in a response when querying the parent resource. However, in the Fusion Applications connector, field parameters are implicitly added to the requests sent to the Fusion Application service.
  
  Note that the service is unable to handle the field parameters in the request and the expand parameter when both are used together.
  
  To ensure that data for both the parent and child resources are included in the response, you must add field parameters that explicitly list the attributes for both parent and child. For example, let’s say you had a parent resource, employee, with the attributes FirstName and LastName and the child resources, directReports, assignments, and photo with the respective attributes, PersondId, AssignmentName, and Image. You’d add a field parameter with the following values:
```
fields=FirstName, LastName; directReports:PersonId; assignments:AssignmentName; photo:Image
```
  If you do use the field parameter, be aware that the values that you provide in the parameter override the selections you made on the Attributes page.
2. (Optional) Click Example to view the example body, if one was provided. For methods other than GET, enter an alternate example to test with by clicking Use Example. The provided example body is copied into the text box. You can edit the example as needed.
3. (Optional) Click Schema to view the request body schema if one was provided.
Expand HTTP Headers and click Add HTTP Header to add a header.
Select the header that you want to include for testing purposes and provide a value in the text field.
Expand Authentication, select the mobile backend and its version that are associated with this API, and enter your mobile user credentials. If both OAuth and Http Basic Authentication are enabled for the mobile backend, select one in the Authentication Method field to use for testing.
Click Response.
Expand the status code and click Example or Schema to review the example or schema for the response body, if you provided one.
Click Test Endpoint.
Test Endpoint toggles to Cancel Test when you click it. If you want to stop the test for any reason, then click Cancel Test.
If you want to make changes to the testing parameters, click Reset to clear all the fields.

To be sure your connector API configuration is valid, you should test it thoroughly (not just from the Connector API Test page) before publishing it. You should also test the custom API (with its implementation) that uses this connector API. Essentially, if you’re ready to publish the connector API, then you should also be ready to publish the custom API that calls it.

If you need to make changes to a connector API that's in the Published state, create a new version of it. For information on creating a new version, see Creating a New Version of a Connector in Managing Oracle Mobile Cloud, Enterprise.

Getting the Test Results

Test results are displayed at the bottom of the Test 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

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.
404 NOT FOUND	Error due to an invalid connector ID. An associated connector with the given ID couldn’t be found.
500 INTERNAL SERVER ERROR	General error when an exception is thrown on the server side.

Security Policy Types for Fusion Applications Connector APIs

You'll need to set a security policy to protect the information you want to send or receive. When determining what policies to set, consider whether the connection to the service involves transmitting proprietary or sensitive information. Adding a security policy ensures the authentication and authorization of the data transmitted.

From the Security page, you can select one or more Oracle Web Services Manager (Oracle WSM) security policies, including OAuth2, SAML, and HTTP Basic Authentication.

Security Policy Type	Description
OAuth2 and the Client Credential Flow	OMCe supports OAuth2, a system where an Authentication server acts as a broker between a resource owner and the client who wants to access that resources. Of the different flows (security protocols) offered by OAuth2, the Client Credentials Grant Flow is used in OMCe to secure connections. This flow is used when the client owns the resources (that is, the client is the resource owner).
HTTP Basic Authentication	HTTP Basic authentication allows an HTTP user agent to pass a user name and password with a request. It's often used with stateless clients, which pass their credentials on each request. It isn't the strongest form of security though as basic authentication transmits the password as plain text so it should only be used over an encrypted transport layer such as HTTPS.
Security Assertion Markup Language (SAML)	SAML is an XML-based open standard data format that allows the exchange of authentication and authorization credentials among a client, an identity provider, and a service provider. The client makes a request of the service provider. The service provider verifies the identity of the client from the identity provider. The identity provider obtains credentials from the client and passes an authentication token to the client, which the client then passes to the service provider. The identity provider verifies the validity of the token for the service provider and the service provider responds to the client.

For a list of the security policies supported for Fusion Applications Connector APIs, see Security Policies for Fusion Applications Connector APIs. For descriptions of security policy properties that can be overridden, see Security Policy Properties.

CSF Keys and Web Service Certificates

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. A credential can hold user name and password combinations, tickets, or public key certificates. This data is used during authentication and authorization.

A Web Service Certificate allows the client to securely communicate with the web service. It can be a trusted certificate (that is, a certificate containing only a public key) or a certificate that contains both public and private key information. Web Service Certificates are stored in the Oracle WSM keystore. You set the overrides by selecting an alias from the drop-down list for the property, keystore.sig.csf.key. The alias for this property is mapped to the alias of the key used for signing. If no value is selected, the default value, orakey, is used (for this release, the only valid value for this property is orakey).

When you select a policy, you can see which properties are listed in the Policy Overrides.

Note:

It isn’t necessary to set all the overrides for a policy; however, you should be familiar enough with the security policies that you’ve selected to know which overrides to set for each policy.

CSF keys, certificates, and their respective values are specific to the environment in which they’re defined. That is, if there are multiple environments, A and B, and you’re working in environment A, 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 environment B. It is also possible for keys with the same key name but with different values to exist in multiple environments.

To set CSF keys and certificates from the Administration page, see Credentials (CSF Keys and Certificates) in Managing Oracle Mobile Cloud, Enterprise.

Using Your Fusion Application Connector API in an App

To use a connector in a mobile app, you first have to wrap calls to the connector API in a custom API and deploy that API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.

This allows the app to access the connector's functionality by calling the custom API. 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.

Alternatively, you can do this automatically. See Generating Custom APIs for Connectors.

You make calls to connector APIs using JavaScript code in the custom API's implementation. When you implement a custom API, you can view the available connectors and their details in a special version of the API Catalog that’s available to custom APIs. (The API Catalog that’s available to client apps doesn’t contain connector APIs.)

Troubleshooting Fusion Applications Connector APIs

A great source of debugging information are the system message logs. 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.

Caution:

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

You won't be able to test a Fusion Applications connector that hasn't been modified since June 2017 unless you save the connector first. Saving the connector regenerates the RAML from the descriptor. You can see when the connector was last modified by selecting it on the Connectors page and expanding the History panel.