Custom Data Adapters on Quantum Fabric

Data Adapters are reusable services with defined operations that work similarly to other services at run time. You can use the Quantum Fabric console to create or upload a custom data adapter. The adapter can then be used to create Integration or Object services.

Why use Custom Data Adapters?

You can create a custom data adapter from your back-end API definition with multiple services. The definitions can be in an XML, RAML, or Swagger format and are readily available as back-end connectors.

When to use Custom Data Adapters

To import an existing service definition

Consider a scenario where you want a reusable service for your Fabric apps, and the service definition is available in a format that is compatible with Fabric.

Instead of creating services from scratch, you can import the service definition to Fabric as a data adapter and use it to create Integration and Object services.

To create a service with RAML or Swagger (Open API) code

Consider a scenario where you have a RAML or Swagger (Open API) code with API definitions that you want to use for your Fabric apps.

Instead of creating RAML or Swagger services from scratch, you can upload the file to Fabric and create a custom data adapter. You can then add metadata for the adapter (such as the name, version, and logo) and use it to create Integration and Object services.

Get Started

You can import, create, and manage custom data adapters on the Custom Data Adapters tab in the API Management section.

Quantum Fabric supports the following types of data adapters:

  • Fabric App-based data adapter
    If you have already configured a Fabric service that is connected to your back-end server, you can import it as a custom data adapter.
  • RAML or Swagger (Open API) based data adapter
    If your back-end server can expose API definitions in a RAML or Swagger format, you can use it to create a data adapter on Fabric.

Import a Data Adapter

You can import a data adapter to Fabric if it is in a compatible format. For more information about the format, refer to Create a Data Adapter Offline section.

To import a data adapter to Fabric, follow these steps:

  1. From the API Management section, go to the Custom Data Adapters tab.
  2. Click IMPORT.
    The Import Data Adapter window appears.
  3. Drag a file onto the upload window.
    Alternatively, you can browse for a file on your system.
  4. After the file is uploaded, verify the details of the adapter, and then click IMPORT.
    The data adapter is imported and can be managed from the Fabric console.

NOTE: You can also import data adapters from Temenos Forge (formerly Quantum Marketplace) by clicking IMPORT FROM TEMENOS FORGE. On the Import Data Adapter from Kony Marketplace window, select a data adapter, and then click IMPORT.

You can then use this Custom Data Adapter to create services and operations in your Quantum Fabric Apps.

Create a Data Adapter on Fabric

You can create a custom data adapter on Fabric by uploading a RAML or Swagger (Open API) file. The file must contain API definitions that you want to use on Quantum Fabric.

To create a data adapter on Fabric, follow these steps:

  1. 1. From the API Management section, go to the Custom Data Adapters tab.
  2. Click CREATE DATA ADAPTER.
    The Create Data Adapter window appears.
  3. Based on the type of file that you want to upload, select RAML or Open API (Swagger).
  4. Drag a file onto the upload window.
    Alternatively, you can browse for a file on your system.
  5. After the file is uploaded, configure the details of the adapter.
    1. Under Definition, configure the following details:
      • Image: The image that is displayed as the adapter icon on the console
      • Adapter Name[Mandatory]: The name of the adapter that is displayed on the console
      • Asset Version[Mandatory]: The version number of the adapter (in the X.X.XX format) that is displayed on the console
      • Min Version Required: The minimum version of Quantum Fabric that is required for the data adapter
      • Adapter Description[Mandatory] - Description that Quantum Fabric displays on the console.
      • Upload to Marketplace after creation - Select this check box if you want to upload your Custom Data Adapter to the Quantum Marketplace.
    2. Under Connection Parameters, you can configure parameters that are passed to the data adapter. Every parameter requires the following details:
      • Parameter Name: The name (key) of the parameter at the back end
      • Type: The data type of the parameter
      • Value: The value of the parameter at the back end

      These parameters are displayed while creating a service with the data adapter.

    3. In the Adapter Description box, type a description of the data adapter. Adding a description is mandatory to create a data adapter.
    4. Select the Upload To Marketplace after creation check box if you want to upload the data adapter to Temenos Forge (formerly Quantum Marketplace).
  6. After configuring the parameters, click CREATE.
    The data adapter is created and can be managed from the Fabric console.

API-based Custom Data Adapter Example

Following is an example of a Swagger (Open API) data adapter that connects to the Swagger PetStore. The data adapter is created by using a sample Swagger (petstore.json) file.

To create an Integration service with the Swagger PetStore data adapter, follow these steps:

  1. Create a custom data adapter and configure the details. For this example, name the adapter PetStoreExample.
  2. Create an Integration Service on Quantum Fabric and select the Service Type as PetStoreExample.
  3. Click ADD OPERATION.
    The Operations List tab appears.
  4. From the drop-down list, select the operations that you require, and then click ADD OPERATION.
  5. Use the operations to make service calls to the Swagger PetStore.

Create a Data Adapter Offline

To create a data adapter offline, you must create a zip file that contains the required file in a Fabric-compatible structure. The structure of your file depends on whether it is RAML/Swagger based, or Fabric App based.

RAML or Swagger (Open API) Based Adapter

For a data adapter that is based on RAML or Swagger (Open API), the root of the zip file must contain the following files:

  • Properties file [Mandatory]: A file that contains the metadata of the data adapter; this file must be named properties.json

    /* This file contains metadata about the Swagger PetStore Data Adapter */
{
 "createdBy" : "Quantum",
 "propertiesVersion": "1.0",
 "itemName": "PetStore",
 "displayName": "PetStore",
 "description": "PetStore",
 "icon": "petstore.png",
 "assetVersion": "1.0",
 "createdMFVersion": "7.3",
 "adapterType":"swagger",

/* You can also configure dynamic connection properties for your data adapter */ 
 "connectionManager":
 {
  "connectionProperties":
  [
   {
    "displayName": "Parameter One",
    "description": "This is the first connection parameter",
    "name": "ParamOne",
    "order": 0
   },
   {
    "displayName": "Parameter Two",
    "description": "This is the second connection parameter",
    "name": "ParamTwo",
    "order": 0
   }
  ]
 }
}

    IMPORTANT: The value for the adapterType key depends on the type of file that is used. The possible values are raml and swagger.

  • RAML or Swagger File [Mandatory]: A file that contains the API definitions of your back-end server; for example, pet-store.json

  • Image [Optional]: An image that is used as the icon for the data adapter; for example, petstore.png

    NOTE: Ensure that you provide the name of the image in the icon key of the properties.json file.

For more information, refer to the sample PetStore.zip file.

After configuring the required files, you can compress them into a zip file and import it into Quantum Fabric.

Fabric App-based Adapter

For a data adapter that is based on service definitions from Quantum Fabric apps, the root of the zip file must contain the following files and folders:

  • Properties file [Mandatory]: A file that contains the metadata of the data adapter; this file must be named properties.json

    /* This file contains metadata about the Google News Data Adapter */
{
 "createdBy" : "Quantum",
 "propertiesVersion": "1.0",
 "itemName": "GoogleNews",
 "displayName": "GoogleNews",
 "description": "GoogleNews",
 "icon": "icon.png",
 "assetVersion": "1.0",
 "createdMFVersion": "7.3",
 "adapterType":"mf_app",

/* You can also configure dynamic connection properties for your data adapter */
 "connectionManager":
 {
  "connectionProperties":
  [
   {
    "displayName": "Parameter One",
    "description": "This is the first connection parameter",
    "name": "ParamOne",
    "order": 0
   },
   {
    "displayName": "Parameter Two",
    "description": "This is the second connection parameter",
    "name": "ParamTwo",
    "order": 0
   }
  ]
 }
}

    IMPORTANT: The value for the adapterType key must be mf_app.

  • Service Folders [Mandatory]: Folders that contain definitions of Fabric services; the name of the folders must match the service name.

    The name of the first level folder must match with the service name. The name of the second level folder must be services and it must contain the service definition file.

    In the following example, NewsObject is the name of the Object Service and newsService is the name of the Integration Service.

    GoogleNews.zip/

    |- newsService/services/newsService.xml

    |- NewsObject/services/NewsObject.xml

      

  • Image [Optional]: An image that is used as the icon for the data adapter; for example, petstore.png

    NOTE: Ensure that you provide the name of the image in the icon key of the properties.json file.

For more information, refer to the sample GoogleNews.zip file.

After configuring the required files and folders, you can compress them into a zip file and import it into Quantum Fabric.

Manage Data Adapters

The Custom Data Adapters tab in the API Management section displays the data adapters that are uploaded to your Fabric environment.

You can click View in the ASSOCIATED APPS column to fetch a list of apps that are associated with a data adapter.

You can also view additional options by clicking the ellipsis (three-dot) menu; the options are as follows:

IMPORTANT: To delete a data adapter, ensure that it is not linked to any services. Otherwise, the console displays an error.