Importing documents through SFTP upload

In the Pay Suite application, you can store large quantities of documents, both historical and current. These documents can be imported into the application by the admin through SFTP upload. This solution allows for a better control over the documentation that is shared with the workers in the organization.

This is a tip message.

You can also use the API upload to import your documents. For more information about this method, refer to Importing documents via API.

Prerequisites

Before you can start the upload of documents within the platform, there are two prerequisites that you must fulfill.

Firstly, you must first enable the Documents feature in the platform. This step is crucial; without it your reviewers will not be able to see the documents in their team planner and your workers won't receive their documents. To enable the feature, navigate to the Workbench > Platform Setup > Feature Enablement > Inbox and switch the toggle to enabled (blue).

This is a tip message.

Access to Workbench depends on your role within the platform.

Activating the Documents feature will:

• Enable the import of documents.

• Give access to the creation of communication rounds in Workbench.

• Give access to team documents in Planner.

Secondly, you must create at least one communication round to which the documents will be linked. This round can be in the past and used to mass-import historical documents. This step is mandatory because a reference to the round is mandatory in the HTTP request of the API call.

This is a tip message.

For more details about the creation of the communication round, refer to Creating a communication round.

Once the communication round is created, in the Communication round details section check if the status is marked as Open or In Progress, and write down the Code of the communication round. You will need unique code in the next steps of the import. These two pieces of information are highlighted in the following figure:

Communication round details

Uploading the files in the SFTP folder

A set of credentials is required to upload documents trough SFTP. To obtain them, create a support ticket where you must specify:

• The name of the tenant (which is the same as the company code used to login trough the web app)

• Environment/stack in which the tenant is located (e.g., demo, presales, etc).

Once you will obtain the required credentials such as hostname, username and an SSH password or a pair of SSH keys,from beqom, you can use them to register an SFTP site connection.

Once the connection is established, you may create the input and inbox folders or access them if they were not previously created.If you have performed the data ingestion into the platform via csv upload, the input folder may already exist. In this case, create an inbox folder.

Uploading multiple PDF documents trough SFTP upload

You may also upload multiple documents at once using a metadata file. The requirements for the metadata file are:

• metadata file must be called DocMapping.csv,

• it must contain one PDF file per row, to allow the identification of recipient,

• the columns in the .csv file must be:

  • FileName: the name of the file uploaded in the same SFTP folder,

  • WorkerExternalId: ID used to identify an existing worker uniquely,

  • CommunicationRoundCodeto: code to identify the communication round (which must be in "Open" or "In progress" state ),

  • IsSummary: set to true when a document is a communication summary for managers,

  • GenerationTimethe: the date the PDF got generated.

An example of a csv. file to import two documents for two different workers in the same communication round is illustrated in the following figure:

Import of different documents in the same communication round

Once the scheduler checks the SFTP folder according to the time and frequency that has been confederated during the first steps, finds the correctly named DocMapping.csv file the import will take place but only for the documents that were listed in the csv. file.

Documents processed successfully will be removed together with the CSV file. Documents that were not listed in the file will be ignored. In case of error, the CSV file will also be removed.

This is an attention message.

Note that it is a good practice to transfer or upload to the SFTP Inbox folder all the PDF files first and leave the csv. file for the end. This way in case the scheduler call is activated in between the process, it will find the PDF files first. Otherwise finding a csv. file but not all the PDF files that are connected to it may lead to a false Not found errors message.

Once the import finishes, the process will generate an output log file in the folder output/inbox. The file will contain one row per document and the following columns:

• FileName as in the import file,

• WorkerExternalId as in the import file,

• IsSummary as in the import file,

• GenerationTime as in the import file,

• CommunicationRoundCode as in the import file,

• Status Success of Failure,

• Details a message explaining the error, in case of failure,

• DocumentId the id of the document in the inbox,

• Overridden set to true when a document for the same worker with the same name and in the same round existed and got overridden,

• ImportTime the time stamp of the import.