asana-connector
Web icon

Asana Connector

icon_trusted
Stable version 2.1.0 (Compatible with OutSystems 11)
Other versions available for 10 and Older
Published on 04 December 2018 by 
5.0
 (7 ratings)
asana-connector

Asana Connector

Documentation


Before you start using the Asana Connector, there are a few steps you must take. Since the Asana Connector relies on the OutSystems Platform's REST capabilities, you must:

- Configure your server to connect to Asana;

- Create an account in Asana;

- Register your Application in Asana;

- Obtain the Configuration Data;

- Test the Asana Connector.

Lost? Don't worry! We will guide you through all the necessary steps and get you connected in no time.

Configure your server to connect to Asana

Asana enforces security policies across both their organization and services. One of these policies concerns supported TLS versions for all of their communications, including REST APIs.

This means that your OutSystems Platform installation needs to be configured to conform to these restrictions or this connector will NOT work. For further details on how to achieve this, please check out this Knowledge Base article on the subject.

Create an account in Asana

In order to start using the Asana Connector, you'll need to have an account in Asana. If you haven't got one already, you can create it here.

Register your application in Asana

After creating an Asana account and signing in, go to your account settings and do the following steps.

    1. Click on My Profile Settings located at the top right corner of the screen:

    2. Select the Apps Tab and then click on the Manage Developer Apps:

 

  

3. Click on the Add New Application:

 

3. Fill in the following mandatory fields and click Create:

      App Name: The name you wish to give your application.

      App URL: The Connector's Demo Page (https://your-personal.outsystemscloud.com/AsanaConnector_Demo/Demo.aspx)

      Redirect URL: The Asana Callback page provided in the AsanaConnector eSpace (https://your-personal.outsystemscloud.com/AsanaConnector/Callback.aspx)



Obtain the Configuration Data

Now that the application is created you should be able to  view the Client ID and the Client Secret:



Since we have all of the necessary information we should open the Asana Connector Configuration page and insert the Client ID and Client Secret in their corresponding fields and then click on the Save button to save them:



Test the Asana Connector

Open the Asana Connector Demo page and click on the Sign In with Asana button:

If you are not logged in then you will be redirected to the Asana login page where you need to provide your Asana E-mail and password:


After successfully logging in, you need to grant the connector permission to access your Asana account by clicking on the Allow button:


If the Asana Connector successfully connects to your Asana account then you should see a page with some of your basic information similar to the one below: 

How to implement the AsanaConnector into your application 

We will be using the AsanaConnector as a base to explain the implementation.

First of all, we should configure your server to connect to Asana, in order to do it you will need the ClientId and ClientSecret as explained before, and you’ll need to use the AsanaToken_Set action, this action will set the session token used as authorization in Asana.

This is a mandatory step that you will need to do to connect with asana, in the next step we will show you how to show and interact with the projects and tasks of Asana.

After you make the configurations you can start using the other actions, so let's take a look at them.

AsanaUser_GetAll

This action returns a list with all the users and respective data for all the workspaces and organizations of the associated asana account.

AsanaUser_Get

This action receives the AsanaUserId and returns you the correspondent AsanaUser structure with the user data.

Workspaces_Get

This action gets all the workspaces configured in the connected asana account, this will return a list of workspaces with the respective Id and name.

Workspace_GetAllProjects

Given a workspaceId this action will return the list of projects associated with the workspace, each project will have an Id and name as well.

Workspace_GetAllTasks

This one will return you a list of tasks according to the search criteria if no input is filled it will just return all the tasks through all the workspaces of the current account. 


Let's take a look at the inputs.

  • WorkspaceId - The ID of the workspace or organization to filter tasks on

Note: If you specify a workspace you must also specify an assignee to filter on.

  • AssigneeId - The ID of the assignee to filter tasks on. Only unarchived tasks in the assignee's list will be returned. 

Note: If you specify an assignee, you must also specify a workspace to filter on.

  • ProjectId - The ID of a project to get tasks from. Only unarchived tasks in the project will be returned.

  • TagId - The ID of a tag to filter the tasks.

  • CompletedSince - Only return tasks that are either incomplete, or completed since the given time. 

  • ModifiedSince - Only return tasks that have been modified since the given time. 

  • Limit - The number of objects to return per page. The value must be between 1 and 100.

  • Offset - The number of the index of the first position of the list of tasks.


Project_GetAllTasks

This one will return you all the task of a project given the project id.


Stories_GetFromTask

You also have this action that returns you the story of a task given the TaskId.

Then for each task you have several actions that you can perform.

Task_New

With this action, you can create a new task the action receives a structure with the task information and returns you the created task.

Task_Delete

It receives the TaskId and deletes a Task.

Task_Get

Receives the TaskId and returns you the correspondent Task.

Task_NewSubTask

This action receives as inputs the TaskInfo structure that will be the subtask and the parent task identifier and returns you a Task structure with the created subtask.

Task_AddComment

This one will add a comment to the task, in order to do it the task receives the TaskId, the text of the comment and the Asana User Id that made the comment, it will then return the comment structure of the created comment.

Attachment_AddToTask

As the name suggests this action is used to add an attachment to an existing task, it will receive the TaskId, FileContent, FileName, FileContentType and will return you the created attachment Id and Name. 

Attachments_GetFromTask

This action returns you the list of attachments (just the attachment identifier and name) of a task given the TaskId.

Attachment_Get

This action given the AttachmentId will return you an attachment structure with the URL to download the actual attached file.

AttachmentBinary_Get

This action can be used in conjunction with the previous one because it used the URL to get the binary data of the file, this way you can manage the download of the file through the outsystems side instead of making the user download it through an external url.

Tag_Create

This action will create a tag in the context of a workspace, to do it receives as input the WorkspaceId, and the tag Name, optionally you can also specify a color for the tag and add notes. The action will then return the created tag.

Tag_Get

It receives the TagId and returns you the tag.

Task_AddTag

This action makes an association between a Task and an existing Tag, in order to do it it receives both the TaskId and the TagId.

Task_RemoveTag

This one has the same inputs as the previous one but instead of adding a tag it removes it.

Now that we have explained all of the actions we will continue to see how the demo is implemented.

So basically in the preparation of the demo the first thing we are doing is check if the asana connector is configured by checking if the ClientId or the ClientSecret site properties are empty.

The next thing we are doing is getting all the workspaces and for each workspace get all the projects.

Now to show the tasks of each project we have a link on the project name the refresh the task block and switch between the tasks of the different projects. (we have the same logic for the workspaces)

Inside the Tasks webblock we have some layers of webblocks that basically let us make some filters but we really don’t need to worry about that to understand how the component works, you can do it in your own way, what we really are interested in is that through this webblocks we are passing the ProjectId and in the preparation of the TaskListBlock we are getting the tasks corresponding to the current ProjectId or to all projects of the current workspace if the ProjectId is empty. This is being done in the GetTaskObjectList action but the flow doesn’t end here, since the GetTaskObjectList just return the TaskId and Name of the tasks, we are then using the ConvertObjectsToTaskList to get all the task data for each task (this is just  because we are displaying more information than just the task name in the list, but if you just want to show the name you don’t really need to do it).

The rest of the flow is just us filtering the list of tasks according to the status that the user clicked in.

Let's jump to how are we handling the tasks, basically, the list of tasks is clickable and through some events, we are getting the TaskId of the clicked task on the demo screen.

Then on the handler of the webblock, we are getting the task and showing the task details on the side bar.

On the sidebar we can perform some actions to the current task, first at the top of the sidebar we can go to the TaskDetailsScreen that will show us a more detailed version of the tasks, and we can delete the task, the delete action beside deleting the task will also trigger an event that are being used on the Demo screen to close the sidebar.

Then we have some details about the task and at the end of the page, we have a webblock with the list of stories and zone to make comments. Then inside this webblock, we have the TaskStories and the AddTaskComment webblocks, on the TaskStories webblock we receive the TaskId and DisplayedCommentsNumber that will be the number of stories to display on the screen and on the preparation we get the stories correspondent to the current TaskId and sort them descending by creation date.

On the AddTaskComment we have the input field to write the comment and a button to trigger the action that saves the comment and an event that will be used to refresh the list of stories.

We have yet to explain to you how to create a new task. At the top right corner of the Demo screen you have a button the will show the modal to create a new task, inside this modal you have the NewTaskOrSubtask webblock (used to either create a task or subtask) the have several input fields that correspond to the task fields, the only special note here is that we are getting the list of users associated to the workspaces and organizations of the current asana account to show them in the assignee combo box.

Then on the action of the save button, we are making some validations and according to if we have a TaskId or not we create a SubTask or a Task, to finalize we trigger an event that will be used to close the modal and refresh the list of tasks.

The only thing left to explain is the attachments of the tasks, on TaskDetailsScreen we have the Attachments webblock that show you the list of attachments and lets you upload new ones. On the AttachmentsList webblock preparation, we get the list of Attachments for the current TaskId.

Then on the name of the attachments of the list we have a link that trigger an action that lets you download the attachment file, in order to do it use both the Attachment_Get to get the name and URL of the file and the AttachemntBinary_Get to get the binary of the file through the URL, with all that we finalize the flow with the download that uses both the file binary and name to download the attachment. 

To finalize on the AddAttachmentToTask webblock we use the upload widget that will receive the attachment file, then on the attach button we validate if the user had chosen a file and if true we use the Attchment_AddToTask action to attach the file to the current task.