HCL Microservices Adapter for Object Services

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

Important: The HCL 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 HCL microservice must use Foundry 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 HCL 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 Foundry Object Services, refer to Object Services.

The HCL Microservices adapter helps you to improve the Foundry 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 HCL Microservices object service.

Creating a HCL Microservices Object Service

Configuring a HCL Microservices End-point Adapter
Configuring a Data Model for HCL Microservices
Mapping Operations to Back-end Methods for HCL Microservices
Visual Mapping Operations to Back-end Methods for HCL Microservices (for Requests and Responses)

Configuring a HCL Microservices End-point Adapter

To configure a HCL 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.

In your VoltMX Foundry Console > Foundry Apps, click ADD NEW to create an app.
Under Configure Services, click the Objects tab, and click CONFIGURE NEW to create an object service.

In the Object Service Definition tab, configure the service definition parameters. For more information, refer to the following sections.

Parameter

Description

Name

Specifies the name that Foundry 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.

From the Endpoint Type list, select the HCL Microservices on the Object Service Definition page.

Under Swagger File, click UPLOAD FILE to select your Swagger File.

Parameter

Description

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, Foundry displays connection parameters based on the OpenAPI spec version that is mentioned in the file.

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.

OpenAPI uploaded 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.

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 Foundry 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:

ServiceRequest: 
  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.

Enter the following connection parameters. The adapter will provide an option for you to enter an header Key and value:

Connection Parameters

Parameter	Description
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 Foundry 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`

Authentication

Parameter

Description

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 Foundry cloud.

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

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

Advanced

Field

Description

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 Foundry cloud

Click Upload New, and then select a JAR file from the file explorer

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

API Throttling

Specifies whether Foundry must limit the number of request calls in a minute.To use API Throttling, follow these steps.

In the Total Rate Limit box, type a required value. This limits the total number of requests that are processed by the service.

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 Foundry App Services Console. For more information, refer to Override API Throttling Configuration.

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 HCL 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.

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

Object	Fields
`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 HCL Microservices

Click the Mapping tab.
Select an object and click Add to create an operation.
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 HCL 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.

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.voltmx.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 instead of .

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.voltmx.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.voltmx.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.voltmx.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.voltmx.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 tags wherever required.

So, The XML should be like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
<mapper xmlns="http://www.voltmx.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 VoltMX Foundry V9 ServicePack 2, you can select only one URL as the Server URL. If your specification file contains multiple URLs, Foundry 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.
Extension data is not supported as Foundry parses only one specification file. If your specification file contains references to any external files, the console displays an error.

For example, if your file contains the following code snippet, the console displays an error:

{
    "$ref": "PayInOutExtension.json#/components/schemas/customFields"
    }

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 Foundry 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 Foundry.
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.
Foundry does not parse or validate examples from the specification file.