Temenos Microservices Adapter for Object Services

The Temenos Microservices Adapter is an interface supported in Object Services from Fabric V9SP5 GA onwards. The adapter allows you to connect to the back-end Temenos Microservices via Object Services.

IMPORTANT: The Temenos Microservices adapter only supports Open API (Swagger) 3.0 specification. It supports uploading a Swagger file along with external reference files.

IMPORTANT: Supports more than one Swagger definition file in a . ZIP file.

Use Case:

Currently, any team trying to connect to Temenos microservice must use Fabric JSON services to implement microservices manually. When the team should modify request payloads, each required JSON template must be changed manually, which is time-consuming as well.

Using the Temenos Microservices adapter in object services, you can upload a valid Swagger JSON file containing all APIs to connect to the hosted microservices. The object service retrieves the metadata from the uploaded Swagger file and displays all the APIs as back-end operations in the Object services. You can use an existing Swagger engine to connect to hosted back-end APIs. So you can use the object services capabilities to link microservices APIs for these objects. For more information on Fabric Object Services, refer to Object Services.

The Temenos Microservices adapter helps you to improve the Fabric app development aspects as follows:

  • To access microservices back-end operations in an object service.
  • To manage APIs definitions with OpenAPI spec, instead of changing individual JSON integration services.
  • To upgrade newer versions of APIs definitions is faster. You need to upload a newer version of the Swagger JSON file to the adapter to get the latest APIs definitions.
  • To create a new data model to link microservices: You can create your custom app data model and map it to microservices operations.

The following sections help you create a Temenos Microservices object service.

Creating a Temenos Microservices Object Service

Configuring a Temenos Microservices End-point Adapter

To configure a Temenos Microservices in object service, you need to upload a Swagger file and a Swagger external reference file(s) containing specifications for the required APIs to the service.

  1. In your Quantum Fabric Console > Fabric Apps, click ADD NEW to create an app.
  2. Under Configure Services, click the Objects tab, and click CONFIGURE NEW to create an object service.
  3. In the Object Service Definition tab, configure the service definition parameters. For more information, refer to the following sections.
    ParameterDescription

    Name

    Specifies the name that Fabric uses to identify the service on the console.

    Version

    Specifies the version number of the service. The version number ranges from 1.0 to 999.99.

    If you create a new service, the version number is 1.0 by default, and it cannot be changed.

    Description

    Specifies the description of the service that is displayed on the console.

  4. From the Endpoint Type list, select the Temenos Microservices on the Object Service Definition page.
  5. Under Swagger File, click UPLOAD FILE to select your Swagger File.
    ParameterDescription
    Swagger File

    Specifies the JSON,or YAML file that contains the required API specifications. You can also upload a zip file that contains the JSON or YAML file along with external reference files, if any.

    To upload an OpenAPI specification file, click UPLOAD FILE, and then select a file from your local system.

    After you upload a file, Fabric displays connection parameters based on the OpenAPI spec version that is mentioned in the file.

    NOTE: In the following sections, all references (screen-shots, objects, operations, and mapping) are based on the sample Swagger JSON file for the Service Request microservice.

    IMPORTANT: It supports uploading a Swagger file along with external reference files.

    IMPORTANT: If the extension files are empty and there are references in the main JSON file to schemas/custom fields of these extensions, an error message will be popped up. To prevent the error message, you need to add dummy schemas/custom fields to the extension files.

    For example,

    1. You have uploaded a mircoservices zip file provided by the Infinity microservices team. The path for uploading the zip file: Object Services > Service Definition page > Swagger File.


    2. In case the uploaded zip file contains empty extension files whose references are present in the main JSON file, an error window will pop up when you click on the Mapping tab > Mapping > <Object> of the Object Service in the Fabric Console.

    “Failed to fetch metadata. Schema definition not present for referenced schema : customFields.”

    - You will be redirected to this documentation page when you click on here.
    - You will be redirected to the previous page in Console when you confirm OK.

    If the main OpenAPI file contains a reference to a schema from external files, for example:

       ServiceRequest: 
      properties: 
        account: 
          type: string 
          description: Account Id 
          example: '87907' 
        requestIn: 
          $ref: 'srmsExternalRef.yaml#/components/schemas/requestIn' 
        signatoryApprovalRequired: 
          type: string 
          description: signatory Approved or Not 
          example: true
    • Make sure the external reference file exists in the zip.
    • The schema should be present in that file. Otherwise the console will throw an error when you try to create a verb and map an operation.

      The srmsExternalRef.yaml file would look like this: 

      Components: 
  schemas: 
    serviceReqRequestIn: 
          type: object 
          properties: 
            xyz: 
                type: string 
                description: Generic serviceReq ID 
                example: ORD127REDFDSAS 
          description: Request In for ServiceReq 
          example: 
            checkIssueId: SB.2406 
            note: CreateNew 
    requestIn: 
          type: object 
          properties: 
          description: Request Load for Creating ServiceReq 
          example: 
            checkIssueId: SB.2406 
            note: CreateNew
    • If you do not have fields in a schema, you can keep an empty properties field, as mentioned in the requestIn schema of the above example.
  6. Enter the following connection parameters. The adapter will provide an option for you to enter an header Key and value:

    ParameterDescription

    xapikey

    Specify the header value "xapikey" for AWS. If you want to have AWS authentication, you can add this value in the service configuration. This value will be added to the header parameters while connecting to the microservice.

    xfunctionkey

    Specify the header value "xfunctionkey" for Azure. This is a common value for all Microsoft Azure deployments.

    If you want to have Azure authentication, you can add this value in the service configuration. This value will be added to the header parameters while connecting to the microservice.

    Authorization

    		These details are generated by the adapter itself, for Docker on-premises.

    Server URL

    Specifies the URL of the server that hosts the APIs. The default URL is the first Server URL in the specification file.

    For information about how Fabric parses the URLs, refer to the Miscellaneous section.

    For example: https://subdomain.site.com/version

    Server Description

    Specifies the description for the server that is specified by the URL.

    For example: Development Server

    ParameterDescription

    Use Existing Identity Provider

    Specifies the identity provider that you want to use to authenticate users for the service.

    You can select any Identity Service that is created on the Quantum Fabric cloud.

    For information about creating an Identity Service, refer to Configure Identity Service.

    NOTE: For more information on Externalizing Identity Services, refer to Replace the Identity Service references in a Fabric app.

    FieldDescription

    Custom code

    Specifies any custom JAR files that you want to associate with the service.

    To associate a JAR file with the service, follow either of the following steps.

    • From the Select Existing JAR list, select a JAR file from the Quantum Fabric cloud
    • Click Upload New, and then select a JAR file from the file explorer

    NOTE: For on-premises instances of Fabric, make sure that the JAR file that is built on the same JDK version that is used to install the Fabric Integration.

    API Throttling

    Specifies whether Fabric must limit the number of request calls in a minute.

    To use API Throttling, follow these steps.

    1. In the Total Rate Limit box, type a required value. This limits the total number of requests that are processed by the service.
    2. In the Rate Limit Per IP box, type a required value. This limits the number of requests based on the IP Address of the request.

    You can also override throttling from the Quantum Fabric App Services Console. For more information, refer to Override API Throttling Configuration.

  7. After you configure all the parameters, click SAVE.

    NOTE: If you want to create objects to the service, click SAVE & CONFIGURE.

Configuring a Data Model for Temenos Microservices

NOTE: In the following sections, all references to screen-shots, objects, operations, and mapping are based on the sample Swagger JSON file for the Service Request microservice.

  1. Click the Data Model tab.
  2. Click Add to create an object and fields as per your Swagger details. The following sample object is created for GetRequestDetails and fields:
    ObjectFields

    GetRequestDetails

    • account

    • dateFrom

    • dateTo

    • partyId

    • status

    • subType

    • type

    NOTE: Currently, the option to auto-generate the data model is not supported for this adapter.

    For more information on creating objects and fields, refer to Configuring a Data Model.

Mapping Operations to Back-end Methods for Temenos Microservices

  1. Click the Mapping tab.

  2. Select an object and click Add to create an operation.

  3. Associate a back-end operation to the object verb. To do this, select the Data Model Verb from the list and select a back-end operation from the Operations list.

    NOTE: All the operations listed in the Swagger file are displayed here. You can map the required back-end operations to verbs for objects.

    The following object verbs are linked to back-end operations.

Visual Mapping Operations to Back-end Methods for Temenos Microservices (for Requests and Responses)

The base mapper1 is created for request and response by default.

Click EDIT to add your custom mapping for request and response parameters, if required.

Request Mapping

For object request calls, you can now map the objects to the back-end operations using the Visual/XML mapping, as shown below:

Response Mapping

For object response calls, you can now map the back-end operations to the objects using the Visual/XML mapping, as shown below:

For more information on mapping, methods (verbs) mapping, custom verbs, and mapper elements, refer to Mapping Operations to Back-end Methods.

NOTE: You can view the service in the Data Panel feature of Quantum Visualizer. By using the Data Panel, you can link back-end data services to your application UI elements seamlessly with low-code to no code. For more information on Data Panel, click here.

Limitations

Map-record issue

When you pass an input payload where you have a scenario of mapping a record within a record, the Visual Mapper generates wrong XML mapper.

For instance, if the input payload is:

{
  "id": 0,
  "category": {
    "id": 0,
    "name": "string"
  },
  "name": "doggie",
  "photoUrls": [
    "string"
  ],
  "tags": [
    {
      "id": 0,
      "name": "string"
    }
  ],
  "status": "available"
}

where category is a record within a record.

The XML generated sample code does not include nested records as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mapper xmlns="http://www.kony.com/ns/mapper">  
  <map inputpath="request_in" outputpath="request_out">    
    <set-param inputpath="id" outputpath="id"/>    
    <set-param inputpath="name" outputpath="name"/>    
    <set-param inputpath="photoUrls" outputpath="photoUrls"/>    
    <set-param inputpath="status" outputpath="status"/>     
    <map inputpath="category" outputpath="category">      
      <set-param inputpath="id" outputpath="id"/>      
      <set-param inputpath="name" outputpath="name"/>    
    </map>    
    <map inputpath="tags" outputpath="tags">      
      <set-param inputpath="id" outputpath="id"/>      
      <set-param inputpath="name" outputpath="name"/>    
    </map>  
  </map>
</mapper>

For scenarios like this where we have a record within a record, the tag should be <map-record></map-record> instead of <map></map>.

To achieve this case, use the custom XML mapper and generate the XML as below:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mapper xmlns="http://www.kony.com/ns/mapper">  
  <map inputpath="request_in" outputpath="request_out">    
    <set-param inputpath="id" outputpath="id"/>    
    <set-param inputpath="name" outputpath="name"/>    
    <set-param inputpath="photoUrls" outputpath="photoUrls"/>    
    <set-param inputpath="status" outputpath="status"/>     
    <map-record inputpath="category" outputpath="category">      
      <set-param inputpath="id" outputpath="id"/>      
      <set-param inputpath="name" outputpath="name"/>    
    </map-record>    
    <map inputpath="tags" outputpath="tags">      
      <set-param inputpath="id" outputpath="id"/>      
      <set-param inputpath="name" outputpath="name"/>    
    </map>  
  </map>
</mapper>

Visual Mapper XML generation issue - dataset as back-end response

When a backend response is a dataset (array), the Visual Mapper generates wrong XML mapper. To achieve this case, use the custom XML mapper and generate the XML as below:

IMPORTANT: Responses with Datasets cannot be generated by the Visual Mapper.

For example, Backend Response sample code:

{
  "officer": [
    {
      "officerkey": "1",
      "description": "Implementation",
      "processDate": "2022-03-02 10:21:26.0"
    },
    {
      "officerkey": "10",
      "description": "Chief Treasury Dealer -Interbank",
      "processDate": "2022-03-02 10:21:27.0"
    },
    {
      "officerkey": "10009",
      "description": "Implementation"
    
    }
  ]
}

The sample visual mapper looks something like this:

The XML generated sample code is as follows:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>                
<mapper xmlns="http://www.kony.com/ns/mapper">
  <map inputpath="response_in" outputpath="response_out">
    <map inputpath="getListOfOfficer" outputpath="officer">
      <set-param inputpath="officer/officerkey" outputpath="key"/>
      <set-param inputpath="officer/description" outputpath="description"/>
      <set-param inputpath="officer/processDate" outputpath="message"/>
    </map>
  </map>
</mapper>

This kind of mapping iterates through getListOfOfficer dataset and fetches officerkey, description and processDate only from the first object in the officer array, but the iteration has to happen through all the objects under officer array of getListOfOfficer.

The Mapper generated Response sample code:

{
  "records": [
    {
      "description": "Implementation",
      "message": "2022-03-02 10:21:26.0",
      "key": "1"
    }
  ],
  "opstatus": 0,
  "httpStatusCode": 200
}

For correct XML mapper response, the XML sample code should look like this

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mapper xmlns="http://www.kony.com/ns/mapper">
  <map inputpath="response_in" outputpath="response_out">
    <map inputpath="getListOfOfficer/officer" outputpath="officer">
      <set-param inputpath="officerkey" outputpath="key"/>
      <set-param inputpath="description" outputpath="description"/>
      <set-param inputpath="processDate" outputpath="message"/>
    </map>
  </map>
</mapper>

Or it can also look like this

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mapper xmlns="http://www.kony.com/ns/mapper">
  <map inputpath="response_in" outputpath="response_out">
    <map inputpath="getListOfOfficer" outputpath="">
      <map inputpath="officer" outputpath="officer">
        <set-param inputpath="officerkey" outputpath="key"/>
        <set-param inputpath="description" outputpath="description"/>
        <set-param inputpath="processDate" outputpath="message"/>
      </map>
    </map>
  </map>
</mapper>

Now the Mapper response sample code is correct:

{
   "records": [
    {
      "description": "Implementation",
      "message": "2022-03-02 10:21:26.0",
      "key": "1"
    },
    {
      "description": "Chief Treasury Dealer -Interbank",
      "message": "2022-03-02 10:21:27.0",
      "key": "10"
    },
    {
      "description": "Implementation",
      "key": "10009"
    }
  ],
  "opstatus": 0,
  "httpStatusCode": 200
}

Dynamic Map Support for Objects with No Pre-defined Fields (Free form objects)

If there is a scenario where an object/record with no pre-defined fields can be passed in runtime during the service call, the Visual Mapper generates not a proper XML.

Here the requestIn is of type object with no pre-defined fields. Here the parent level mapping doesn’t happen and hence there will be no reference to that object in the generated visual mapper XML. These kinds of objects are supported with dynamic-map.

Therefore, whenever we encounter such cases, we should add a <dynamic-map></dynamic-map> tags wherever required.

So, The XML should be like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<mapper xmlns="http://www.kony.com/ns/mapper">
<map inputpath="request_in" outputpath="request_out">
<set-param inputpath="account" outputpath="account"/>
<set-param inputpath="partyId" outputpath="partyId"/>
<set-param inputpath="serviceReqConfId" outputpath="serviceReqConfId"/>
<set-param inputpath="signatoryApprovalRequired" outputpath="signatoryApprovalRequired"/>
<set-param inputpath="subtypeId" outputpath="subtypeId"/>
<set-param inputpath="typeId" outputpath="typeId"/>
<set-param inputpath="uuid" outputpath="uuid"/>
<dynamic-map inputpath="requestIn" outputpath="requestIn">
</dynamic-map>
</map>
</mapper>

Miscellaneous

The OpenAPI Specification (formerly: Swagger specification) is a framework used to define interfaces with which you can design, build, document, and consume REST APIs.

For more information about OpenAPI 3.0, you can refer to the following articles:

OpenAPI 3.0

  • With the OpenAPI 3.0 Specification, you can add multiple URLs to your definition and also include parameters in the URL. For more information, refer to A Visual Guide to What's New in Swagger 3.0.
    • While creating a service for OpenAPI 3.0 in Quantum Fabric V9 ServicePack 2, you can select only one URL as the Server URL. If your specification file contains multiple URLs, Fabric picks the first URL by default.
    • You can change the URL before you publish the service to the run time by reconfiguring the service before a publish. For more information, refer to Service Reconfiguration.
    • Parameters in the URL are not supported. Make sure that you add static server URLs to your specification file.
  • The trace HTTP method is not supported and the APIs that use the trace method are ignored.

    APIs that use other HTTP methods are parsed by Fabric to create operations.
  • If the HTTP response code is not 200, the console displays the response from the back-end server as is.
  • OpenID Connect (OIDC) is not supported for authentication.
  • Callbacks, which are used to define Webhooks, are not supported. Links, which are used to define the output of one operation as input for another operation, are not supported. Make sure that you remove Callbacks and Links from your OpenAPI 3.0 spec before you uploading it to Fabric.
  • Serialization of parameters, which includes style (defines the delimiter for multiple parameters) and explode (specifies whether objects of an array are generated as separate parameters), is not supported.
  • Fabric does not parse or validate examples from the specification file.