Introduction

ConnectALL has exposed a set of ReST APIs that other applications or scripts can use to query (poll) for modified records, to retrieve modified records, to put new records, and to post modifications to the linked application. Whenever the other application or script uses ConnectALL's APIs, ConnectALL will then respond by managing the synchronization or data retrieval with the mapped application.

If you are on version 2.10.2 or below, use the below descriptor formatIf you are on version 2.10.3 or above, use the below descriptor formatIf you are on version 2.10.29.1 or later versions

Desc_ConnectALL_Provider.json

ConnectALL Provided API descriptor 

Descriptor_ConnectALL_API_Prpvider.json

ConnectALL Provided API descriptor

adapter-descriptor (1).json
ConnectALL Provided API descriptor

REST API

Most, but not all, methods in this ReST API take a JSON payload as input in the request and return a JSON payload in the response. Sample request and response JSON payloads are given below.ReST API

Get Modified Records

Fetch modified records from the other application.

Sample Request

{
   "appLinkName":"TestCustomAdapter",
   "lastModifiedTime":"2019-10-02 00:30:00.000"
}
appLinkName - Application Link Name 
modifiedTime - Time from which the records has to be fetched
Sample Response
{ 
   "totalrecords": 2, 
   "data": [
            { 
             "id": "1", 
             "fields": {
                        "issuetype: "bug",
                        "summary": "Sample test 1", 
                        "description": "Sample test 1", 
                        "status": "Open", 
                        "priority": "1", 
                        "severity": "2", 
                        "id": "1" 
                       } 
            }, 
            { 
             "id": "2", 
             "fields": { 
                        "issuetype: "bug",
                        "summary": "Sample test 2", 
                        "description": "Sample test 2", 
                        "status": "Open", 
                        "priority": "3", 
                        "severity": "5", 
                        "id": "2" 
                       } 
            } 
           ] 
}

In the example response above, note that an "id" is given inside of "fields", and also outside of fields. The value in both "id" fields is the invoking system's record ID. Such an ID only gets set when a record in the other system is created via save records (described below). Therefore, if the modified records returned in the result have never been sync'd/linked to a record in the invoking system, the ID values will be empty.

"issuetype" will be the value specified in your entity mapping if you provided an issuetype field in your Universal Adapter Descriptor.  To clarify, it will be the invoking app's issuetype, not the issuetype from the system on the other side of the automation.


URL

http://<ConnectAllServer>:8090/connectall/api/2/search

MethodPOST
Typeapplication/JSON
Sample Code
Using cURL

curl -X <METHOD> -u <USERNAME:PASSWORD> --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'apikey: <API_KEY_FOR_AUTHENTICATION>' -d '<REQUEST_BODY>' '<URL>'

Using Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class SearchRecordApi {

public  void searchRecord() throws Exception {
  URL obj = new URL("<URL>");
  HttpURLConnection con = (HttpURLConnection) obj.openConnection();
  String input = "<REQUEST_BODY>";

  String userCredentials = "<USERNAME:PASSWORD>";
  String basicAuth = "Basic " + new String(Base64.getEncoder().encode(userCredentials.getBytes()));

  con.setRequestProperty ("Authorization", basicAuth);
  con.setRequestMethod("<METHOD>");
  con.setRequestProperty("Content-Type", "application/json");
  con.setRequestProperty("Accept", "application/json");
  con.setRequestProperty ("apikey", "<API_KEY_FOR_AUTHENTICATION>");

  con.setDoInput(true);
  con.setDoOutput(true);
  OutputStream os = con.getOutputStream();
  os.write(input.getBytes());
  os.flush();

  int responseCode = con.getResponseCode();
  System.out.println("Method Response Code :: " + responseCode);

  if (responseCode == HttpURLConnection.HTTP_OK || responseCode == 201) { //success
  BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
  String inputLine;
  StringBuffer response = new StringBuffer();

  while ((inputLine = in.readLine()) != null) {
    response.append(inputLine);
  }
  in.close();
    System.out.println(response.toString());
  } else {
    System.out.println("Method request not worked");
  }
}
}
Using Ruby
#!/usr/bin/ruby

require 'net/http'
require 'json'
require 'uri'

data = <REQUEST_BODY>

uri = URI.parse("<URL>")
headers = {'Content-Type' => "application/json", 'Accept' => "application/json",'apikey' => "<API_KEY_FOR_AUTHENTICATION>"}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, headers)
request.basic_auth("<USERNAME>", "<PASSWORD>")
request.body = data.to_json
response = http.request(request)

puts response.code
puts response.body

Using Python

#adding the requests library

import requests
from wsgiref import headers
import json

# defining the api-endpoint
API_ENDPOINT = "<URL>"
basicAuthCredentials = ('<USERNAME>', '<PASSWORD>')
# your API key here
headers = {'Content-Type' : 'application/json', 'Accept' : 'application/json','apikey' : '<API_KEY_FOR_AUTHENTICATION>'}

# data to be sent to api
data = <REQUEST_BODY>

# sending post request and saving response as response object
r = requests.post(url = API_ENDPOINT, auth=basicAuthCredentials, headers=headers, data = json.dumps(data))


# extracting response text
print(r.status_code)
print(r.text)

Save Records

Request from the external application (the system that is making the call) to create or update a record in the linked application.

Sample Request

{
 "fields" : {
   "summary" : "Test for API creation 2",
   "description" : "Test for API creation 2",
   "assignee" : "admin",
   "priority" : "1",
   "reporter" : "admin",
   "id":"<RECORD_ID>"
 },
 "appLinkName":"TestCustomAdapter"
}
appLinkName - Application Link Name from the ConnectALL
fields - Fields to be created

<RECORD_ID> - The external application's record ID. (The invoking system's record ID.)
Sample Responses
201 –
{
  "Response":"Success",
  "Message":"Record Jira6QC11Req\QC-20 successfully pushed into ConnectAll queue! "
}
400 – Bad request or validation errors: Sample > {"Response":"Error", "Message":"<specific error message>"}

500 – Unable to process the request due to internal server.

If you have provided a value for ID Field in your Universal Adapter Descriptor, then you can use that field name instead of "id" in your request.

Note that this supports Dynamic Record Linking as well. To link to an existing record in the other application, provide the other system's record id in the appropriate field. (Follow the Dynamic Record Linking instructions for the field mapping.) For example, in a Jama to bespoke app sync, when a new Jama record is created, the bespoke app will detect the new Jama record via a get modified record search, create the new record in its system, and then set the relationship in the other app. To do so, postRecord with nothing except the two IDs to map:


{
   "appLinkName":"bespokeToJama",
   "fields":{
       "JAMA_ID":"OP-TRY-616",
       "id":"24"
    }
}


URLhttp://<ConnectAllServer>:8090/connectall/api/2/postRecord
MethodPOST
Typeapplication/JSON
Sample Code
Using cURLcurl -X <METHOD> -u <USERNAME:PASSWORD> --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'apikey: <API_KEY_FOR_AUTHENTICATION>' -d '<REQUEST_BODY>' '<URL>'
Using Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class PostRecordApi {

public  void postRecord() throws Exception {
  URL obj = new URL("<URL>");
  HttpURLConnection con = (HttpURLConnection) obj.openConnection();
  String input = "<REQUEST_BODY>";

  String userCredentials = "<USERNAME:PASSWORD>";
  String basicAuth = "Basic " + new String(Base64.getEncoder().encode(userCredentials.getBytes()));

  con.setRequestProperty ("Authorization", basicAuth);
  con.setRequestMethod("<METHOD>");
  con.setRequestProperty("Content-Type", "application/json");
  con.setRequestProperty("Accept", "application/json");
  con.setRequestProperty ("apikey", "<API_KEY_FOR_AUTHENTICATION>");

  con.setDoInput(true);
  con.setDoOutput(true);
  OutputStream os = con.getOutputStream();
  os.write(input.getBytes());
  os.flush();

  int responseCode = con.getResponseCode();
  System.out.println("Method Response Code :: " + responseCode);

  if (responseCode == HttpURLConnection.HTTP_OK || responseCode == 201) { //success
    BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
    String inputLine;
    StringBuffer response = new StringBuffer();

    while ((inputLine = in.readLine()) != null) {
      response.append(inputLine);
    }
    in.close();
    System.out.println(response.toString());
  } else {
    System.out.println("Method request not worked");
  }
}
}
Using Ruby
#!/usr/bin/ruby

require 'net/http'
require 'json'
require 'uri'

data = <REQUEST_BODY>

uri = URI.parse("<URL>")
headers = {'Content-Type' => "application/json", 'Accept' => "application/json",'apikey' => "<API_KEY_FOR_AUTHENTICATION>"}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, headers)
request.basic_auth("<USERNAME>", "<PASSWORD>")
request.body = data.to_json
response = http.request(request)

puts response.code
puts response.body
Using Python
#adding the requests library

import requests
from wsgiref import headers
import json

# defining the api-endpoint
API_ENDPOINT = "<URL>"
basicAuthCredentials = ('<USERNAME>', '<PASSWORD>')
# your API key here
headers = {'Content-Type' : 'application/json', 'Accept' : 'application/json','apikey' : '<API_KEY_FOR_AUTHENTICATION>'}

# data to be sent to api
data = <REQUEST_BODY>

# sending post request and saving response as response object
r = requests.post(url = API_ENDPOINT, auth=basicAuthCredentials, headers=headers, data = json.dumps(data))

# extracting response text
print(r.status_code)
print(r.text)

Get Linked Record ID

Request from the external application to fetch the linked record ID. The "linked record Id" is the ID in the other system. In the request, provide the external application's own record ID. This will, of course, return nothing unless the given record ID has been linked to a record in the other system. 

This is similar to getRecordById. This method returns a JSON payload containing the ID, whereas getLinkedRecordId returns just the ID, in text, without JSON.

Sample Request

{
  "appLinkName":"TestCustomAdapter",
  "recordId":"<RECORD_ID>"
}
appLinkName - Application Link Name from the ConnectALL
recordId- The calling system's record ID used to retrieve the linked record ID in the other system
Sample Responses
200 – {"id":"DP-5"}

404 - If no linked record Id is available

400 – Bad request or validation errors:  {"Response":"Error", "Message":"<specific error message>"}

500 – Unable to process the request due to internal server.
URLhttp://<ConnectAllServer>:8090/connectall/api/2/getLinkedRecordId
MethodPOST
Typeapplication/JSON
Sample Code
Using cURLcurl -X <METHOD> -u <USERNAME:PASSWORD> --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'apikey: <API_KEY_FOR_AUTHENTICATION>' -d '<REQUEST_BODY>' '<URL>'
Using Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class GetLinkedRecordIdAPI {

public  void getLinkedRecordId() throws Exception {
  URL obj = new URL("<URL>");
  HttpURLConnection con = (HttpURLConnection) obj.openConnection();
  String input = "<REQUEST_BODY>";

  String userCredentials = "<USERNAME:PASSWORD>";
  String basicAuth = "Basic " + new String(Base64.getEncoder().encode(userCredentials.getBytes()));

  con.setRequestProperty ("Authorization", basicAuth);
  con.setRequestMethod("<METHOD>");
  con.setRequestProperty("Content-Type", "application/json");
  con.setRequestProperty("Accept", "application/json");
  con.setRequestProperty ("apikey", "<API_KEY_FOR_AUTHENTICATION>");

  con.setDoInput(true);
  con.setDoOutput(true);
  OutputStream os = con.getOutputStream();
  os.write(input.getBytes());
  os.flush();

  int responseCode = con.getResponseCode();
  System.out.println("Method Response Code :: " + responseCode);

  if (responseCode == HttpURLConnection.HTTP_OK || responseCode == 201) { //success
    BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
    String inputLine;
    StringBuffer response = new StringBuffer();

    while ((inputLine = in.readLine()) != null) {
      response.append(inputLine);
    }
    in.close();
    System.out.println(response.toString());
  } else {
    System.out.println("Method request not worked");
  }
}
}
Using Ruby
#!/usr/bin/ruby

require 'net/http'
require 'json'
require 'uri'

data = <REQUEST_BODY>

uri = URI.parse("<URL>")
headers = {'Content-Type' => "application/json", 'Accept' => "application/json",'apikey' => "<API_KEY_FOR_AUTHENTICATION>"}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, headers)
request.basic_auth("<USERNAME>", "<PASSWORD>")
request.body = data.to_json
response = http.request(request)

puts response.code
puts response.body
Using Python
#adding the requests library

import requests
from wsgiref import headers
import json

# defining the api-endpoint
API_ENDPOINT = "<URL>"
basicAuthCredentials = ('<USERNAME>', '<PASSWORD>')
# your API key here
headers = {'Content-Type' : 'application/json', 'Accept' : 'application/json','apikey' : '<API_KEY_FOR_AUTHENTICATION>'}

# data to be sent to api
data = <REQUEST_BODY>

# sending post request and saving response as response object
r = requests.post(url = API_ENDPOINT, auth=basicAuthCredentials, headers=headers, data = json.dumps(data))

# extracting response text
print(r.status_code)
print(r.text)

Get Record By ID

Request from the external application to fetch the linked record ID. Provide the external application's own record ID in the request. I.E., the invoking external app uses its own record ID to request the info from the other system.

This is similar to getLinkedRecordId, but this returns just the id, in text, whereas the other call returns a JSON payload.

Sample Request

{
  'appLinkName' => "TestCustomAdapter",
  'recordId' => "<RECORD_ID>"
}
appLinkName - Application Link Name from the ConnectALL
recordId - the external application's record ID used to retrieve the linked record Id from the other system
Sample Responses
200 – DP-5 (Sample response. The record ID in plain text; not JSON.)

404 - If no linked record Id is available

400 – Bad request or validation errors: {"Response":"Error", "Message":"<specific error message>"}

500 – Unable to process the request due to internal server.
URLhttp://<ConnectAllServer>:8090/connectall/api/2/getRecordById
MethodPOST
Typeapplication/JSON
Sample Code
Using cURLcurl -X <METHOD> -u <USERNAME:PASSWORD> --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'apikey: <API_KEY_FOR_AUTHENTICATION>' -d '<REQUEST_BODY>' '<URL>'
Using Java
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.io.OutputStream;
import java.net.HttpURLConnection;
import java.net.URL;
import java.util.Base64;

public class GetRecordByIdAPI {

public  void getRecordById() throws Exception {
  URL obj = new URL("<URL>");
  HttpURLConnection con = (HttpURLConnection) obj.openConnection();
  String input = "<REQUEST_BODY>";

  String userCredentials = "<USERNAME:PASSWORD>";
  String basicAuth = "Basic " + new String(Base64.getEncoder().encode(userCredentials.getBytes()));

  con.setRequestProperty ("Authorization", basicAuth);
  con.setRequestMethod("<METHOD>");
  con.setRequestProperty("Content-Type", "application/json");
  con.setRequestProperty("Accept", "application/json");
  con.setRequestProperty ("apikey", "<API_KEY_FOR_AUTHENTICATION>");

  con.setDoInput(true);
  con.setDoOutput(true);
  OutputStream os = con.getOutputStream();
  os.write(input.getBytes());
  os.flush();

  int responseCode = con.getResponseCode();
  System.out.println("Method Response Code :: " + responseCode);

  if (responseCode == HttpURLConnection.HTTP_OK || responseCode == 201) { //success
    BufferedReader in = new BufferedReader(new InputStreamReader(con.getInputStream()));
    String inputLine;
    StringBuffer response = new StringBuffer();

    while ((inputLine = in.readLine()) != null) {
      response.append(inputLine);
    }
    in.close();
    System.out.println(response.toString());
  } else {
    System.out.println("Method request not worked");
  }
}
}
Using Ruby
#!/usr/bin/ruby

require 'net/http'
require 'json'
require 'uri'

data = <REQUEST_BODY>

uri = URI.parse("<URL>")
headers = {'Content-Type' => "application/json", 'Accept' => "application/json",'apikey' => "<API_KEY_FOR_AUTHENTICATION>"}
http = Net::HTTP.new(uri.host, uri.port)
request = Net::HTTP::Post.new(uri.request_uri, headers)
request.basic_auth("<USERNAME>", "<PASSWORD>")
request.body = data.to_json
response = http.request(request)

puts response.code
puts response.body
Using Python
#adding the requests library

import requests
from wsgiref import headers
import json

# defining the api-endpoint
API_ENDPOINT = "<URL>"
basicAuthCredentials = ('<USERNAME>', '<PASSWORD>')
# your API key here
headers = {'Content-Type' : 'application/json', 'Accept' : 'application/json','apikey' : '<API_KEY_FOR_AUTHENTICATION>'}

# data to be sent to api
data = <REQUEST_BODY>

# sending post request and saving response as response object
r = requests.post(url = API_ENDPOINT, auth=basicAuthCredentials, headers=headers, data = json.dumps(data))

# extracting response text
print(r.status_code)
print(r.text)

Save Attachment

Request from the external application to save an attachment to the application on the other side of the automation. The is uni-directional; attachments can be sent to the connected application, but cannot be retrieved from that application. 

URL

http://<ConnectAllServer>:8090/connectall/api/2/upload?appLinkName=<APPLICATION_LINK_NAME>

&recordId=<RECORD_ID>

&apikey=<API_KEY_FOR_AUTHENTICATION>

&origin=<ORIGIN>

MethodPOST
Type

multipart/form-data. (The below procedure applies if you are using Postman)

  • Select the option File from the drop-down list under the key column. The Select File button is displayed. 
  • Enter the input as ‘file’ under the KEY column as it denotes that you are uploading a file. Note that providing any other key input (other than ‘file’) will result in an error response.
  • Click the Select File button, and choose the file from your local drive.

Query Params

apikey - <API_KEY_FOR_AUTHENTICATION>
appLinkName - Application Link Name

recordId - The external record ID (the ID from which the attachment is pushed). ConnectALL uses this record id to locate the linked destination record on which to store the attachment. 

origin - Specify "source" if the invoking application (using the Universal Adapter) is on the left side of the automation, or "destination" if it's on the right side of the automation.

Sample Code
Using cURL
curl --location --request POST 'http://localhost:8090/connectall/api/2/upload?appLinkName=<APPLICATION_LINK_NAME>
&origin=source
&recordId=<recordId>
&apikey=<API_KEY_FOR_AUTHENTICATION> 
--header 'Content-Type: multipart/form-data' --form 'file=@/Users/sbhaskara/Downloads/testcaseerrorlogfile.log'
Response


{
   "attachmentId": <ATTACHMENT_ID>
}

Notes:

  • Interestingly, mapping the attachment fields in Field Mapping is not required.
  • Providing the attachmentFieldName and attachmentFieldId in the adapter descriptor is not required.
  • You do not even have to provide an attachment field in the field attributes in the descriptor.

GET Comments by Record ID 

Request from the external application to fetch the comments. Provide the record ID corresponding to the mapped application in the request. I.E., the invoking external app uses linking record id of the other system.

{Note: ConnectALL will do the RTF conversions on comment body based on the datatype defined in the comment field configuration of the automation}.

Sample Request

{
  'appLinkName' : "TestCustomAdapter",
  'recordId' : "EXTERNAL_RECORD_ID",

  'createdAfter':1592246088099


}

appLinkName - Application Link Name from the ConnectALL.

recordId - The external application's record ID used to retrieve the comments from linked record Id of the destination system.

createdAfter – timestamp that is used to filter based on comment creation date.
Sample Responses

[

    {

       

        "commentId": "671926",

        "author": "admin",

        "body": "test 1",

        "createdDate": 1593648560000,

        "updatedDate": 1593648560000,

       

    },

    {

        "commentId": "671927",

        "author": "admin",

        "body": "test 2"

        "createdDate": 1593648565000,

        "updatedDate": 1593648565000

       

    }

]


commentId – uniqueId to refer to the comment in the other system (Optional – depends on application).

author – user who created the comment in the other system.

body – actual comment body with formatting based on the configuration in applink.

createdDate – timestamp when the comment was created.

updatedDate – timestamp when the comment was last updated.

Sample Request
200 – On successful response

400 – Bad request or validation errors: {"Response":"Error", "Message":"<specific error message>"}

500 – Unable to process the request due to internal server.
URL http://<ConnectAllServer>:8090/connectall/api/2/getRecordCommentsById
MethodPOST
Typeapplication/JSON
Sample Code
Using cURLSame as other examples
Using JavaSame as other examples
Using RubySame as other examples
Using PythonSame as other examples

Save Comments by Record ID 

Post the comment from external application to other mapped system. Provide the record ID corresponding to the mapped application in the request. I.E., the invoking external app uses linking record id of the other system.

{Note: ConnectALL will do the RTF conversions on comment body based on the datatype defined in the comment field configuration of the automation}.

Sample Request

{
  "appLinkName" : "TestCustomAdapter",
  "recordId" : "EXTERNAL_RECORD_ID",

  "commentList":[{

      "body": "Comment 1",

      "author": "admin"

  },{

      "body": "Comment 2",

      "author": "admin"

  },{

      "body":"Comment 3",

      "author": "admin"

  }]


}

appLinkName - Application Link Name from ConnectALL

recordId – linking record id of the mapped application from the other system

commentList – an array of JSON Object with body, author information to save them as commentsSample Responses
Sample Responses

{

    "Response": "Success",

    "Message": "Comment successfully posted on to record! "

}


200 – On successful response
400 – Bad request or validation errors: {"Response":"Error", "Message":"<specific error message>"}

500 – Unable to process the request due to internal server.
URL http://<ConnectAllServer>:8090/connectall/api/2/postRecordCommentById
MethodPOST
Typeapplication/JSON
Sample Code
Using cURLSame as other examples
Using JavaSame as other examples
Using RubySame as other examples
Using PythonSame as other examples

Parameters

<ConnectAllServer> - IpAddress of the server

<METHOD> - MethodType

<USERNAME> - User of the ConnectALL

<PASSWORD> - Password of the user

<API_KEY_FOR_AUTHENTICATION> - api-key for the user in ConnectALL

<REQUEST_BODY> - request body for a particular url in respectively json format

<URL> - api-endpoint