Download files by URL

In this example, you will download a welcome package from BrickFTP via file URL reference, and email it to your customer as the first step in their onboarding process. The workflow is triggered by the customer signing up as a prospect on a web form.

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

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 response The return from a third-party API after a request has been made by the client. schema, to tell Nintex Automation Cloud that this property 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 to store the file within the workflow.

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

Register for a BrickFTP API key

To complete this example, you need a BrickFTP account and API key.

If you do not already have a BrickFTP account, sign up for a free trial here.
In the web panel of your BrickFTP account, click API.
Type a name to identify the API key in your BrickFTP account.
Click add key.
Copy the key displayed on the screen somewhere secure.
You will use it to create a connection to your BrickFTP Xtension.

Note: You should also upload an example file to send to your customers.

Receive 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 your own BrickFTP subdomain as a host The domain name of the third-party API's URL., and /api/rest/v1 as a basePath.
Uses basic authentication Identifying the API requestor using a username and password passed in the HTTP header. to pass the API key An authorization code passed in an API request, either inside the header or as a parameter, to identify the requester..
Defines two operations A single request to a third-party API. Operations often become actions in the workflow designer.:

/folders/, which takes no parameters A piece of information passed to a third-party API during a request. and lists the available files in the root folder.
/files/{filepath}, which takes the parameter of the filepath 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. and returns a download URL.
The filepath parameter uses x-ntx-dynamic-values to populate a list of files from the /folders/ operation.

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

Copy

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "BrickFTP"
    },
    "host": "nintexxtensions.brickftp.com",
    "basePath": "/api/rest/v1",
    "schemes": [ "https" ],
    "consumes": [ "application/json" ],
    "produces": [ "application/json" ],
    "security": [
        {
            "basicAuth": []
        }
    ],
    "paths": {
        "/folders/": {
            "get": {
                "summary": "List files in folder",
                "description": "List files in folder",
                "operationId": "listFiles",
                "x-ntx-visibility": "internal",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/files/{filepath}": {
            "get": {
                "summary": "Download file",
                "description": "Download file",
                "operationId": "downloadFile",
                "parameters": [
                    {
                        "name": "filepath",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "x-ntx-summary": "Select the file",
                        "x-ntx-dynamic-values": {
                            "operationId": "listFiles",
                            "value-title": "display_name",
                            "value-path": "path"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "properties": {}
                        }
                    }
                }
            }
        }
    },
    "securityDefinitions": {
        "basicAuth": {
            "type": "basic"
        }
    }
}

Step 2: Add the file object to the response properties

In the response object of 200 in the /files/{filepath} operation, add a download_uri object to the properties object:

Inside the download_uri object, define:
- A type of string
- A format of x-ntx-file-reference

Copy

 		
"responses": {
    "200": {
        "description": "OK",
        "schema": {
            "type": "object",
            "properties": {
                "download_uri": {
                    "type": "string",
                    "x-ntx-summary": "Downloaded file",
                    "format": "x-ntx-file-reference"
                }
            }
        }
    }
}

The OpenAPI Specification

Copy

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "BrickFTP"
    },
    "host": "nintexxtensions.brickftp.com",
    "basePath": "/api/rest/v1",
    "schemes": [ "https" ],
    "consumes": [ "application/json" ],
    "produces": [ "application/json" ],
    "security": [
        {
            "basicAuth": []
        }
    ],
    "paths": {
        "/folders/": {
            "get": {
                "summary": "List files in folder",
                "description": "List files in folder",
                "operationId": "listFiles",
                "x-ntx-visibility": "internal",
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/files/{filepath}": {
            "get": {
                "summary": "Download file",
                "description": "Download file",
                "operationId": "downloadFile",
                "parameters": [
                    {
                        "name": "filepath",
                        "in": "path",
                        "type": "string",
                        "required": true,
                        "x-ntx-summary": "Select the file",
                        "x-ntx-dynamic-values": {
                            "operationId": "listFiles",
                            "value-title": "display_name",
                            "value-path": "path"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "type": "object",
                            "properties": {
                                "download_uri": {
                                    "type": "string",
                                    "x-ntx-summary": "Downloaded file",
                                    "format": "x-ntx-file-reference"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "securityDefinitions": {
        "basicAuth": {
            "type": "basic"
        }
    }
}

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 basic authentication security template.

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 takes a customer's name and email address through a web form, downloads a file from BrickFTP and emails it to the customer.

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

Click Create workflow in your Nintex Automation Cloud tenancy.
Configure the Start event to be a Nintex form, with:
- A text field for the customer's name.
- An email field.
For more information on designing forms in Nintex Automation Cloud, see Design a form.
Drag a BrickFTP: Download a file action after the Start event.
Configure the Download a file action:
1. Select which file you want to download.
2. Click and select Edit to open the Store a File options.
3. In the Location options, select Connector.
4. In the Connector field, select a file sync service to store the file temporarily.
5. In the Connection field, select the connection to use with the file sync service.
6. In the Path and file name field, type the file name to store the file.
Drag a Set a variable value action after the Download a file action.
For more information, see Set a variable value.
Configure the action to store the file from the Xtension.
Drag a Send an email action after the Set a variable value action.
For more information, see Send an email.
Configure the email to send the file to the email address from the web form with a welcome message.
Click Test to test the workflow.
Save or publish the workflow.

Tip: You can extend this workflow by using actions to add the customer to your Customer Relationship Management provider.

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.