Steps to Create REST based Operations in Gathr Analytics

Steps to create Floor Operations in Gathr Analytics:

  1. Right click on Floor and Navigate to Connectors -> Show. You’ll get a dataset consisting of all the existing connectors in your system.

  1. Drag and Drop Connectors dataset on the Floor.

  2. Right click on the Connector name and navigate to Connectors->Operations->Add Floor Operation.

  1. Once you click on Add Floor Operation a Select Connection form will open up. The input will always be the name of Connection(s) which is already configured in the Connector. Click on NEXT in this form and you’ll be directed to ADD Operation form.

  1. Carefully enter all the details in ADD Operation form.

    Details to be entered are:

    i. Add Operation Name

    ii. Add Operation Description (in brief).

    iii. Operation Type will be pre-populated.

    iv. Add REST API/Endpoint of the Operation that you wish to create. Add pagination parameter in the REST API. In order to apply pagination, user needs to add the following parameter to the REST API:

Size parameter defines the size of the chunk in which data is being called. In the example below Test Jira Connector maxResults is the size parameter. It should always be passed along with the API.

Note: By default, operations are created to read records and they use the GET request in order to do that. Users can leave those parameters with default values.

Request JSON Body is only used for write back operations. For now it should be empty for floor and context operations.

v. User needs to have prior knowledge of whether the API consists of encoding or not. If API contains encoding, the user needs to select UTF-8 Encoding from the Encoding dropdown.

vi. Select pagination, there are different types of Pagination supported by Gathr Analytics. Select the suitable type that your API supports.

In the example below, Test Jira Connector API supports Offset based Pagination, hence Offset Based Pagination is selected.

Note: Pagination is a process using which we can fetch the API response(data) into chunks. Different API uses different kinds of Pagination, users should be well aware of what kind of Pagination is being used in the API.

While implementing Pagination we need to take care of two parameters (Size and Start) which will be available in the next step.

vii. Click on NEXT after entering all the details.

  1. When you click on NEXT the user will be redirected to third form. As we are creating Floor Operation there is no query parameter thus we will not make any changes in the REQUEST TEMPLATE PARAMETERS section.

Select the PAGINATION PARAMETERS section in order to configure the Start parameter for Pagination

  1. Within the PAGINATION PARAMETERS Section enter the details for the following:

Start parameter is the reference of start of the response, here in case of Test Jira Connector startAt is being used as the Start parameter.

In the example below, for Test Jira Connector we are using offset based pagination. We define Parameter as startAt, Join Symbol as ‘=’ and Value as 0.

Note: After Operation creation, when users run this operation, as we have defined the maxResult (size parameter from previous step) as 100 and startAt parameter as 0, API will bring first 100 records and in second hit startAt parameter’s value will change from 0 to 100 automatically and API will fetch next 100 records.

This process will continue until all the records are fetched till then Operation will be in processing state. Once all the records are fetched, Operation execution will be successful.

  1. Click On NEXT, and you will be directed to the fourth Form.

  1. In the Select JSON Information form, the user needs to select the appropriate array required according to the one’s use case.

For Example : If the sample response is:

[

   {

     “Key1”:”Value1”,

     “Key2”:”Value2”

   },

   {

     “Key1”:Value3”,

     “Key2”:”Value4”

   }

]

Here for the above sample response you would see [*] array in the Select JSON Response drop down.

On selecting [*] array you’ll get a data set with the columns shown below on Gathr Analytics:

  1. Click on NEXT.

  1. Once you click on NEXT you’ll be directed to Configure Dataset form. Enter the details like Dataset Name, Dataset Description in this form. You cannot complete Operation creation without creating a Primary Key.

The paths (keys) of the JSON response are mentioned in this form, from here either you can select any relevant path(s) as your Primary Key, or you can Auto Generate Primary Key. You can change the field Name, Description, Business Type or DataType but please keep in mind not to change the path fields as it denotes the JSON path for your columns.

  1. Click on NEXT after selecting a Primary Key and your Floor Operation will be created.

You can run this Operation by Navigating from Connectors -> Imported Connectors -> Test Jira Connector(your Connector) -> View all Boards.

Steps to create Context Operation :

  1. Context Operations are created on BUSINESS/DATA Types so that they can be exposed across all the exploration. Select a cell on which you have to create context Operation like in case of Test Jira Connector if Users want to view Projects of a Board or Projects of Multiple Boards then Context Operation will be created on Board Id.

Please note that the context value you select should contain the data in the REST API response otherwise you will get no data in the later steps and the operation creation will not be successful.

  1. Select a Board Id Navigate to Connectors-> Operations ->Add Context Operation you’ll be directed to Select Connector and Connection form.

  1. From here Select your Connector from the dropdown and the Connection Name will be selected from the Connection drop down. Click on NEXT and you will be directed to ADD Operation Form.

  2. Carefully enter all the details in ADD Operation form.

    Details to be entered are:

    i. Add Operation Name

    ii. Add Operation Description in brief.

    iii. Operation Type will be pre populated.

    iv. Add REST API/Endpoint of the Operation that you wish to create. Add pagination parameter in the REST API. While creating context Operation keep in mind to take input in curly braces {}. For example if you are creating operation to View all Projects of a Board then you need to give BoardId as input in your REST API and while adding this REST API in your ADD Operation form you need to give BoardId in curly braces like :

/rest/agile/1.0/board/{boardId}/project?maxResults=100

v. User needs to have prior knowledge of whether the API consists of encoding or not. If the API contains encoding, the user needs to select UTF-8 Encoding from the Encoding dropdown.

vi. Select pagination, here Test Jira Connector API supports Offset based Pagination. Hence, Offset Based Pagination is Selected.

vii. Click on NEXT after entering all the details.

Note: Pagination is a process using which we can fetch the API response(data) into chunks. Different API uses different kinds of Pagination, One should be well aware of what kind of Pagination is being used in one’s API. While implementing Pagination we need to take care of two parameters: first is size parameter, this parameter defines size of the chunk in which data is being called, second parameter is start parameter which defines the start record. The size parameter(maxResult) is passed along with the API in ADD Operation form and the start parameter is configured in the later steps of Operation creation.

  1. When you click on NEXT you will be redirected to Third form, here all the fields will be pre-populated. Here, in the Maximum Values section change the value from 10 to 1. API may allow more than 1 input in the query parameter for example in the Test Jira Connector case in View all Projects API can take only 1 Input at time.

For Example : /rest/agile/1.0/board/2/project?maxResults=100

If the API would have supported more than 1 value then the value of Maximum Values would have been increased and more than 1 parameters would have been passed in the API

For Example: /rest/agile/1.0/board/2,3,4/project?maxResults=100

Most of the API’s do not support more than 1 parameter in query hence we recommend users to change this value from 10 to 1 so that API can be executed successfully.

For pagination details kindly go to PAGINATION PARAMETERS section.

Within the PAGINATION PARAMETERS Section, enter the details of start parameter, sample is shown below, here in Test Jira Connector we are using offset based pagination. We define Parameter as startAt, Join Symbol as ‘=’ and Value as 0.

After Operation creation when we run this operation, as we have defined the maxResult i.e the size parameter as 100 and startAt parameter as 0, API will bring first 100 records and in second hit startAt parameter’s value will change from 0 to 100 and API will fetch next 100 records.

This process will continue until all the records are fetched till then Operation will be in processing state. Once all the records are fetched, Operation execution will be successful.

Operations can be created on Business Type as well as Data Type, User can define this from the CONTEXT PARAMETER Section from the Configure Query Parameters forms.

In the CONTEXT PARAMETER Section from the dropdown User can Select whether they want to create an operation on Business Type or Data Type.

User can also add Context in the resultant dataset for that User has to check the Add Operation Context in Result checkbox.

  1. Click On NEXT, and you will be directed to the fourth Form.

  1. In the Select JSON Information form, the user needs to select the appropriate array required according to the one’s use case.

    For Example : If the sample response is:

    [

    {

     “Key1”:”Value1”,

 “Key2”:”Value2”

    },

    {

      “Key1”:Value3”,

  “Key2”:”Value4”

}

    ]

Here for the above sample response you would see [] array in the Select JSON Response drop down. On selecting [] array you’ll get the following data on Gathr Analytics:

  1. Click on NEXT.

  2. Once you click on NEXT you’ll be directed to Configure Dataset form. Enter the details like Dataset Name, Dataset Description in this form.

You cannot complete Operation creation without creating a Primary Key

The keys of the JSON response are mentioned in this form, from here either you can select any relevant key(s) as your Primary Key, or you can Auto Generate Primary Key. You can change the field Name, Description, Business Type or Datatype but please keep in mind to not to change the path fields as it denotes the JSON path for your columns.

  1. Click on NEXT after selecting a Primary Key and your Context Operation will be created successfully.

  2. You can then perform this operation by right click on a cell/multiple cell/whole column and then go to Connectors → Imported Connectors → → and run the operation.

For ex, in the example it would look like Connectors → Imported Connectors → Test Jira Connector → View all Projects

Steps to create Write Back Operation:

Prerequisites required for POST Operation:

POST REST API

Request JSON Body required for creating POST Operation.

Response JSON Body required for creating POST Operation. Steps for creating Post Operation in Gathr Analytics:

  1. While creating POST Operation , User needs to make sure that the container contains all fields/keys that are present in there Request JSON Body ,for example in case of Test Jira Connector while creating Create Component of Project operation, Request JSON Body contains 4 fields:

{

 "name": "TestJiraComponent",

 "description": "Test Component Creation",

 "leadUserName": "jack.sparrow",

 "project": "TrialProject"

}

  1. Right click on the top of the Container present on the floor, Navigate to Connectors → Operations → Add Operation.

  1. Once you click on Add Operation a Reduce data popup will appear. Click on APPLY and you’ll be directed to Select Connector and Connection form.

  1. From here Select your Connector from the dropdown and the Connection Name will be selected from the Connection drop down. Click on NEXT and you will be directed to ADD Operation Form.

  1. Carefully enter all the details in ADD Operation form.

    Details to be entered are:

    i. Add Operation Name

    ii. Add Operation Description

    iii. Add REST API/Endpoint of the Operation that you wish to create

    iv. Under Actions drop down select Add new record(s) as you are creating a POST operation to create data in your application using Gathr Analytics.

    v. Select HTTP Method as POST.

vi. In Request JSON Body add the Request JSON Body that is required to create the respective operation.

For example in case of Test Jira Connector while creating Add Component Operation ,a sample Request JSON Body is as follows:

{

 "name": "TestJiraComponent",

 "description": "Test Component Creation",

 "leadUserName": "jack.sparrow",

 "project": "TrialProject"

}

Hence this is the kind of response that you need to add in the Request JSON Body in case of Add Component Operation.

vii. User needs to have prior knowledge of whether the API consists of encoding or not, If API contains encoding, the user needs to select UTF-8 Encoding from the Encoding dropdown.

viii. After entering all the details click on NEXT.

  1. When you click on NEXT the user will be redirected to the third form that is Configure Query Parameters form. In the REQUEST TEMPLATE PARAMETER section, if the REST API has any context(input) then the user needs to configure that input here. Then go to the JSON BODY PARAMETERS section, where the mandatory key will be configured. Mandatory keys are the keys/fields that are required for write back, without these keys users will not be able to write back to the system.

In the case of Test Jira Connector while creating the Add Component operation the mandatory keys are project and name , we check the “Is this Input mandatory?” checkbox, corresponding to project and name.

Please make sure to assign the correct Data Type for your fields, otherwise execution of the operations wouldn’t be successful due to the incorrect datatypes.

In the HEADER PARAMETER section, if your REST API contains any header then user needs to add that in this section.

  1. Click on NEXT after selecting the mandatory keys.

  2. When you click on NEXT you will be redirected to Select JSON Information form.

  3. On Select JSON Information form in Response JSON Body you need to give the Response body of your API.

  1. In the Loop element section, the user needs to select the appropriate array required according to the one’s use case.

For Example : If the sample response is:

[

{

     “Key1”:”Value1”,

      “Key2”:”Value2”

 }

 {

     “Key1”:Value3”,

      “Key2”:”Value4”

  }

]

Here for the above sample response you would see [*] array in the Select JSON Response drop down.

On selecting [*] array you’ll get a data set with the columns shown above on Gathr Analytics:

Please note that the JSON response body you’ve added might not contain any array([*]), in that case the “Loop Element” section will remain empty and will generate the fields/columns values according to the object’s values (Keys present in the curly braces {}).

Click on NEXT.

  1. Once you click on NEXT you’ll be directed to Configure Dataset form. Enter the details like Dataset Name, Dataset Description in this form.

You cannot complete Operation creation without creating a Primary Key.

The keys of the JSON response are mentioned in this form, from here either you can select any relevant key(s) as your Primary Key, or you can Auto Generate Primary Key. You can change the field Name, Description, Business Type or Datatype but please keep in mind to not to change the path fields as it denotes the JSON path for your columns.

How to run a POST Operation:

In order to run POST Operation you need to follow the following steps:

  1. Right click on top of the container and Navigate to Connectors → Imported Connector→ → and run the operation.

For example, in the example it would look like Connectors → Imported Connector → Test Jira Connector → Add Component

  1. Once you click on the Operation name a Reduce data popup will appear click on APPLY and you’ll be directed to the Map Parameters popup where you need to map the mandatory parameters corresponding to parameters in your Request JSON Body.

For Example for creating a component of a Project in Jira we need Component name and the Project name ,hence name and project are two mandatory fields, thus your container should contain the component name that you wish to create and project name for which you want to create the component.

NOTE: The Mapping Parameters will be the same as the Request JSON Body keys, Users need to carefully map the details that they want to write back to their systems.

  1. Click on Submit and if the write back is successful you’ll get a Request Execution Detail dataset and a dataset for which the write back was performed.

For example in the case of Test Jira Connector when you run Add Component operation, two dataset :

  1. Components
  2. Request Execution Detail will be generated.

NOTE: Creating REST based operations in Gathr Analytics requires good knowledge of the REST APIs, Paginations and the JSONs structures.

Please write to us at support@Gathr Analytics.one in case of any question/concern(s).

If you have any feedback on Gathr documentation, please email us!

← Configure Google Sheets on New Gathr Analytics UI
Steps to create a new REST Connector in Gathr Analytics →