External Application Provided API



Usecase

Let’s say you use Trello to make a list of your 'to-do' tasks, ‘Done’ tasks, etc. And you want to integrate Trello and Jira—to see all the info that is updated in Trello is reflected in Jira. You might be using Trello boards where there is a collection of cards that in turn contain lists. When you integrate with Jira, the boards in Trello could be mapped with Jira’s project, the Cards in Trello could be mapped with User Story in Jira, and finally, the Trello 'Lists' could be mapped with Jira’s 'Statuses' (Trello Boards <–>Jira Project, Trello Cards <-> Jira Entity Type, Trello List<-> Jira Status).

In the above mapping scenario, when you create a 'Card' in the Trello Board, a 'Story' will be created in Jira and will be viewable in Jira by Jira Users. To achieve this mapping, when you map the metadata of the applications, you could map Trello’s Board and Jira’s Project. As a Trello Board could have multiple values, for ex: TechService Board, Product Board, CustomerSupport Board, etc…, each board could be mapped to a different project in Jira.

ConnectALL's Universal adapter can help in the above scenario and make the integration of Trello and Jira possible.

Introduction

The 'External Application Provided API' approach is suitable when the application you want to integrate with provides a ReST API that ConnectALL can use for the following purposes:

  • To query/poll for changes to objects/entities
  • To read records/objects/entities from the other application
  • To put new records to the application, and
  • To put changes to records back to the application.

To adopt this approach, specify the application's API and data transformations in the ConnectALL Universal Adapter configuration screen. Once configured, ConnectALL will poll the other application using that application's ReST API. 

Universal Adapters can be created and configured directly through the UI, or by manually crafting a Universal Adapter Descriptor. The recommended approach is to use the UI. If you wish to manually craft a descriptor, use the attached file as a starting point. Note: The application type in the Adapter descriptor should be "ExternalApplication" to enable this style of Universal Adapter configuration.

Descriptor format for version 2.10.2 or belowDescriptor format for version 2.10.3 or above

The process of creating a Universal Adapter involves:

  • naming the adapter and specifying the Application Type, which is the type specified when you requested your Universal Adapter license,
  • providing an icon to be used within ConnectALL to represent that application,
  • specifying the fields the application uses (the fields you wish to map), 
  • specifying the application's metadata, such as entity types and projects,
  • specifying "schemes", which specify how to transform messages between your end application's API and ConnectALL's API (which is described under ReST API below), and
  • specifying how schemes are associated with application links via the metadata specified in both the scheme and in the application link.

The process of using a Universal Adapter involves:

  • creating a connection (see Connection Configuration here), just like you would for any other adapter, and
  • using that connection in an application link, just like you would for any other adapter.

Specify Fields and Metadata

To synchronize data with an application, ConnectALL needs to know about the fields that need to be synchronized, and any metadata required by the application. Examples of metadata for an application are project and issue type (or entity type). Those are two common pieces of metadata, but not all applications require those, and some require other pieces of information.

When configuring an application link, metadata is the info that you will see in the Entity Mapping tab. The fields you configure will be shown on the Field Mapping tab.

Metadata also is also how you form a relationship between different schemes and application links. For example, you might have issue-type metadata. There may be two issue types: Bugs and Stories. Further, you might need to specify an API for each issue type, such as one for Bugs and another for Stories. Or you might need a slightly different transformation spec for each. You can have one scheme for Bugs and another for Stories. Likewise, you might have one applink for Bugs (and bug-specific fields) and another applink for Stories (and story-specific fields). That piece of metadata for issue-type (Bugs vs Stories) ties the scheme to the application link.

Scheme Creation

ConnectALL would just love it if all the applications provided the same ReST API, and it would be even more awesome if they all used the ReST API specified below. Unfortunately, they don't. The ReST API below specifies how ConnectALL attempts to communicate with other applications. Schemes translate that API into the end application's API. Schemes translate both the requests and the responses.

API configuration is mandatory for the synchronization of records when you are using an External API provider. The API configuration (or) schemes can be configured at an adapter level and also at the metadata level for synchronization.

Follow the below procedure to configure an API:

  1. Click the cogwheel icon on the top right corner of the home page.
  2. Click Universal Adapters from the drop-down list. The universal adapter configuration page is displayed.

        

  3. Click View displayed against API Configuration. The Configuration screen is displayed. In the below screen, the +Add Scheme button is displayed If you have not created any schemes. If you have already created schemes, a '+' button will be displayed.

    Note that, in the version 2.10.9 and above, the Default tab is displayed (instead of the +Add Scheme button). It has a default template, where you can provide the details for the REST API configuration, headers, and metadata association.  You can also rename the <Default> scheme to a name of your choice.


  4. Click +Add Scheme to create a new scheme. The Create New Adapter Scheme screen is displayed.

        

  5. Enter the new scheme name in the Scheme Name field and click Create Scheme. The API configuration screen contains three sections listed below:
    1. ReST API Configuration
    2. Request Headers
    3. Metadata Association

                       

ReST API Configuration

The ReST API Configuration section (above screen) has the list of APIs supported by ConnectALL for the external API provider. The list of APIs supported are:

  • Query Modified records
  • Ready Record by ID - Mandatory
  • Create Record
  • Update Record

The following parameters should be configured for each API:

  • URL – ReST API URL for the operation
  • HTTP Verb –  HTTP verb for the operation. The available options are GET, POST, PUT and PATCH.
  • Request Spec Config – Request transformation spec for the operation can be configured in this section.
  • Response Spec Config –  Response transformation spec for the operation can be configured in this section.

The API URLs

As shown below, click the Configuration icon () against the operation and select a field from the URL Field Options list to add fields to the URL. This is a convenience mechanism. These fields can also be typed in manually. 

The option named 'fields' will add the “${fields[ValueSeparator:'='] [fieldSeparator:’&']}” expression in the URL field. You can edit the “ValueSeparator” and the “fieldSeparator” values to have the appropriate separators matching the API. For example, if the default expression is used, the URL pattern will be:

<APPLICATION_URL>/<API>?summary=Test&description=Test2

This is the pattern of the synchronization. In this example, the symbols “=‘ and ‘&’ will be used as the value and field separators.

The summary and the description are mapped in the application link itself.

Transformation Spec Config

Note the checkbox in the below image. The ability to send a Request Body is available only for Create Record and Update Record. The check box can be cleared when the operation doesn’t have any request payload required for the adapter. Further, it can be used in conjunction when the payload has to be sent in the URL instead of the request body.

ConnectALL expects a response body in response to API calls, but for Update Record, the response body is optional. For Update Record response specs, the check box can be cleared when the operation doesn’t have any response payload available from the adapter. For more information on Transformation Spec Configuration, click here.

                     


ActionDescription
Input Payload Sample payload to test the transformation spec
Load request samples

This hyperlink will be available only on the Request Spec config. When you click this hyperlink, it will load the sample request spec and you can modify it based on the required input. For the response spec, you have to provide a sample of the adapter’s response for the API.

Spec Type

The transformation spec type. The supported types are:

            • Jolt
            • Groovy
Transformation Spec Provide the transformation spec for the operation
Transformed Output

When you click Test Spec, the "Transformed Output" box will show the output of the transformation spec. 

Save - The transformation spec will be saved in the request. You can also save it in the database using the Save as Draft or Activate button on the parent page.

Request Header

Some ReST APIs require values to be sent in the "request header". In this section, you can configure any request header to be sent for all the APIs configured in the current scheme. 

              

To add a request header,

  1. Click the + Add header button to add a default header.
       

  2. Click on the KEY or the VALUE button to enter the values. Once you are in the edit mode, you can change the header key and the value. 
       

  3. Click outside the button after editing the value to return to the view mode. 
       

Metadata Association

You can configure the specific metadata for a scheme or make it as Default for all metadata by clicking the Default option. 

              

To configure the specific metadata for the scheme: 

1.

Click the Override option, and click +Add metadata.

The Metadatakey and Metadata Value button is displayed.



2.

When you click Metadata Key, it lists the entity names configured as part of the adapter descriptor. The Metadata Value option will load the entity values based on the selected Metadata Key.

3.Select the Metadata Key and Metadata Value and click Save against the metadata to save the configuration. 

Note

A scheme can be configured in the Draft or in the Active state by clicking Save As Draft or Activate buttons respectively. Note that the adapter should have at least one default scheme and can have ’n’ number of the overridden schemes. If there are overridden schemes configured while synchronizing, the application will compare the metadata configured with the overridden schemes and apply the scheme. If the metadata information is not matching, the Default scheme will be applied. 

Test Configuration

Note: The test configuration feature is available from version 2.10.26

ConnectALL allows you to test the configuration of an External application provided API. The test configuration option is available for Query Modified Record, Record by ID, Create Record and Update Record operations. To test the configuration of a scheme, it should be associated with an app-link.  To test a configuration,

  1. Click the Configure link against the Api Configuration option. The API configuration screen will be displayed.
  2. Click the test configuration icon ) displayed against an API. The Input screen will display the Application Link drop-down list.
  3. Select an app-link and click Test Config.

Once the testing is complete, the Response Payload section will display the results.

Depending upon the API you choose to test the configuration, the fields will be displayed in the Test API Configuration screen. Suppose if you click the Test Configuration button against the Query Modified records API, the date fields will be displayed for you to select a date range as displayed below. select the date range and click Test Config.

If you choose the ‘Read Record by ID’ and select the app-link, you will be able to input the record ID and test the configuration.

If you choose the ‘Create Record API’, the list of fields which are configured as a part of the app-link will be displayed. Select a field and click Test Config. Click the 'Add Field' button if you want to add a field. 

ReST API

Query Modified Records

The URL to fetch the modified records from the Universal Adapter

MethodGET / POST
Typeapplication/JSON

Request for POST

The request in the following sample format will be sent in the request Body if the HTTP verb is chosen as POST in the configuration.
Request sample for POST

{
 "metadata" : [
 	{
	 "project": {
		"id" : "10001",
		"name" : "Sample"
	 }
	 },{
	 "domain" : {
		"id" : "DEFAULT",
		"name" : "DEFAULT"
	 }}
 ],
 "queryFilter" : "",
 "queryFields" : [ "summary", "description", "assignee", "priority", "reporter"] ,
 "fromDate" : "01-04-2019 11:46:00.000",
 "toDate" : "01-04-2019 11:48:00.000"
}
metadata - MetaData configured in the Application Link
queryFilter - Poll Query configured in the Application Link
queryFields - Fields Configured in the Application Link

fromDate - Last polled time from ConnectALL for the Application Link

toDate - Current polling time from the ConnectALL for the Application Link


URL Parameters

By clicking  beside the URL configured, the metadata available for the adapter will be displayed. Based on the selected MetaData Key, the configured value of the metadata will be sent in the URL. In addition to the metadata below fields will also be displayed. The value for the parameters will be sent in the URL while polling


last-modified-time - Last polled time from ConnectALL for the Application Link

current-time - Current polling time from the ConnectALL for the Application Link

pollQuery Poll Query configured in the Application Link

Response

Sample

{
	"totalrecords": 2,
	"result": [{
			"id": "1",
			"fields": {
				"summary": "Sample test 1",
				"description": "Sample test 1",
				"status": "Open",
				"priority": "1",
				"severity": "2",
				"modifiedTime": "01-04-2019 11:46:30.124"
			}
		}, {
			"id": "2",
			"fields": {
				"summary": "Sample test 2",
				"description": "Sample test 2",
				"status": "Open",
				"priority": "3",
				"severity": "5",
				"modifiedTime": "01-04-2019 11:46:30.124"
			}
		}
	]
}
Note: The response for the record should always return the updated date of the record.

Read Record By ID

Configure the URL to fetch the record by record id

MethodGET / POST
Typeapplication/JSON

Request for POST

The request in the following sample format will be sent in the request Body if the HTTP verb is chosen as POST in the configuration.
Request sample for POST

{
 "id":"TP-4",
 "fields" : [ "summary", "description", "assignee", "priority", "reporter", "modifiedTime"] 
}
id - record Id to be fetched
fields - Fields to be retrieved in the response


URL Parameters

By clicking  beside the URL configured, the metadata available for the adapter will be displayed. Based on the selected MetaData Key, the configured value of the metadata will be sent in the URL. In addition to the metadata below fields will also be displayed. The value for the parameters will be sent in the URL.


record id is the Id of the record to be fetched

pollQuery Poll Query configured in the Application Link

Response

Sample

{
	"id":"TP-4",
	"fields" : {
		"summary" : "Test for API creation 2",
		"description" : "Test for API creation 2",
		"priority" : "1",
		"modifiedTime" : "01-04-2019 11:46:30.124",
		"severity": "2",
		"status": "Open"
	}
}
Note: The response for the record should always return the updated date of the record.

The Universal adapter can send payload as URL Query Param for Create and Update records.

Create Record

Configure the URL to create the record

MethodPOST/PUT
Typeapplication/JSON

Request for POST

The request in the following sample format will be sent in the request Body if the HTTP verb is chosen as POST /PUT in the configuration.
Request sample for POST

{
	"fields" : {
		"summary" : "Test for API creation 2",
		"description" : "Test for API creation 2",
		"priority" : "1",
		"modifiedTime" : "01-04-2019 11:46:30.124",
		"severity": "2",
		"status": "Open"
	}
}

fields - fields configured in the application link.
URL Parameters

By clicking  beside the URL configured, the metadata available for the adapter will be displayed. Based on the selected MetaData Key, the configured value of the metadata will be sent in the URL.

Response

Sample

{
	"id":"TP-4",
	"fields" : {
		"summary" : "Test for API creation 2",
		"description" : "Test for API creation 2",
		"priority" : "1",
		"modifiedTime" : "01-04-2019 11:46:30.124",
		"severity": "2",
		"status": "Open"
	}
}
Note: The response for the record should always return the updated date of the record.

Update Record

Configure the URL to update the record

MethodPOST / PUT
Typeapplication/JSON

Request for POST

The request in the following sample format will be sent in the request body if the HTTP verb is chosen as POST/PUT in the configuration.
Request sample for POST

{
 "id":"TP-4",
 "fields" : {
	 "summary" : "Test for API creation 2",
	 "description" : "Test for API creation 2",
	 "assignee" : "admin",
	 "priority" : "1",
	 "reporter" : "admin"
  }
}

fields - fields configured in the application link

id: Id of the record to be updated.

URL Parameters

By clicking  beside the URL configured, the metadata available for the adapter will be displayed. Based on the selected MetaData Key, the configured value of the metadata will be sent in the URL. In addition to the metadata below fields will also be displayed. record Id is the id of the record to be updated.

Response

Sample

{
	"id":"TP-4",
	"fields" : {
		"summary" : "Test for API creation 2",
		"description" : "Test for API creation 2",
		"priority" : "1",
		"modifiedTime" : "01-04-2019 11:46:30.124",
		"severity": "2",
		"status": "Open"
	}
}
Note: The response for the record should always return the updated date of the record.