Integrate External Applications

6 Integrate External Applications

How You Integrate External Back-End Applications

Your application may come predefined with integrations to other Oracle cloud services. You can also integrate other applications, such as third-party applications, with the existing applications in your topology.

To integrate with external Back-end applications, use the Industries Framework. For example, to integrate:

Customer Relationship Management (CRM) software
Billing software and custom tax engines
Enterprise Resource Planning (ERP) software

To interact with external front-end applications, set up the front-end applications to call the corresponding TM Forum (TMF) Open APIs per your business needs. For example, you can connect a web store UI to create customer accounts or a Website for customers to manage their own accounts.

You integrate external Back-end applications to route API requests, publish event data, and receive necessary event data from those applications. To integrate an application, you start by adding the system description and provide the necessary details to connect to that application. And, to route requests or publish events to that application, you define routing conditions and events that your external application wants to listen to.

Before you integrate an external Back-end application, do the following:

If you're using a custom API for this integration, register that API. If you're using TM Forum (TMF) Open APIs, you can skip this step. To add a custom API, see the Set Up Custom APIs chapter.
Determine the APIs you want to associate with your external application for routing requests and receiving data. You can associate any Open API or your own API with the external application. For example, you can associate the Account Management API with your external customer master to route account-related requests.
Check which APIs generate the events that you want your external application to listen to. You can use TMF Open APIs or your own API for listening to events. For example, you can register Oracle Communications Billing and Revenue Management to use the Account Management API to listen to account data for managing accounts.
If the external application doesn't support TMF Open APIs, build an adapter for the TMF Open APIs in the external application. The adapter is responsible for transforming the data shared between the applications into the format that each application understands. This enables your external application to interact with your application. You can build the adapter on a cloud service (for example, Oracle Fusion applications) or an on- premises system (for example, Oracle Siebel applications).

Note:
The Oracle cloud services that are preintegrated with your application use TMF adapters to interact. You don't have to build your own adapter for these applications. For example, Care Experience uses the adapter in Oracle Communications Billing and Revenue Management to interact with that application. For integrating Oracle cloud services that support customer, account, or party management, you can use the corresponding TMF adapters.

To integrate an external back-end application, you must do the following:

Add the external application that you want to integrate with your application.
Set up the workspace connections for your external application.
Add the additional routing conditions for context-based routing by using the gatekeeperRules API.

Add the External Application

You use systemDescriptors API to add the external or target application.

Note:

Ensure that you don't update default system descriptors to integrate any new external application. To replace a preintegrated target application with an external application, create descriptors by using the POST method of systemDescriptorsAPI. In case, if you lose a default system descriptor, create a service request on My Oracle Support to revert your changes.

Here's how you add your external application:

Create a payload with the target application details described in this table.

Field	Description
`target-name`	A unique name of the target application.
`system`	The type of the target application.
`domain`	The domain of the target application.
`apis`	The details of the APIs that connect with the target application to send requests. Ensure that you specify the URL prefix to connect to the APIs. You must specify at least one API and one resource for the target application.

Call the systemDescriptors API by running this cURL command or by using a REST API client:
```
curl-H Authorization: Bearer <accessToken> https://<hostName>/admin/{workspace}/systemDescriptors/ -X POST -H "Content-Type: application/json" -d @api-data.json
```
Where:
- <accessToken> is the OAuth access token for your account.
- <hostName> is the URL for your CX Industries Framework API Gateway.
- <workspace> is the path parameter for the production or test workspace. For example, 02 for the test workspace and 01 for the production workspace. If you are calling the API using FA API Gateway, you can skip this parameter.
Here is a sample request payload for defining the external tax engine as the target application by using the systemDescriptors API:
```
{
"target-name":"Tax Engine", "external":{
"offered-apis":[
{
 

"api-name":"taxCalculation", "api-number":"orcl-200",
"api-version":"v1",
"url-prefix":"cx/industry", "api-resources":[ "CalcTaxes",
"Healthcheck"
]
}
]
},
"system":"Taxation", "domain":"Taxes" "type": "external"
}
```
Now that you have added your external application,add the connections details for each workspace connection.

Set Up Workspace Connection

Here's how you add the workspace connection details for your external application:

Note:

Ensure that you don't update default connection descriptors to integrate any new external application. To replace a preintegrated target application with an external application, create connection descriptors by using the POST method of connectionDescriptors API. In case, if you lose a default connection descriptor, create a service request on My Oracle Support to revert your changes.

Create a payload with the target application's connection details described in this table.

Field	Description
`system-descriptor`	The unique identifier of the descriptor defined for the target application.
`endpoint-name`	The name of the endpoint. This must be unique for each application. The endpoint can be an API or an adapter that acts as a bridge for the integration of the applications.
`endpoint-url`	The Endpoint URL of the target application.
`user-name`	The user name for the endpoint. Required for the Basic Auth authentication types.
`password`	The password for the endpoint. Required for the Basic Auth authentication types.
`identity-uri`	The URL from which your communications application retrieves an authorization token. Required for OAuth authentication type.
`client-id`	The client ID your authorization server assigns to your communications application. Required for OAuth authentication type.
`client-secret`	The client secret assigned to your communications application and used to retrieve an authorization token. Required for OAuth authentication type. The OAuth scope that your communications application requests access to and that's granted with the token. Appears for OAuth authentication type.
`scope`	The OAuth scope that your communications application requests access to and that's granted with the token. Appears for OAuth authentication type.
`code`	Specifies the connection type. For integrating external applications, the connection type must be external.
`server-audience`	Leave this blank if you're using Oracle Identity Cloud Service as the identity provider. If you're using an external identity provider, create a service request on My Oracle Support at https:// support.oracle.com for updating this value for your identity provider.

Call the connectionDescriptors API by running this cURL command or by using a REST API client:
```
curl -H Authorization: Bearer <accessToken> https://<hostName>/admin/{workspace}/connectionDescriptors/
-X POST -H "Content-Type: application/json" -d @api-data.json
```
Where:
- <accessToken> is the OAuth access token for your account.
- <hostName> is the URL for your CX Industries Framework API Gateway.
- <workspace> is the path parameter for the production or test workspace. For example, 02 for the test workspaceand 01 for the production workspace. If you are calling the API using FA API Gateway, you can skip this parameter.
The API returns the response with the application descriptor ID once configured.
Here is a sample request payload for providing the external tax engine's connection details by using the connectionDescriptors API:
```
"routing":
{
"system-descriptor": "SYSTEM_DESCRIPTOR_ID", "endpoint-name": "taxation-rest",
"endpoint-url": "http://TAXATIONGW_IP:PORT", "fabric-facing-auth": {
"oidc-client-credentials": { "client-id": "OIDC_CLIENT_ID",
"client-secret": "OIDC_CLIENT_SECRET", "identity-uri": "https://IDENTITY_URI", "scope": "OIDC_SCOPE"
}
},
"type": "external"
}
```
If you're using OAuth for authorizing access to APIs, provide the OAuth client credentials as specified in the sample payload. Instead, if you're using HTTP basic authentication, provide the basic credentials, such as:
```
"basic":
{
"username": "admin",
"password": "admin"
}
```
Now that you have added the connection details, update the routing map to connect with the external application to send requests.