Launch Cloud Service External Mapping Services Integration

4 Launch Cloud Service External Mapping Services Integration

Launch has productized publishing capabilities with Siebel, BRM - wherein we follow a low-code approach to publish into runtime applications. This has been made possible using the OAS mapper capability (using JSON path function to query for an element within JSON data). This allows you to map entities between source (Launch) and target (runtime systems) using the provided set of java classes (standard functions) for transformation such as valueMap, defaultValue, splitString, conditionalValueMap, and so on. However, there might arise a need to add your own mapping functions to support any custom transformation logic that might be required which is not available in the product. This improves the business agility to distribute catalog definitions by adding your business specific mapping functions.

Integration of Launch, Siebel, and BRM requires creation and upload of mapper file that will point to your custom mapping. A default mapper file is provided by Launch. You can update the same file with invocation calls to the custom mapping function. For more detail, see Integrate Launch with Siebel CRM and Pricing Design Center (BRM). This integration of external mapping function supported in the mapping file involves a series of steps. These include declaring the function signature within the mapping file, setting up the wiring, and developing the third-party function service, among other components.

Overview

This chapter outlines the Integration of Third-Party Mapping Function service to support extension of current productized mapping capabilities supported by mapper file. This chapter also provides detailed step-by-step instructions for integrating a third-party mapping function service.

Assumptions: The external function service developed by Customers, ensures high availability and low latency. The function service implementation should expose APIs as described in this document.

Note:

Raise a Service Request with Oracle Support before you start adding external mapping services for Integration to Siebel CRM and BRM.

Purpose

The purpose of this integration is to enable Launch to interact with customer developed mapping service having preTransform and transform API based on swagger definition. This integration provides enhanced functionality by allowing the Launch Integration microservices to extend the mapping capabilities currently offered by mapper file.

Scope

This chapter covers the entire process from initial configuration in Fabric to final testing in Launch, including API setup, authentication configuration, and Launch-specific settings.

Prerequisites

Before beginning the implementation, ensure you have the following:

Access to the CXIF Host environment (e.g., https://your-cxif-host-example.com).
Customers Admin privileges for running/admin APIs.
Authentication credentials for the third-party Function Service (OAuth2, Basic Auth, or OCIHttpSignature).
Familiarity with RESTful APIs and JSON.
Downloading Third Party Function Service Swagger. See Appendix for more details.
Access to curl or Postman for API testing.
Knowledge of the specific service being integrated.
Knowledge of mapper file, its constructs, and its usages.

Related Guides

Table 4-1 contains information about other useful sources of information for the integration process.

Table 4-1 Related Guides for External Mapping Services Integration

Reference	Description
Integrate Launch with Siebel CRM and Pricing Design Center (BRM)	Describes the setup and implementation of the edit and upload mapper file.
Implement CX Industries Framework	Describes the setup and implementation of the CX Industries Framework required for Launch integrations.

System Architecture Overview

The integration involves three main components:

Fabric: Acts as the API management and routing layer. Fabric also have Integration microservices for uploading Mapper file and perform publish/migration.
Client’s Third-party Function service: The third-party mapping function service provided and hosted by client.
Launch: The UI for publish and Migration.

The flow of data is as follows:

Launch > Third-party Mapping Function Service

Figure 4-1 Integrating Launch, Fabric, and the third party function service

Description of "Figure 4-1 Integrating Launch, Fabric, and the third party function service"

Step 1: The diagram illustrates the architecture for integrating Launch, Fabric, and the third party function service. Assuming the Third party Function Service is ready, the process begins with creating a TIC or Connection Descriptor in the Config microservice. This TIC specifies authentication method, credentials, and host information of the Third Party Function Service.
Step 2: The mapper file with the necessary mapping extension changes is uploaded. The file is stored in UCM.
Step 3: The user publishes or migrates the project.
Step 4: The Customer Function Service is called and returns the appropriate response.

Detailed Implementation Steps

Configuring Fabric

For Launch to talk to RMS, and the outbound call from RMS to “Third Party Function Service” to happen, there needs to be some configurations done in the CXIF fabric cluster to mediate the flow. This configuration is to be done using the CXIF Admin API’s. More details on the individual service can be found in the Related Guides section.

Create a New Connection Descriptor (TIC)

Connection Descriptor or TIC is where one would mention the host of the third-party function service deployed. Also, the authentication mode and the authentication secrets are to be passed in the request while creating TIC.

Supported authentication modes and sample requests for the same are provided below for reference.

Note:

Do not modify the fields endpoint-name, type, and system-descriptor. You can modify other fields as per your implementation

Sample Request:

POST https://{CXIFHost}/admin/connectionDescriptors
{
  "endpoint-name": "ThirdPartyMappingFunction",
  "endpoint-url": "https://your-host-example.com/",
  "fabric-facing-auth": {
    "oidc-client-credentials": {
      "client-id": "your-client-id",
      "client-secret": "your-client-secret",
      "identity-uri": "https://your-identity-provider.com/oauth2/v1/token",
      "scope": "your-scope"
    }
  },
  "type": "external",
  "system-descriptor": "thirdpartymappingfunction-ttd"
}

endpoint-url field should be the host of the service which interacts with the underlying third party function service.

fabric-facing-auth field should be where we decide the mode of authentication and the credentials for authenticating.

Replace placeholders with your actual third party mapping function service endpoint and OAuth2 credentials. Currently fabric supports two types of authentications. BasicAuth and OAuth2 (only client credentials is supported).

The sample payload for each type is as mentioned below.

Table 4-2 Sample Payload

Authentication Type	Sample Payload
Basic Auth	{ "system-descriptor": "thirdpartymappingfunction-ttd ", "endpoint-name": "ThirdPartyMappingFunction", "endpoint-url": "https://thirdpartyfunctionservice.dev.com/", "fabric-facing-auth":{ "basic":{ "username": "admin", "password": "password" } }, "type": "external" }
OAuth2	{ "endpoint-name": "ThirdPartyMappingFunction", "endpoint-url": "https://thirdpartyfunctionservice.dev.com/", "fabric-facing-auth": { "oidc-client-credentials": { "client-id":"48eb39a9a7cb4bc0b7761ebb8d3ada97", "client-secret":"adt2cdde-6c94-4be2-b525-fff575a9c3fc", "identity-uri": "https://idcs-322c58839e042ad2.identity.oraclecloud.com/oauth2/v1/token", "scope": "https://n6jfpge6uqfrum.apigateway.us-ashburn-1.oci.customer-oci.comurn:opc:resource:consumer::" } }, "type": "external", "system-descriptor": "thirdpartymappingfunction-ttd " }]

Authentication Type

Sample Payload

Basic Auth

{
       "system-descriptor": "thirdpartymappingfunction-ttd ",
       "endpoint-name": "ThirdPartyMappingFunction",
       "endpoint-url": "https://thirdpartyfunctionservice.dev.com/",
       "fabric-facing-auth":{
            "basic":{
                "username": "admin",
                "password": "password"
            }
       },
       "type": "external"
}

OAuth2

{
    "endpoint-name": "ThirdPartyMappingFunction",
    "endpoint-url": "https://thirdpartyfunctionservice.dev.com/",
    "fabric-facing-auth": {
        "oidc-client-credentials": {
            "client-id":"48eb39a9a7cb4bc0b7761ebb8d3ada97",
            "client-secret":"adt2cdde-6c94-4be2-b525-fff575a9c3fc",
            "identity-uri": "https://idcs-322c58839e042ad2.identity.oraclecloud.com/oauth2/v1/token",
            "scope": "https://n6jfpge6uqfrum.apigateway.us-ashburn-1.oci.customer-oci.comurn:opc:resource:consumer::"
        }
    },
    "type": "external",
    "system-descriptor": "thirdpartymappingfunction-ttd "
}]

Creating GKR (Gate Keeping Rule)

Once TIC is created, a default GKR will get created with endpoint-name ThirdPartyMappingFunction after 10 seconds.

Use the below get call to get the id of created GKR.

GET {{Fabric_APIGW}}/admin/gatekeepingRules

Response of this get call will be the list of GKR.

Sample Response

[
    {
        "endpoint-name": "ThirdPartyMappingFunction",
        "rule-name": "Generated gatekeeping rule for endpoint tmf632",
        "destination-selection": [
            {
                "api-id": "orclfunc-100",
                "api-version": "v1",
                "criteria": [
                    {
                        "rank": 1,
                        "resource-ids": [
                            "transform",
                            "preTransform"
                        ]
                    }
                ]
            }
        ],
        "id": "gkr-internal-rest-1234 "
    },
    {
        "endpoint-name": "pdc-test2",
        "rule-name": "Generated gatekeeping rule for endpoint pdc-test2",
        "id": "gkr-pdc-test2zgj5k"
    }
]

From the list of responses, the default GateKeepingRule for ThirdPartyMappingFunction can be considered. Use the id from the default GateKeepingRule of ThirdPartyMappingFunction to make the PUT call as shown below:

{{Fabric_APIGW}}/admin/gatekeepingRules/gkr-func7n7fw

Sample Payload

{
    "endpoint-name": "ThirdPartyMappingFunction",
    "rule-name": "Generated gatekeeping rule for endpoint func",
    "destination-selection": [
        {
            "api-id": "orclfunc-100",
            "api-version": "v1",
            "criteria": [
                {
                    "rank": 1,
                    "resource-ids": [
                        "transform",
                        "preTransform"
                    ]
                }
            ]
        }
    ],
    "id": "gkr-func7n7fw"
}

The POST call above will create the GKR.

Note:

Only the id field of the above payload needs to be changed and copied from GET call output. Other fields will remain unchanged.

Validating the Connection and Testing the API

After configuring Fabric, it's crucial to test the connection before proceeding to Launch configuration.

PreTranform API Test - Refer Appendix : Downloading swagger file.

Prepare a POST request:

https://<fabricHost>/api/01/apiIntegration/v1/preTransform with payload.

Sample Payload:

{
  "functionName": "customExternalMappingFunction",  // This function should be implemented by third party mapping function service.
  "inputJson": "{ “name” : “IPhone”, “id” : “2222”}” // This input is received from making source API calls and will be input for customExternalMappingFunction.
  "paramList": [red],  
  "contextParameters": [  
    {
      "Name": "JobId",
      "Value": "1234"
    }
  ]
}

Send the request and analyze the response. You should receive result in the format:

{
"result": { 
"valueType": "object",
"value": "{}”
}
}

For Pretransform, valueType can be either an object or an array, and value should be of same data type as mentioned in valueType.

Transform API Test - Refer Appendix : Downloading swagger file

Prepare a POST request:

https://<fabricHost>/api/01/apiIntegration/v1/transform with payload

Sample Payload:

{
  "functionName": " customExternalMappingFunction ",  // This function should be implemented by third party mapping function service.
  "inputJson": "{ “name” : “IPhone”, “id” : “2222”}” // The input is received from making source API calls and will be input for customExternalMappingFunction.
  "paramList": [],  
  "contextParameters": [  
    {
      "Name": "JobId",
      "Value": "1234"
    }
  ]
}

Send the request and analyze the response. You should receive result in the format:

{
"result": { 
"valueType": "object",
"value": "{}”
}
}

For transform, valueType can be either an object, an array, integer, string, or number and value should be of same data type as mentioned in valueType.

Changes in Mapper File

Maintaining versions and uploading Mapping File procedure can be referred from Integrate Launch with Siebel CRM and Pricing Design Center (BRM) guide. This section only describes the changes to be done in Mapping File.

Mapping File Changes for Transform and PreTransform

Figure 4-2 System Integration Flow

Description of "Figure 4-2 System Integration Flow"

In mapper file, source_request_spec defines the procedure of retrieving source data. After the retrieval of source data, pre transformation happens ( Figure 4-2 step 1). There is a field in target_request_spec called select_json_path, whose value defines the pre transformation logic. The value of select_json_path can be jaywayjson path or function or internal function.

For example, if “select_json_path “: “$”, this means that the entire payload beginning from root, will be selected transformations.

To further enhance the capability of select_json_path, a user can use his own defined functions (third-party functions) as a value of select_json_path (Figure 4-2 step 1.1), the below signature can be used. Once this signature is processed in runtime, the preTranform API is invoked with appropriate parameters. Refer PreTransform Test Sample Payload.

" select_json_path ": "@invokeExtFunction(customExternalMappingFunction, PRETRANSFORM, arg1, arg2…)"

The signature is explained below:

@invokeExtFunction is the signature to be used for calling third-party function service REST API.

customExternalMappingFunction is the function name that needs to be invoked by third party function service.

PRETRANSFORM is a keyword that indicates that function is called on the context of "pre-transformation" and respective API will get called.

arg1 and arg2 are optional parameters. There can be infinite optional parameters.

Once pre transformation is completed, transformation begins ( Figure 4-2 step 2). Component schema is the structure of payload that should be sent to target as payload to respective exposed API. Component schema contains different fields. Mostly fields are evaluated using jayway json path, but function and oracle internal functions are also supported. The third-party function service can be used with component fields as well (Figure 4-2 step 2.1 and step 2.2).

The following sample demonstrates how to specify function signature to invoke third party function service for transformation. Once this signature is processed in runtime, the transform API is invoked with appropriate parameters. Refer Transform Test Sample Payload.

"productName": {
  "type": "string",
  "description": "Description of this Employee",
  "x-oracle-map-data": {
    "json_path": "@invokeExtFunction(customExternalMappingFunction, TRANSFORM, params...)"
  }
}

@invokeExtFunction is the signature to be used for calling third party function service REST API.

customExternalMappingFunction is the function name that needs to be invoked by third party function service.

TRANSFORM is a keyword that indicates that function is called on the context of transformation and respective API will get called.

params is an optional parameter. There can be infinite optional parameters.

Testing Launch

Once the file is uploaded and all configurations are complete, along with the third party function service up and running, you can proceed with the publish and migration processes. The expected payload can then be verified accordingly.

Troubleshoot Integration Errors

Some of the integration errors and the troubleshooting tips are mentioned below.

Table 4-3 Integration Errors

Error Type	Error Details	Troubleshooting Tips
API configuration	"No corresponding routing solution found for: apiIntegration/v1/preTransform or Transform"	Check TIC configurations are correctly set.
Authentication	401 Unauthorized	Verify credentials and token expiration for External Function Service access.
Function not returning proper result	The supplied @invokeExtFunction response JSON is not of valid syntax.	Validate the return values using API definition mentioned in Appendix.
Network	A connection reset error	Check for any network restrictions or proxy settings that might interfere. If the service implemented is deployed on a cloud platform or on premise, make sure it is accessible over the web and cater to the proxy configurations.
Exception in logs	The transformation function @invokeExtFunction must contain at least one argument which specifies the API Path to be invoked as part of the REST URL.	Correct signature of invokeExtFunction as per documentation.