Chimichanga-Integrations

This library provides an interface used to integrate 3rd party apps with Chimichanga. Trello is the only 3rd party app currently implemented.

Prerequisuites

Trello: You must get both an API Key and a token to create an instance of an interface for Trello. Both can be retrieved from the following link: https://trello.com/app-key

-Please note that any of the calls that the interface will make to Trello will only work if the token matches the account that the user is trying to retrieve a board from. -In other words, your token is only authorized to retrieve data linked to that account only.

Usage

1. Require the package after installation

  const chimiInterface = require('@theportal/chimichanga-integrations');

2. You must create an instance of an Interface by specifying the desired 3rd party app. The Interface takes in two parameters: name (specifies the name of the 3rd party app) and the associated data required to setup/authorize the interface's calls. For Trello, the data object must contain an apiKey and a token.

  const data = {
    apiKey = '',
    token = ''
  };
  const trelloInterface = new chimiInterface('trello', data );

3. Once created, you can make calls to Trello using the interface.

  trelloInterface.getProjectId(projectUrl);
  trelloInterface.getProject(projectId);
  trelloInterface.getMembers(taskId);
  trelloInterface.updateTask(taskId, completed);
  trelloInterface.updateSubtask(taskId, subtaskId, completed);
  trelloInterface.addAttachmentByUrl(taskId, url);
  trelloInterface.createWebhook(projectId, callbackUrl);
  trelloInterface.formatWebhookRes(res);

Interface Methods

The getProjectId(projectUrl) Method

The getProjectID() method is used to return a project's ID by using the project's URL.

  const projectUrl = "https://trello.com/b/suJlDmry/myboard";
  const projectId = trelloInterface.getProjectId(projectUrl);

The getProject(projectId) Method

The getProject() method will return all relevant Chimichanga data for a project. It will return all the tasks (and all info for each task: dueDate, description, assignees, etc) and all checklists and the subtasks within them.

  const projectId = "59de4c44085a9a9f88b6d235";
  const project = trelloInterface.getProject(projectUrl);

The getMembers(taskId) Method

The getMembers() method will return all members who are assigned to the task corresponding to the taskId. The members will be in an array and will contain their full name and username.

  const taskId = "sdlk213411jf26d235";
  const members = trelloInterface.getMembers(taskId);

The updateTask(taskId, completed) Method

The updateTask() method will be used to update the 3rd party app for when a task is checked as completed or unchecked on Chimichanga. The parameter completed is a boolean: true if the task is completed, false if otherwise. The status code of the request will be returned.

  const taskId = "sdlk213411jf26d235";
  const updateTaskStatus = trelloInterface.updateTask(taskId, true);

The updateSubtask(taskId, subtaskId, completed) Method

The updateSubtask() method will be used to update the 3rd party app for when a subtask is checked as completed or unchecked on Chimichanga. The parameter completed is a boolean: true if the subtask is completed, false if otherwise. The status code of the request will be returned.

  const taskId = "sdlk213411jf26d235";
  const updateSubtaskStatus = trelloInterface.updateSubTask(taskId, true);

The addAttachmentByUrl(taskId, url) Method

The addAttachmentByUrl() method will update the task on the 3rd party app to include an attachment. The url parameter must be a working url to the attachment. The attachment's information is returned.

  const taskId = "sdlk213411jf26d235";
  const attachmentUrl = 'www.somelinktoattachment.com/asdfas.jpeg';
  const attachment = trelloInterface.addAttachmentByURL(taskId, attachmentUrl);

The createWebhook(projectId, callbackUrl) Method

The createWebhook() method will create a webhook for a project. The webhook will listen to any updates made within the project. The webhook will send the webhook responses to the callbackUrl. The callbackUrl requires a get method and a post method. In the post method for the callbackUrl, you can access the data for the update like so:

  router.post('/', async function(req, res, next) {
    const action = req.body.action;
    //do something with action
  });

The formatWebhookRes(res) Method

The formatWebhookRes() method is used to format webhook responses that are relevant for Chimichanga. Going back to the post method for the callbackUrl, one can format the response using the method to have only relevant information. The method will also return 'undefined' if the update on the 3rd party app is not relevant for Chimichanga.

  router.post('/', async function(req, res, next) {
    const action = req.body.action;
    //format the response!
    trelloInterface.formatWebhookRes(action);
  });

List of actions that the createWebhook will listen to

• ADD TASK

• ADD SUBTASK

• ADD ASSIGNEE

• ADD DOCUMENT

• DELETE TASK

• DELETE SUBTASK

• DELETE ASSIGNEE

• UPDATE TASK

• UPDATE PROJECT

• UPDATE SUBTASK