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 format | If you are on version 2.10.3 or above, use the below descriptor format | If you are on version 2.10.29.1 or later versions |
---|
Desc_ConnectALL_Provider.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 |
---|
Method | POST |
---|
Type | application/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"
}
}
URL | http://<ConnectAllServer>:8090/connectall/api/2/postRecord |
---|
Method | POST |
---|
Type | application/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 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. |
URL | http://<ConnectAllServer>:8090/connectall/api/2/getLinkedRecordId |
---|
Method | POST |
---|
Type | application/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 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. |
URL | http://<ConnectAllServer>:8090/connectall/api/2/getRecordById |
---|
Method | POST |
---|
Type | application/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 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> |
---|
Method | POST |
---|
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.
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 |
Method | POST |
Type | application/JSON |
Sample Code |
Using cURL | Same as other examples |
Using Java | Same as other examples |
Using Ruby | Same as other examples |
Using Python | Same as other examples |
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 |
Method | POST |
Type | application/JSON |
Sample Code |
Using cURL | Same as other examples |
Using Java | Same as other examples |
Using Ruby | Same as other examples |
Using Python | Same 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