Prerequisite: You should have knowledge on upload templates in Kloudio and REST APIs.

What is a Custom API connection?

If you use upload templates in Kloudio, you'll know that we use Google Sheets or Excel to upload data to a table in your database. If your data destination is not a database, this article will help you push data to an external service or SaaS application REST API.

Note: For this example we'll be using a JIRA API as our SaaS destination.

Steps to create Custom API Template:

-Set up your Custom API connection

-Use your Custom API connection to create an upload template. 

How to create a custom API connection?

1. Login to the Kloudio dashboard

2. Click on Connections 

3. Click on New Connection 

4. Under Web Applications  section, click on Custom API  

5. Fill in the Connection Name (can be anything) and Base URL (Rest API's Base URL)  

6. You will see a page like this. If you want to set up authentication, you can use the Authentication section. It has options like Basic Auth  or Bearer . You can also add headers. For this example we will use a basic auth according to Jira's API, So, we have to input, encode_base64(username:password)

7. Click Template Endpoint . There is another option called Reports Endpoint  that is used to integrate your custom API with Kloudio's reporting feature. 

8. Complete the following fields:

  1. Name  – Can be anything
  2. Upload URL  – This has to be sub url POST endpoint to upload data, which accepts id as param. Eg:(https://kloudio.atlassian.net/rest/api/2/issue/:issueId)
  3. Headers URL  – Which should return columns, or data we can get all columns.
  4. Data Access Path – On which key you need to send data on payload to POST endpoint
  5. Upload Response Parser  – Here you will need to write code to parse the response from POST endpoint, so Kloudio can understand it. This function should return an object which has a status, message and id. Status can be Invalid  or Success . Message should be the message you want display on template. 
  6. Header Response Parser  - Here you need to write code to parse the response from GET columns endpoint, so, Kloudio can display the columns for you. This function should return list of columns which has columnName , columnMapping  and dataType

    For Jira:

  1. Name  – Upload Issues
  2. Upload URL  – /rest/api/2/issue
  3. Headers URL  – /rest/api/2/search?maxResults=1
  4. Data Access Path – N/A for Jira POST
  5. Upload Response Parser  – 
module.exports = function (response, error) {
  if(error){
      let errorText = collectErr(response.errors);
      return {
          status: "invalid",
          message: errorText
      };
    }else {
      return {
          status: "Success",
          message: "",
          id: response.key
      };
    }
};

function collectErr(errorsData) {
    let errorText = '';
    for (let key in errorsData) {
        if (errorsData.hasOwnProperty(key)) {
            errorText += errorsData[key] + ';';
        }
    }
    return errorText;
};

    6. Header Response Parser  - 

const mapDatatype = {
    string: 'Text',
    boolean: 'Text',
    number: 'Number',
    object: 'Object',
};
module.exports = function headersParser(response) {
    flattedObject = flattenObject(response.issues[0]);
    for (let key in flattedObject) {
        columns.push({
            columnName: key,
            columnMapping: key,
            dataType: mapDatatype[typeof (flattedObject[key])] || 'Text'
        })
    }
    return {
        columns: columns
    };
};

function flattenObject(obj, prefix) {
    let propName = prefix ? prefix + '.' : '';
    let retObj = {};
    for (let attr in obj) {
        let parentAttr = propName + attr;
        if (Array.isArray(obj[attr])) {
            retObj[parentAttr] = obj[attr]
        } else if (typeof obj[attr] === 'object') {
            Object.assign(retObj, flattenObject(obj[attr], parentAttr));
        } else {
            retObj[parentAttr] = obj[attr];
        }
    }
    return retObj;
};

9. Click Save.

How to create a custom API Template?

1 . Go to the Home Screen again

2. Click on Templates

3. Click on New Template

4. Click and Select the Connection name we created in the previous step (Create custom Connection). 

5. Click Search to get all the entities we have available for the upload.

6. Click on your entity. For the example its Upload Issues.

7. Select all the required fields for the Kloudio to make POST request. For the examples its, fields.summary, fields.project.key, fields.issuetype.name and fields.id.

8. Name the template and click Save.

How to use Google Sheet to upload Issues to JIRA?

1 . Open a blank sheet Google sheets.
2. Click on Add-ons -> Kloudio -> Login.
3. Login to Kloudio.

4. Click on Add-ons -> Kloudio -> My Templates to view all your templates. 

5. Click on the template you created and Click INSERT TEMPLATE.

6. The template will be inserted as shown below: 

7. Add the data you want to upload.

8. Click Add-ons -> Kloudio -> Upload -> All to upload data.

9. Kloudio will show the status of your upload.

10. Done! In this example, our issue is now uploaded in Jira. 

Did this answer your question?