27 Fusion Applications Connector APIs
Oracle Mobile Cloud Service (MCS) 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.
When configuring the connector API, you need to enter runtime credentials each time you need to access a Fusion Applications service, but customers of Fusion Applications-based services should only have to sign in once to the mobile app to access the Oracle Cloud application. You can create an app that lets users sign in just once with their identity domain credentials. To see how to set up single sign-in, see Configuring Oracle Cloud Applications as the Identity Provider.
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 MCS. The Fusion Applications service description, the Fusion Applications Describe, is retrieved from the external service.
-
Resource Discovery phase. MCS locates the Fusion Applications instance via the Describe URL provided. When authentication is confirmed, MCS 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.
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
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
Selecting 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.
Setting Resource Attributes
Editing the Fusion Applications Connector API
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 configurationSetting 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). To learn more about these policies, see Security Policy Types for Fusion Applications Connector APIs.
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
Setting a Web Service Certificate
keystore.sig.csf.key
because orakey
is the only valid value for all of these certificate keys.
Testing the Fusion Applications Connector API
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.
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 |
MCS 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 MCS 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 MCS, 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 Providing 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 CSF Keys and Certificates.
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.
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 Environment Policies and Their 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.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.