Upload files by URL

In this example, you will upload a file to a message in Flowdock by passing the URL reference of the file. The workflow is triggered by a new file arriving in a specified Box folder, allowing you to automate team discussion on new requirements that have been approved by product managers.

Also see the how-to on Files by URL reference.

Flowdock is a hub for team collaboration that enables a variety of inbox and discussion features for business teams or development groups.

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.

File-reference

The file-referenceSpecification Extension A Nintex-specific OpenAPI Specification key that allows special functionality within Nintex Xtensions. is a key-value pair added to a parameter A piece of information passed to a third-party API during a request. object, to tell Nintex Automation Cloud that this parameter is a URL to a file. In the 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. configuration panel, the designer is able to select a file variable within the workflow to send, rather than having to configure the file URL.

To use file-reference, use a key of format, with the value x-ntx-file-reference. The parameter object must always have a type of string.

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 Flowdock account:

If you do not already have a Flowdock account, create a free account here.
Inside your Flowdock account, open your Account page.
Click Developer Applications.
Click New Application.
Add the Name, Description, App URL, and the OAuth Redirect URL of https://us.nintex.io/connection/api/Token.
Click Save.
Record the Client ID and Client Secret somewhere secure. You will need these to import the Xtension into Nintex Automation Cloud.

Send a file by reference

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.with a host of api.flowdock.com, and 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..
Defines three get operations A single request to a third-party API. Operations often become actions in the workflow designer.:

/flows, with no parameters, that lists the available flows.
/organizations, with no parameters, that lists the available organizations.
/flows/{organization}/{flow}/messages/ that lists the available messages:
- Using x-ntx-dynamic-values with the two 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.parameters, organization and flow.
- Using a string parameter of event in the query Part of the URL that does not fit into the path structure, and provides additional information or parameters for the request. The query is prefaced by a question mark (?) in the URL, for example: http://example.com?color=blue. with a single enum value of message.

All three get operations are hidden using x-ntx-visibility.
For more information about using x-ntx-visibility, see x-ntx-visibility.

Defines one post operation of /flows/{organization}/{flow}/messages/{message}/comments that posts a file:

Using x-ntx-dynamic-values with the two path parameters, organization and flow.
With two string parameters, content and event, defined 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..
With the event parameter given a single enum value of comment.
With both parameters in the body being required.

For more information on using x-ntx-dynamic-values, see x-ntx-dynamic-values.

Copy

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Flowdock"
    },
    "host": "api.flowdock.com",
    "schemes": [ "https" ],
    "produces": [ "application/json" ],
    "security": [
        {
            "oauth2": []
        }
    ],
    "paths": {
        "/flows": {
            "get": {
                "summary": "List flows",
                "operationId": "listflows",
                "description": "List the flows available",
                "x-ntx-visibility": "internal",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/organizations": {
            "get": {
                "summary": "List organizations",
                "operationId": "listorgs",
                "description": "List the organisations available",
                "x-ntx-visibility": "internal",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/flows/{organization}/{flow}/messages/": {
            "get": {
                "summary": "List messages",
                "operationId": "listmessages",
                "description": "List the messages available",
                "x-ntx-visibility": "internal",
                "parameters": [
                    {
                        "name": "organization",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "x-ntx-summary": "Select your organization",
                        "x-ntx-dynamic-values": {
                            "operationId": "listorgs",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "flow",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "x-ntx-summary": "Select the flow (group)",
                        "x-ntx-dynamic-values": {
                            "operationId": "listflows",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "event",
                        "in": "query",
                        "type": "string",
                        "enum": [ "message" ],
                        "x-ntx-summary": "Select 'message'",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/flows/{organization}/{flow}/messages/{message}/comments": {
            "post": {
                "summary": "Upload file",
                "operationId": "addfile",
                "description": "Add a file via a comment",
                "x-ntx-summary": "Add a file to Flowdock ",
                "parameters": [
                    {
                        "name": "organization",
                        "type": "string",
                        "in": "path",
                        "required": true,
                        "x-ntx-summary": "Select your organization",
                        "x-ntx-dynamic-values": {
                            "operationId": "listorgs",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "flow",
                        "type": "string",
                        "in": "path",
                        "required": true,
                        "x-ntx-summary": "Select the flow (group)",
                        "x-ntx-dynamic-values": {
                            "operationId": "listflows",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "message",
                        "type": "number",
                        "in": "path",
                        "required": true,
                        "x-ntx-summary": "Select the message to add a file to",
                        "x-ntx-dynamic-values": {
                            "operationId": "listmessages",
                            "value-title": "content",
                            "value-path": "id"
                        }
                    },
                    {
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "required": [ "content", "event" ],
                            "properties": {
                                "content": {
                                    "type": "string",
                                    "x-ntx-summary": "File to upload"
                                },
                                "event": {
                                    "type": "string",
                                    "enum": [ "comment" ],
                                    "x-ntx-summary": "Select 'comment'"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "securityDefinitions": {
        "oauth2": {
            "type": "oauth2",
            "flow": "accessCode",
            "authorizationUrl": "https://api.flowdock.com/oauth/authorize",
            "tokenUrl": "https://api.flowdock.com/oauth/token",
            "scopes": {}
        }
    }
}

Step 2: Add the file-reference format to the parameter

In the content parameter in the /flows/{organization}/{flow}/messages/{message}/comments operation, define the properties as:

A type of string.
A format of x-ntx-file-reference.

Copy

 
"parameters": [
    {
        "name": "body",
        "in": "body",
        "required": true,
        "schema": {
            "required": [
                "content"
            ],
            "type": "object",
            "properties": {
                "content": {
                    "type": "string",
                    "x-ntx-summary": "File to upload",
                    "format": "x-ntx-file-reference"
                }
            }
        }
    }
]

The OpenAPI Specification

Copy

 		
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Flowdock"
    },
    "host": "api.flowdock.com",
    "schemes": [ "https" ],
    "produces": [ "application/json" ],
    "security": [
        {
            "oauth2": []
        }
    ],
    "paths": {
        "/flows": {
            "get": {
                "summary": "List flows",
                "operationId": "listflows",
                "description": "List the flows available",
                "x-ntx-visibility": "internal",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/organizations": {
            "get": {
                "summary": "List organizations",
                "operationId": "listorgs",
                "description": "List the organisations available",
                "x-ntx-visibility": "internal",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/flows/{organization}/{flow}/messages/": {
            "get": {
                "summary": "List messages",
                "operationId": "listmessages",
                "description": "List the messages available",
                "x-ntx-visibility": "internal",
                "parameters": [
                    {
                        "name": "organization",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "x-ntx-summary": "Select your organization",
                        "x-ntx-dynamic-values": {
                            "operationId": "listorgs",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "flow",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "x-ntx-summary": "Select the flow (group)",
                        "x-ntx-dynamic-values": {
                            "operationId": "listflows",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "event",
                        "in": "query",
                        "type": "string",
                        "enum": [ "message" ],
                        "x-ntx-summary": "Select 'message'",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/flows/{organization}/{flow}/messages/{message}/comments": {
            "post": {
                "summary": "Upload file",
                "operationId": "addfile",
                "description": "Add a file via a comment",
                "x-ntx-summary": "Add a file to Flowdock ",
                "parameters": [
                    {
                        "name": "organization",
                        "type": "string",
                        "in": "path",
                        "required": true,
                        "x-ntx-summary": "Select your organization",
                        "x-ntx-dynamic-values": {
                            "operationId": "listorgs",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "flow",
                        "type": "string",
                        "in": "path",
                        "required": true,
                        "x-ntx-summary": "Select the flow (group)",
                        "x-ntx-dynamic-values": {
                            "operationId": "listflows",
                            "value-title": "parameterized_name",
                            "value-path": "parameterized_name"
                        }
                    },
                    {
                        "name": "message",
                        "type": "number",
                        "in": "path",
                        "required": true,
                        "x-ntx-summary": "Select the message to add a file to",
                        "x-ntx-dynamic-values": {
                            "operationId": "listmessages",
                            "value-title": "content",
                            "value-path": "id"
                        }
                    },
                    {
                        "name": "body",
                        "in": "body",
                        "required": true,
                        "schema": {
                            "required": [ "content", "event" ],
                            "properties": {
                                "content": {
                                    "type": "string",
                                    "x-ntx-summary": "File to upload",
                                    "format": "x-ntx-file-reference"
                                },
                                "event": {
                                    "type": "string",
                                    "enum": [ "comment" ],
                                    "x-ntx-summary": "Select 'comment'"
                                }
                            }
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "securityDefinitions": {
        "oauth2": {
            "type": "oauth2",
            "flow": "accessCode",
            "authorizationUrl": "https://api.flowdock.com/oauth/authorize",
            "tokenUrl": "https://api.flowdock.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 by a file being added to the Approved folder in your Box account, and sends that file to a message in your Flowdock organization.

For more information on creating workflows, see the Workflow Designer.

Configure the Start event to be a Box: New File event:
- Select the folder where new uploads will trigger the workflow. For example, Approved.
- Click to add the File variable start variable to the workflow.
  For more information, see Box - New File.
Drag an Add a file to Flowdock action after the start event.
Configure the Add a file to Flowdock action:
1. Select message in the event field.
2. Select the organization within Flowdock you want to send the file to.
3. Select the flow you want to send the file to.
4. Select the message you want to attach the file to.
5. Select the File variable from the start event as the File to attach.
6. Select comment in the Select comment field.
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.
The file is added to the Flowdock message.