microapp development walk-through integrating asana into ... · configure the integration 1. create...

Microapp Development Walk-through Integrating Asana into Citrix Workspace

PUBLISHED BY Citrix Systems, Inc. 851 West Cypress Creek Road Fort Lauderdale, Florida 33309 USA

http://www.citrix.com

Copyright © 2019 by Citrix Systems, Inc.

All rights reserved. Citrix, the Citrix logo are trademarks of Citrix Systems, Inc. and/or one or more

of its subsidiaries, and may be registered with the U.S. Patent and Trademark Office and in other

countries. All other marks appearing herein are the property of their respective owners.

Citrix Systems, Inc. (Citrix) makes no representations or warranties with respect to the content or

use of this publication. Citrix specifically disclaims any expressed or implied warranties,

merchantability or fitness for any particular purpose. Citrix reserves the right to make any changes

in specifications and other information contained in this publication without prior notice and

without obligation to notify any person or entity of such revisions or changes.

No part of the publication may be reproduced or transmitted in any form or by any means, electronic or mechanical, including photocopying, recording or information storage and retrieval systems, for any purpose other than the purchaser’s personal use, without express written permission of.

http://www.citrix.com/

Table of Contents Create a simple integration with Asana and create a microapp ........................................................... 4

Configure the integration ...................................................................................................................... 5

1. Create HTTP integration with Asana .......................................................................................... 5

2. Add Tasks Data Endpoint ............................................................................................................ 7

3. Add Projects Data Endpoint......................................................................................................10

4. Add new service action .............................................................................................................12

5. Create service action to Add a Comment to the task ..............................................................14

6. Add Mark task as completed service action .............................................................................16

7. Finish Asana integration configuration ....................................................................................18

Create and configure microapp ........................................................................................................... 19

1. Create microapp .......................................................................................................................19

2. Add create new task page ........................................................................................................20

3. Add task detail page .................................................................................................................25

4. Add a notification when a task is created ................................................................................30

5. Add a notification when a task is changed ...............................................................................33

6. Test your microapp ...................................................................................................................35

Appendix .............................................................................................................................................. 36

1. Set up third-party application access in Asana.........................................................................36

Create a simple integration with Asana and create a microapp

This document describes how to implement the following use-cases in Citrix Workspace

microapps. For this integration we will address the following use-cases:

• Notify user when assigned tasks are created or changed

• Let user to create a new task

• Let user mark task complete

You must meet the following prerequisites:

• Have an Asana user account

• Know your Asana workspace ID

• Have a Citrix Cloud account and be logged in to Citrix Workspace microapps

Configure the integration

1. Create HTTP integration with Asana

1.1. Open the Citrix Workspace microapps admin UI.

1.2. Click on the Manage tab at the top of the page.

1.3. Click on the Add New Integration. A list of integrations that we support out of the

box are displayed.

1.4. Select the HTTP icon.

1.5. Enter the following information for the integration:

Name: Asana integration

Base URL: https://app.asana.com/api/1.0/

Service Authentication: Bearer

Token: ${YOUR_ACCESS_TOKEN}

1.6. Optionally, you can choose OAuth as a service action authentication:

Grant type: Authorization code

Token URL: https://app.asana.com/-/oauth_token

Scope: default

Client ID: your_client_id

Client secret: your_secret

Authorization URL: https://app.asana.com/-/oauth_authorize

See appendix 1.7 to set up OAuth in asana.

2. Add Tasks Data Endpoint

2.1. Navigate to Data Loading in your Asana integration.

2.2. Click Add new Data Endpoint.

2.3. Configure new tasks endpoint:

Endpoint Name: Tasks

Endpoint URI: workspaces/${YOUR_WORKSPACE_ID}/tasks/search

Request Method: GET

Replace ${YOUR_WORKSPACE_ID} with your workspace id (ex. 419224638481718). If you do not know

the workspace id log in to https://app.asana.com and call https://app.asana.com/api/1.0/workspaces in

different tab.

2.4. Configure QUERY parameters:

Name: completed

Data type: STRING

Value: false

Name: opt_fields

Data type: STRING

Value:

name,completed,notes,assignee_status,created_at,completed_at,due_on,a

ssignee.email,parent.name,projects.name

2.5. Select the Link pagination type.

Asana uses link based pagination see https://asana.com/developers/documentation/getting-

started/pagination

JSON Path to next page link…: next_page.uri

2.6. Click Test Service.

The test is successful with 200 http code. The response should be like this:

{

"next_page": {

"offset": "yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9",

"path": "/tasks?project=…&limit=5&offset=yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9",

"uri": "https://app.asana.com/api/1.0/tasks?project=...&limit=5&offset=yJ0eXAiOiJKV1QiLCJhbGciOiJIRzI1NiJ9"

https://app.asana.com/

https://app.asana.com/api/1.0/workspaces

https://asana.com/developers/documentation/getting-started/pagination


},

"data": [

{

"id": 1139016971395847,

"gid": "1139016971395847",

"assignee": null,

"assignee_status": "upcoming",

"completed": false,

"completed_at": null,

"created_at": "2019-09-09T13:01:02.660Z",

"due_on": null,

"name": "Task 1",

"notes": "",

"parent": null,

"projects": [

{

"id": 1139016971395844,

"gid": "1139016971395844",

"name": "Testing project"

}

]

},

…

]

}

2.7. Click Load tables.

The tables for the HTTP response structure are generated.

2.8. Click the Edit attributes for tasks_data table to configure missing primary key.

2.9. Toggle the primary key switch for id attribute.

2.10. Click Add to finish endpoint creation.

3. Add Projects Data Endpoint The synchronized projects from Asana will be used during ticket creation. Projects will be assigned to the

particular task on “Create new task” page.

3.1. Navigate to Data Loading on your Asana integration.

3.2. Click Add new Data Endpoint.

3.3. Configure new tasks endpoint.

Name: Projects

Endpoint URI: workspaces/${YOUR_WORKSPACE_ID}/projects

Request Method: GET

Replace ${YOUR_WORKSPACE_ID} with your workspace id (ex. 419224638481718). If you do not know

the workspace id log in to https://app.asana.com and call https://app.asana.com/api/1.0/workspaces in

different tab.

3.4. Select the Link pagination type.

Asana uses link based pagination see https://asana.com/developers/documentation/getting-

started/pagination

JSON Path to next page link…: next_page.uri

3.5. Click Test Service.

The test is successful with 200 http code.


https://app.asana.com/api/1.0/workspaces



3.6. Click Edit attributes for projects_data table to configure missing primary key.

3.7. Toggle the primary key switch for id attribute.

3.8. Click Add to finish endpoint creation.

4. Add new service action

The following steps will guide you through the service action configuration. The service

action will create task within some project evetime it is performed.

See the API reference documentation https://asana.com/developers/api-reference/tasks#create

4.1. Navigate to Service Actions on the side menu.

4.2. Click Add New Service Action.

4.3. Configure service action.

Action name: Create task

Endpoint URI: /tasks

Requested Method: POST

4.4. Configure QUERY parameters.

Name: projects

Data type: STRING

Is required: true

https://asana.com/developers/api-reference/tasks#create

4.5. Configure parameters of BODY of HTTP put request.

Content type: Form URL Encoded

Name: name

Data type: STRING

Is required: true

Name: notes

Data type: STRING

Is required: true

4.6. Click Add to finish the service action creation.

5. Create service action to Add a Comment to the task

The following steps will guide you through the service action configuration. The service

action will add comments to the existing task.

See the API reference documentation https://asana.com/developers/api-reference/stories




Action name: Add comment to the task

Endpoint URI: tasks/{{taskId}}/stories


The {{taskId}} will be replaced from configured PATH parameter.

5.4. Configure PATH parameters.

Name: taskId

Data type: STRING

Is required: true



Name: text

Data type: STRING

Is required: true

https://asana.com/developers/api-reference/stories

5.6. Click Add to finish the service action creation.

6. Add Mark task as completed service action

The service action will update the existing task with a change of completed attribute to

true.

See the API reference documentation https://asana.com/developers/api-reference/tasks#update




Action name: Mark task as completed

Endpoint URI: tasks/{{taskId}}


The {{taskId}} will be replaced from the configured PATH parameter.

6.4. Configure PATH parameters.

Name: taskId

Data type: STRING

Is required: true



Name: completed

Data type: BOOLEAN

https://asana.com/developers/api-reference/tasks#update

Default value: true

Is required: false

6.6 Click Add to finish the service action creation.

7. Finish Asana integration configuration

7.1. Navigate to Manage tab at the top of the page.

7.2. Click Synchronization in the Asana integration action menu.

7.3. Trigger the synchronization by click on the blue arrow marked All.

The endpoints will be synchronized shortly.

Create and configure microapp

1. Create microapp

1.1. Navigate to the list of integrations.

1.2. Select Add Microapp from the menu.

1.3. Navigate to Properties on the left menu and configure the basic attributes of the

app.

App name: Notify the tasks microapp

App icon:

2. Add create new task page

2.1. Navigate to Pages on the left panel.

2.2. Click Add New Page.

2.3. Enter the page properties.

Page name: Create task

Page template: Form

Select the table generated when creating “Tasks” data endpoint (Section 2) as a data source

Data source: Asana integration

Data Table: Tasks Data

2.4. Click Select Fields.

2.5. Deselect all fields by selecting the checkbox on column header.

2.6. Configure on the editable page preview a page design like what is pictured below:

Use static text for page headline,

text input for “Name” field,

text area for “Notes” field,

select for “Project” field. (Configuration of select data will be shown in 2.7)

Use Flexible grid with 2 cells and 2 cell per row to achieve nicer layout.

2.7. Click Project text input in editable page preview.

2.8. Open Select properties tab and configure:

Select type: Select from Database

Data source for options: Asana data integration (your asana integration)

Data table for options: projects_data (the table created in “project” endpoint

creation 3) Data column for option label: name

Data column for option id: id

2.9. Click Create task in editable page preview.

2.10. Open Actions tab and configure:

Add action: Run service

Data: Asana integration (your asana integration)

Action: Create task (the action created in 4 Add new service action)

2.11. Click Edit parameters.

2.12. Edit parameters for the service action (see the picture).

All values for service action are taken from particular page component values.

2.13. The Page is created. See the status on list of pages.

3. Add task detail page

3.1. Navigate to Pages on the left panel.

3.2. Click + Add Page on the top right side of the page.

3.3. Enter the page properties:

Page name: Task detail

Page template: Detail

Select the table generated while creating “Tasks” data endpoint (Section 2) as a data source


Data Table: Tasks Data

3.4. Click Select Fields.

3.5. Select “name” and “notes” field.

3.6. Click Set columns and Add to create the page.

3.7. Configure on the editable page preview a page design like what is pictured below:

Use static text component for page headline,

text component for “Name”, “Notes”, “Project” field

Use the text Area for “Comment”.

Use Flexible grid with 2 cells and 2 cell per row to achieve nicer layout.

3.8. Select each component and configure data source in text properties tab:


Data Table: tasks_data

Data column:name,notes…


Data Table: tasks_data_projects

Data column: name

3.9. Click Create task in the editable page preview.

3.10. Open Actions tab and configure the two service actions, in order.


Action label: Comment task


Action: Add comment to task (created in 5 Create service action to Add a Comment to the

task) Action parameters:

The taskId is taken from the column value of the opened task detail.

The text value for service action is taken from the comment component.


Action label: Complete task


Action: Mark task as completed (created in 6 Add Mark task as completed service action) Action parameter:

The taskId is taken from the column value of the opened task detail.

3.11. The Page is created by now. See the status in the list of pages.

4. Add a notification when a task is created

4.1. Navigate to Notifications on the left panel.

4.2. Click Add New Notification.

4.3. Configure the basic properties of the notification:

Notification name: When new task is created

Notification trigger event: New records


Data table: Task Data

4.4. Change the trigger for the notification:

After Data Synch

of

Asana integration (the integration created at 1 Create HTTP integration with Asana).

4.5. Modify the user which should be notified. See the image below.

4.6. Change the content of the card:

Content type: Notification

Card Title: The new task '{{name}}' created

The variable {{varName}} can be selected from the select box by clicking on the “Insert variable”.

Card Body:

The new task '{{name}}' has been assigned to you.

{{notes}}

Card Timestamp: created_at DB column App to Go to: Notify the tasks microapp

Page to go: Task detail (created in 3 Add task detail page) When the underlying record is deleted: true

5. Add a notification when a task is changed

5.1. Navigate to Notifications in the left panel.

5.2. Click + Add Notification on the top right side of the page.

5.3. Configure the basic properties of the notification:

Notification name: When task is changed

Notification trigger event: Changed records


Data table: Task Data

5.4. Change the trigger for the notification:

After Data Synch

of

Asana integration (the integration created at 1 Create HTTP integration with Asana)

5.5. Configure the condition when the notification is triggered:

Where

column “name” on table “task_data” changes

or

column “notes” on table “task_data” changes

or

column “assignee_email” on table “task_data” changes

5.6. Modify user which should be notified. See the image below.

5.7. Change the content of the card:

Content type: Notification

Card Title: Task '{{name}}' has changed

The variable {{varName}} can be selected from the select box by clicking on the “Insert variable”.

Card Body:

{{notes}}

Card Timestamp: created_at DB column

App to Go to: Notify the tasks microapp

Page to go: Task detail (created in 3 Add task detail page)

6. Test your microapp

6.1. Navigate to Preview microapp link in the top right corner.

6.2. See the app preview which should be like the screenshot below:

6.3. Click the card and create the Complete task action button on the page.

6.4. Check the task in https://app.asana.com to verify that the task has been commented

on and marked as closed.

Appendix

1. Set up third-party application access in Asana Note: You must upgrade your account to at least Premium to access the search API.

1.1. Log in to https://app.asana.com/.

1.2. Click your avatar in the right corner.

1.3. Select my profile settings.

1.4. Choose App tab.

1.5. Click Manage Developer Apps.


https://asana.com/developers/documentation/getting-started/search-api


1.6. Select preferred authentication method.

1.7. In case you want to use OAuth, add New App:

1.7.1. Copy your client id and Client secret to some secret place.

1.7.2. Assign your workspace redirect URL to your app.

1.8. In case you prefer Bearer token/Personal access choose New access token option:

1.8.1. Provide the name.

1.8.2. Copy your token to some secret place.

microapp development walk-through integrating asana into ... · configure the integration 1. create...

Documents