24 Connectors
In Oracle Mobile Hub, you use connectors to simplify calls to external services, such as enterprise systems and third-party APIs.
Mobile Hub 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 Mobile Hub’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 Mobile Hub.
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 Mobile Hub 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.
Create 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.
Basic Connector Setup
You can create a functioning connector by completing the first two pages in the REST Connector API wizard.
-
Click and select Development > 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:
-
API Display Name: The name as it will appear in the list of connector APIs.
-
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.
-
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.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. Essentially, if you’re ready to publish the connector API, you should also be ready to publish the custom API that calls it.
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.
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
andPUT
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
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:
Set 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 thecsf-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:
Test 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:
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 |
204 NO CONTENT |
Successful connection but no response body (used for |
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.
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, Mobile Hub 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 Mobile Hub 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).
Security and REST Connector APIs
Mobile Hub 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 Mobile Hub-specific authorization header is automatically set as theAuthorization
header. This originalAuthorization
header that’s set on the connector API request is used to pass only Mobile Hub authorization and is never passed through to the external service call. If you setOracle-Mobile-External-Authorization
on the request, the value of this header will be set asAuthorization
on the request to the external service. Set anOracle-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 theOracle-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 orBEARER
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 Mobile Hub is reused to authenticate with the other service.
-
An access token generated by a service is passed to an Mobile Hub 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 Mobile Hub 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 defaultAuthorization
header. On the Rules tab of the REST Connector UI, create a rule of typeHeader
forAuthorization
and provide a value. This approach isn’t recommended as usually theAuthorization
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 |
Mobile Hub 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 Mobile Hub 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?
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 Mobile Hub, 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.
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 thekeystore.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.
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.
Set 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:
-
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 bedirections/zones?origin=Pasadena
. Note that a simple concatenation of the URL isn’t done. -
If you're combining a remote URL with a query parameter
U?qp=a
with a default ruleqp=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 ruledestination=Anaheim
, the resulting URL should bedirections/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 URLdirections/zones?origin=Pasadena
, the result isdirections/zones?origin=Pasadena&date=2015–04_07T14:30:00.000Z
.
About 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.
Edit 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.
- Click and select Development > 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.
Use 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 Call a Connector API 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.
Troubleshoot 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 Override SSL Settings for Connectors for details.
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 Mobile Hub 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 Mobile Hub.
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 Mobile Hub 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.
Create 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.
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.
-
*.*.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.
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.
Set 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 selectDevelopment > 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. -
Identify your new SOAP 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,
myOrderApi
.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.
-
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.
-
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.
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.
-
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:
-
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.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.
Select 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.
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.
Set 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.
Set 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.
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:
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.
Test 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.
Get 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 |
---|---|
|
Successful connection. |
|
Error due to missing or invalid authentication token. |
|
Error due to user not having authorization or if the resource is unavailable. |
|
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.
Get 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, Mobile Hub 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 Mobile Hub 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).
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 API Timeouts.
-
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, Mobile Hub 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.
Mobile Hub 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 Test Your Connector.
Security Policy Types for SOAP 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 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
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 Mobile Hub, 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.
-
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 isorakey
). -
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 isorakey
).
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.
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.
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.
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.
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.
Use Your Connector API in an App
To use a connector in a mobile app, you need to have a custom API that can call the connector API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.
The syntax for a call to a connector API is the same as you would use when calling any other API from custom API implementation code.
Description of the illustration connector-calling1.png
When you implement a custom API, you can view the available connectors in the API Catalog tab in the API Designer. While creating your custom API, you might find it beneficial to open the Test page of the connector API so that you can refer to any headers, parameters, and schemas that you’ve configured for the connector API.
Troubleshoot SOAP 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
.
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. Be aware that this policy must be manually added to a policies.properties
file that you intend to export.
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 Mobile Hub, 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 Hub (Mobile Hub) 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
-
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. Mobile Hub 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.
-
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.
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: Mobile Hub 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.
Set the Basic Information for Your ICS Connector API
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.
Select or Create an ICS Instance Connection
Select an Active Integration
Edit 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.
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.
Set Runtime Security for the ICS Connector API
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
,orwss_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.
You can create a new key, or 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.
Create a New CSF Key
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.
Test the ICS Connector API
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.
Getting Diagnostic Information
You can view the response code and returned data to determine if your endpoints are valid. A response status other than 2xx doesn't necessarily mean the test failed. If the operation was supposed to return a null response, a response should show a 4xx code.
For every message that you send, Mobile Hub 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 Mobile Hub 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).
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 thewss_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 Mobile Hub, 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.
CSF keys and their values are specific to the environment in which they’re defined. That is, if the Development environment is selected, then only the CSF keys and certificates for the security policies in use by artifacts in that environment are listed in the CSF Keys dialog. A different set of keys and certificates will be displayed in another environment, such as Staging. It’s also possible for keys with the same key name but with different values to exist in multiple environments.
A CSF key can be deployed to another environment, however, because CSF keys are unique to an environment, only the key name and description are carried over to the target environment. You won’t be able to use that key in the new environment until it’s been updated with user name and password credentials by the mobile cloud administrator.
Use Your Connector API in an App
To use a connector in a mobile app, you need to have a custom API that can call the connector API. Such a custom API could also contain additional logic to process the data returned from the call to the connector.
The syntax for a call to a connector API is the same as you would use when calling any other API from custom API implementation code.
Description of the illustration connector-calling1.png
When you implement a custom API, you can view the available connectors in the API Catalog tab in the API Designer. While creating your custom API, you might find it beneficial to open the Test page of the connector API so that you can refer to any headers, parameters, and schemas that you’ve configured for the connector API.
Troubleshoot 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 Mobile Hub. -
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, Mobile Hub itself, the ICS instance that Mobile Hub 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. Be aware that this policy must be manually added to apolicies.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 Hub (Mobile Hub) 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:
-
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 Mobile Hub. The Fusion Applications service description, the Fusion Applications Describe, is retrieved from the external service.
-
Resource Discovery phase. Mobile Hub locates the Fusion Applications instance via the Describe URL provided. When authentication is confirmed, Mobile Hub 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:
-
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.
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.
Set the Basic Information for Your Fusion Applications Connector API
Connect 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.
Create a Fusion Applications Instance Connection
Select Fusion Applications Resources
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.
Set Resource Attributes
Edit 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.
As long as the Fusion Applications connector API is in Draft state, you can edit the connector configuration
Set Runtime Security for the Fusion Applications Connector API
The Fusion Applications Connector API supports OAuth Authentication, HTTP Basic Authentication, and Security Assertion Markup Language (SAML).
Provide 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.
Create a New CSF Key
Set a Web Service Certificate
keystore.sig.csf.key
because orakey
is the only valid value for all of these certificate keys.
Test the Fusion Applications Connector API
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 |
Mobile Hub 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 Mobile Hub 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. |
CSF Keys and Web Service Certificates
In Mobile Hub, 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 Provide a CSF Key.
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.
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.
To set CSF keys and certificates from the Administration page, see Credentials (CSF Keys and Certificates) in Managing Oracle Mobile Hub.
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 Call a Connector API 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.)
Troubleshoot 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.
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. 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.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.