Upload files by streaming
|
In this example, you will use file streaming to attach a file to a newly-created task in the project management service Asana. The workflow is triggered by a new file arriving in a specified Box folder, allowing you to automate your task management processes. Also see the how-to on Files as multipart formdata. |
Asana is a popular project management tool for teams and individuals, allowing you to create projects and tasks, attach files from cloud services or upload them to Asana directly, and manage discussion around your tasks. All tasks belong to a workspace and are assigned to a member of your Asana team.
The operation A single request to a third-party API. Operations often become actions in the workflow designer. of creating a task returns the task id, which we pass to the next workflow action A task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. which attaches the file. Because the OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. does not allow more than one definition for an endpoint The address of a specific resource provided by the third-party API. and HTML method, the attach-file operation cannot provide a drop-down value to select an existing task in the designer, so it can only add files to new tasks. If you wanted to extend this workflow to attach files to existing tasks, you could:
- Add another operation that returns the task id of a searched-for task to use with the attach file operation.
- Create a serverless function A service that allows you to run code without provisioning and managing a web serve to host it. Examples include Amazon Web Services and Microsoft Azure. to combine the operations of creating a task and attaching a file, and rewrite the existing attach-file operation to attach to an existing task.
This example uses dynamic-values to allow the designer to select the workspace and assignee for the new task. For more information on dynamic-values, see x-ntx-dynamic-values.
The complete OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. and icon for this example are available here.
Tip: Want the short version? Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.
Register a client ID and secret
To import the completed Xtension A set of instructions for Nintex Automation Cloud to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control. , you must create the client ID and shared secret in your Asana account:
- If you do not already have an Asana account, create a free account here.
- Inside your Asana account, open your Account settings page.
- Click Manage Developer Apps.
- Click Add New Application.
- Add the App Name, App URL, and the Redirect URL of https://us.nintex.io/connection/api/Token.
- Click Create.
- Ensure Authorization Code Grant is selected.
- Record the Client ID and Client Secret somewhere secure. You will need these to import the Xtension into Nintex Automation Cloud.
Create the Xtension
Step 1: Create the basic OpenAPI Specification
Create an OpenAPI Specification that:
- Uses https Hypertext Transfer Protocol Secure: the protocol by which websites and APIs communicate securely over the internet.on a host The domain name of the third-party API's URL.of app.asana.com with a basePathof /api/1.0.
- Uses OAuth2.0 A two-step authorization protocol that both identifies the requestor, and allows a user to grant access to a third-party account without revealing their credentials to the requesting software. security.
- Defines four operations:
- /workspaces using the get method and no parameters A piece of information passed to a third-party API during a request., that returns an array of workspace objects with names and ids.
- /users using the get method and no parameters, that returns an array of user objects with names and ids.
- /tasks using the post method and parameters in the body The part of an HTTP request or response that can contain an arbitrary amount of data, such as the content of a form or web page.to define the workspace and assignee (using x-ntx-dynamic-values), and the name and notes on the task; and returns an object that contains an object that includes the task id of the new task. The workspace, name and assignee are required.
- /tasks/{task_id}/attachments using the post method to attach a file to the task, with the task id in the path The part of the URL after the hostname that directs the request to a specific resources within the host. For example, the section after "example.com" in http://example.com/this/is/a/path..
Add "x-ntx-visibility" : "internal" to the /workspaces and /users operations to hide them from the workflow designer, as they're not useful to the designer.
For more information on using x-ntx-dynamic-values and x-ntx-visibility see:
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Asana"
},
"host": "app.asana.com",
"basePath": "/api/1.0",
"schemes": [ "https" ],
"produces": [ "application/json" ],
"consumes": [ "application/json" ],
"security": [
{
"oauth2": []
}
],
"paths": {
"/workspaces": {
"get": {
"summary": "List workspaces",
"description": "Lists all workspaces the authenticated user can access",
"operationId": "ListWorkspaces",
"x-ntx-visibility": "internal",
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
},
"/users": {
"get": {
"summary": "List users who can access this workspace",
"description": "Lists all users who can access this workspace",
"operationId": "ListUsers",
"x-ntx-visibility": "internal",
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
},
"/tasks": {
"post": {
"summary": "Create a task",
"description": "Create a task assigned to the selected user",
"operationId": "CreateTask",
"consumes": [ "multipart/form-data" ],
"parameters": [
{
"name": "task",
"in": "body",
"schema": {
"required": [ "workspace", "assignee", "name" ],
"properties": {
"workspace": {
"type": "string",
"x-ntx-summary": "Workspace to add task to",
"x-ntx-dynamic-values": {
"operationId": "ListWorkspaces",
"value-collection": "data",
"value-path": "id",
"value-title": "name"
}
},
"assignee": {
"x-ntx-summary": "Person to assign the task to",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "ListUsers",
"value-collection": "data",
"value-path": "id",
"value-title": "name"
}
},
"name": {
"type": "string",
"x-ntx-summary": "Title of the task"
},
"notes": {
"type": "string",
"x-ntx-summary": "Task detail"
}
}
}
}
],
"responses": {
"201": {
"description": "Created Task",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"x-ntx-summary": "Task id"
}
}
}
}
}
}
}
}
},
"/tasks/{task_id}/attachments": {
"post": {
"summary": "Attach a file to a task",
"description": "Attach a file to a specified task",
"operationId": "AttachFile",
"consumes": [ "multipart/form-data" ],
"parameters": [
{
"name": "task_id",
"type": "string",
"in": "path",
"x-ntx-summary": "Task id",
"description": "Task",
"required": true
}
],
"responses": {
"200": {
"description": "Ok"
}
}
}
}
},
"securityDefinitions": {
"oauth2": {
"type": "oauth2",
"flow": "accessCode",
"authorizationUrl": "https://app.asana.com/-/oauth_authorize",
"tokenUrl": "https://app.asana.com/-/oauth_token",
"scopes": {}
}
}
}
Step 2: Set the operation to consume multipart/form-data
In the HTTP method object of the /tasks/{task_id}/attachments operation, add a consumes array with the value multipart/form-data.
"paths": {
"/tasks/{task_id}/attachments": {
"post": {
"summary": "Attach a file to a task",
"operationId": "AttachFile",
"produces": [ "application/json" ],
"consumes": [ "multipart/form-data" ]
}
}
}
Step 3: Define the file parameter
In the parameters array of the /tasks/{task_id}/attachments operation, define a parameter object for the file:
- in with a value of formData.
- type with a value of file.
- require with a value of true.
- name with a value of file.
- description with a value of The file to attach.
"parameters": [
{
"name": "task_id",
"type": "string",
"in": "path",
"x-ntx-summary": "Task id",
"description": "Task",
"required": true
},
{
"in": "formData",
"name": "file",
"type": "file",
"required": true,
"description": "The file to attach."
}
]
The OpenAPI Specification
{
"swagger": "2.0",
"info": {
"version": "1.0.0",
"title": "Asana"
},
"host": "app.asana.com",
"basePath": "/api/1.0",
"schemes": [ "https" ],
"produces": [ "application/json" ],
"consumes": [ "application/json" ],
"security": [
{
"oauth2": []
}
],
"paths": {
"/workspaces": {
"get": {
"summary": "List workspaces",
"description": "Lists all workspaces the authenticated user can access",
"operationId": "ListWorkspaces",
"x-ntx-visibility": "internal",
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
},
"/users": {
"get": {
"summary": "List users who can access this workspace",
"description": "Lists all users who can access this workspace",
"operationId": "ListUsers",
"x-ntx-visibility": "internal",
"parameters": [],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
}
}
}
}
}
}
}
},
"/tasks": {
"post": {
"summary": "Create a task",
"description": "Create a task assigned to the selected user",
"operationId": "CreateTask",
"consumes": [ "multipart/form-data" ],
"parameters": [
{
"name": "task",
"in": "body",
"schema": {
"required": [ "workspace", "assignee", "name" ],
"properties": {
"workspace": {
"type": "string",
"x-ntx-summary": "Workspace to add task to",
"x-ntx-dynamic-values": {
"operationId": "ListWorkspaces",
"value-collection": "data",
"value-path": "id",
"value-title": "name"
}
},
"assignee": {
"x-ntx-summary": "Person to assign the task to",
"type": "string",
"x-ntx-dynamic-values": {
"operationId": "ListUsers",
"value-collection": "data",
"value-path": "id",
"value-title": "name"
}
},
"name": {
"type": "string",
"x-ntx-summary": "Title of the task"
},
"notes": {
"type": "string",
"x-ntx-summary": "Task detail"
}
}
}
}
],
"responses": {
"201": {
"description": "Created Task",
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string",
"x-ntx-summary": "Task id"
}
}
}
}
}
}
}
}
},
"/tasks/{task_id}/attachments": {
"post": {
"summary": "Attach a file to a task",
"description": "Attach a file to a specified task",
"operationId": "AttachFile",
"consumes": [ "multipart/form-data" ],
"parameters": [
{
"name": "task_id",
"type": "string",
"in": "path",
"x-ntx-summary": "Task id",
"description": "Task",
"required": true
},
{
"in": "formData",
"name": "file",
"type": "file",
"required": true,
"description": "The file to attach."
}
],
"responses": {
"200": {
"description": "Ok"
}
}
}
}
},
"securityDefinitions": {
"oauth2": {
"type": "oauth2",
"flow": "accessCode",
"authorizationUrl": "https://app.asana.com/-/oauth_authorize",
"tokenUrl": "https://app.asana.com/-/oauth_token",
"scopes": {}
}
}
}
Create the workflow
Step 1: Add your Xtension
Import the OpenAPI Specification you created into Nintex Automation Cloud:
- Open your Nintex Automation Cloud tenancy.
- Click Xtensions in the dashboard to open the Xtensions page.
- Click
in the Private connector list. - Click Choose a file. Navigate to the OpenAPI Specification on your computer.
- Wait for Nintex Automation Cloud to validate the file.
- Click Next.
- Nintex Automation Cloud detects the OAuth 2.0 security template.
- Type the Client ID in the Client ID field.
- Type the shared secret in the Client Secret field.
- Click Next.
- Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
- Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
- Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
- Click Publish.
Step 2: Create your workflow
Create a workflow that is triggered when a new file is uploaded to a specific Box folder. The workflow creates a new task in Asana for a specified person to review the file, then attaches the file to the new Asana task.
For more information on creating workflows, see the Workflow Designer.
To create the workflow:
- Click Create workflow in your Nintex Automation Cloud tenancy.
- Configure the Start event to be a Box: New File event:
- Select the folder where new uploads will trigger the workflow. For example, Review.
- Click to add the Name and File variable start variables to
the workflow.
For more information, see Box - New File.
- Drag a Create a task action after the start event.
- Configure the Create a task action:
- Select the workspace to add the task to.
- Select the person to assign the task to.
- Type a name for the task.
Tip: Add the Name variable to make each task name unique.
- Add notes directing the assignee to review the attached file.
- Create a collection variable to store the returned Task id.
- Drag an Attach a file to a task action after Create a task.
- Configure the Attach a file to a task action:
- Use the task id collection variable as the Task id.
- Select the File variable from the start event in The file to
attach.
- Publish your workflow.
Tip: If you want to troubleshoot an Xtension, select Development as the Assigned Use when you publish the workflow. Development workflows display more detailed error messages in their instance details. Republish your workflow as Production when you're ready to use it.
Step 3: Test your workflow
- Upload a new file into your Box folder.
A new task is created in Asana with the file attached.