SFTP Export Extension

From this article you will learn:

What is a Rossum SFTP Export extension
What are the common use case configurations
How to set up SFTP Export extension
What are the available configuration parameters

What is a Rossum SFTP Export extension

The SFTP export extension enables a one-way connection from Rossum to your SFTP server. That means the function can send data from your Rossum queue to a specific folder on your SFTP server. Also, the target SFTP folder will be the final destination for your extracted data and document files with a specified naming convention. You will find the SFTP credentials safely stored in the function.

Common use case configurations for SFTP Export Extension

Look at the following examples that show the complete configuration JSON for the function.

1. Exporting annotation files using document ID in the file name

The function exports the annotation XML files to the SFTP folder “/upload” in this basic example. Document ID from the Rossum queue stands for the files names.

{
  "path": "/upload",
  "exports": [
    {
      "type": "annotation_content",
      "format": "xml",
      "filename_template": "annotation-{doc_id}.xml"
    }
  ],
  "template_variables": [
    {
      "name": "doc_id",
      "type": "datapoint",
      "schema_id": "document_id"
    }
  ]
}

2. Exporting annotation files and document files using a complex naming convention

In this example the function exports both the document PDF and the annotation content XML. The files are named using the following:

document ID from Rossum queue
current date – year, month, day
number sequence – five digits, starting with 0, with an increment of 1. The sequence’s first three numbers are as follows: 00000, 00001, 00002, …

{
  "path": "/upload",
  "exports": [
    {
      "type": "annotation_content",
      "format": "xml",
      "filename_template": "{doc_id}-{year}-{month}-{day}-{seq_1}.xml"
    },
    {
      "type": "document",
      "filename_template": "{doc_id}-{year}-{month}-{day}-{seq_1}"
    }
  ],
  "template_variables": [
    {
      "name": "doc_id",
      "type": "datapoint",
      "schema_id": "document_id"
    },
    {
      "name": "year",
      "type": "datetime",
      "format": "%Y"
    },
    {
      "name": "month",
      "type": "datetime",
      "format": "%m"
    },
    {
      "name": "day",
      "type": "datetime",
      "format": "%d"
    },
    {
      "name": "seq_1",
      "type": "sequence",
      "start": 0,
      "increment": 1,
      "padding_size": 5,
      "padding_character": "0"
    }
  ]
}

How to set up the SFTP Export Extension

Setting it up takes a few simple steps.

Step 1: Prepare your SFTP server and the target folder

Set up and run your SFTP server where the function will place the data. The following items need to be ready to establish the connection:

“host” – this is the host name of the SFTP server (e.g., “rossum-export.server.customer.com “).
“port” – open port which will be used for connection to the SFTP server (the default port for SFTP connection is “22”, but you can use a different port number as well).
“username” – the name of the user account on the SFTP server the connection will use.
“password” – password related to the user account above.
“path” – prepare a target folder on the SFTP server where the extension places the output files. The path to the folder (e.g., “/upload”) is used in the extension configuration. You can find the path by executing the shell command “pwd” using an SFTP client or terminal from the target directory on the SFTP server.

Step 2: Select your queues and schemas

Now you need to identify the queue(s) with the annotation data and documents you want to export to the SFTP target folder. Once that’s done, identify the schema IDs of the fields used in the file naming pattern. You will need the queues and schema fields in the next steps in this guide.

Step 3: Activate the SFTP export extension in the Rossum store

To enable the SFTP export function, go to the Rossum application and:

Click on the Extensions tab at the top of the app.
Choose the Rossum store option to display all the available extensions.
Select the “SFTP Export Extension” tile.
Click “Try extension.”

Step 4: Specify to which queue(s) you want to add this extension.

Choose which queue(s) will export your data and documents to the SFTP server. Please note you can connect one or more queues. Once in the “Rossum Store extension settings,” scroll down to “Queues” and select the queue(s) that should have this one.

Step 5: Configure the data to export and output files naming convention

The configuration defines what data the function will export, the file format, and how the files will be named and numbered.

Step 6: Set up the secrets used for the SFTP server connection

The secrets you use to connect to your SFTP server are safely stored in the extension configuration screen in the Secrets section.

You can add your secrets to the edit box. When you click the Save Changes button on the configuration screen, your secrets are stored to the function but are not visible anymore. Instead, the “__change_me__” string is shown again until someone adds new secrets to be stored.

What are the available configuration parameters

Root	Param name	Mandatory	Description
	path	yes	The target directory on the remote SFTP server where the output files will be placed.
	exports	yes	This section defines which data files to export to the target folder on the SFTP server.
exports	type	yes	Specifies what type of data file the extension will export. You can set the value of the parameter to: “annotation_content” – data extracted from the document in specified “format“ “document” – the original document exported in PDF format
exports	format	yes, if export type is “annotation_content”	Defines output file format of exported type “annotation_content”. The supported formats are “csv”, “xml”, “xlsx” and “json”.
exports	filename_template	yes	Every export section can specify its own “filename_template“ defining naming convention for the output files (how they are named and numbered). It can contain fixed parts, which will be used in every filename, and dynamic parts, which will change in every filename generated using the template. The means of “template_variables” define the dynamic parts of the filename. The filename template for export type “annotation_content“ contains filename extension definition (e.g “.xml“). The filename template for export type “document“ does NOT contain filename extension definition. It is automatically taken from the original file imported to Rossum (e.g. “.pdf” or “.png“).
	template_variables	yes	Creates a unique filename for every output file exported to the target SFTP folder.
template_variables	name	yes	The name of the template variable. The “filename_template” definition refers on this name.
template_variables	type	yes	There are 3 types of the “template_variables”: “datapoint” – annotated data from the document. In the final filename, you can use all data items that have a value and are present in the queue schema. The data item you want to use is defined using the “schema_id” variable. “datetime“ – generates current date and time using standard python datetime format specified in the template_variable “format” variable. “sequence“ – generates number sequences of the fixed count of numbers.
template_variables	schema_id	yes, if template variable type is “datapoint“	An existing queue schema ID of an item to be used in template_variable of type “datapoint”.
template_variables	format	yes, if template variable type is “datetime“	Specifies the standard python datetime format specified in the template_variable.
template_variables	start	yes, if template variable type is “sequence“	The starting number of the sequence.
template_variables	increment	yes, if template variable type is “sequence“	Defined increment which is added to the previous value in the sequence.
template_variables	padding_character	yes, if template variable type is “sequence“	Character used as a leading character in the sequence (typically “0”).
template_variables	padding_size	yes, if template variable type is “sequence“	Overall count of number characters in the sequence. Note: Numbers are guaranteed to be unique, but there can be a hole (missing value) in the sequence. This hole comes from the nature of database sequences.