A great new UI refresh and significant new functionality is here!
See the 2.10 Release Notes for details.

External Application Provided API

Introduction

This 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 the webhook configuration.

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

Descriptor_ExternalAppProvider (1).json

External Application Provided API

Descriptor_external_application.json

External Application Provided API


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 below), just like you would for any other adapter, and
  • using that connection in an application link, just like you would for any other adapter.

Connection Configuration

  1. In ConnectALL's UI, under Connections, add a connection to your end application. 
  2. Specify the application type, which is the application name you specified when you created your Universal Adapter.
  3. Give the connection a name, specify the URL of the application, and any necessary credentials.
  4. Select the supported authentication types. If you choose:
    1. Basic - The credentials provided in the configuration screen will be used.
    2. API Key - When the API Key auth type is selected, the option to provide the API key name and the value will be displayed. 
  5. Select the 'Auth' option. If you choose:
    1. Header - The authentication details will be sent in the header.
    2. URL - The authentication details will be sent in the URL. Click here for more information. In addition, you can provide these details in the Connections screen. To do this, click Connections in the top navigation bar, and in the Connections screen, click the pencil icon against the required connection to edit.

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

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.

Procedure

Follow the below procedure to configure an API:

  1. Click the cog wheel 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. 

  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

Note that every API has the four below listed parameters:

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

Request Body 

This is available only for the Create 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. Click the Configuration icon () against the operation and select URL Field Options from the list to send the fields in the URL. 

This 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. The summary and the description are mapped in the application link itself. Note that the symbols “=‘ and ‘&’ will be used as the field separators.

Response Body

This is available only for Update Record. The check box can be cleared when the operation doesn’t have any response payload available from the adapter.

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 required input. For the response spec, you have to provide the sample of the adapter’s response for the API.

Spec Type

The transformation spec type, and the supported types are:

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

If you click:

  • Test Spec - This input box will have 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 in the parent page.

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.

    2.  The Metadatakey and Metadata Value button is displayed.

     

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


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.