1. Open the export or import connector

2. Scroll down to the ‘Trust relations’ include. If the include is missing you need to add the include “FtpConnectorObjectTrustRelationList”)

3. click on ‘Assign new RSA key’

4. Click ’New’ to create a new Trust relation

5. Fill in the fields:

   1. Name = give a name

   2. Description = give a description

   3. Type = RSA key pair

   4. Inheritance = merge

6. Click ‘Generate key’

7. Copy the RSA private key and the password (all the way at the bottom) from the field 'Public certificate'.

   1. Note: do this immaterially. If you refresh the trust relation page (or leave it and come back) navigate back to this page, the public key will be displayed instead.

8. If you forgot to copy the private key, you can click ‘Reveal secret key' > fill in the password of the user you’re logged in with (not the client password!)

9. Now click ‘Ok’ to navigate back the the previous screen

10. Select the trust relation you just created > click confirm on the top right of the page
    

    Image Removed

11. After confirming, the details tab of the connector is opened. When you now scroll down to the ‘Trust relation’ include you will see that the trust relation is linked.

12. Don't forget to configure the import/export connector as usual. So add the: server, port number, directory, etc .

13. After setting up the connection on the client side, you can start testing.

Troubleshooting checklist

•  Were you able to connect to the SFTP server in FileZilla?
•  Is there a firewall? If so, is our IP address whitelisted?
•  Is there a self-signed certificate, or is this by a trusted party?
•  In regards to incoming import: Did the received file change over time?

Summary

Exercise

•  N/A

Search

What is SFTP / when to use SFTP

SFTP stands for SSH File Transfer Protocol. This is a method of transferring files between two entities. It is literally nothing else than having one entity (system or user) transferring a file to a server, which in turn can be collected by another entity (system or user). Or to make it even more simple: image if you would put a file on a folder on your desktop, which would then be collected by another user. It is as simple as that.

SFTP is most commonly used in the following scenario’s:

• Data should be shared in a common file format. As the file is placed on a server, most commonly files like CSV or XML are used. But PDF, Word or image files are also commonly used. As these are common files, users can more easily interact with them and understand what is happening.

• Debugging needs to be easy. Seeing as there are two actions (entity > server, server > entity), it is quite easy to debug where the error is happening. If an expected file is not on the server, you know the delivering party made an error. If the file is on the server, but not (correctly) collected by the receiving entity, you know that something is going wrong with collection.

• Large datasets need to be shared. A webservice is most commonly used for short transactions. Large datasets are not suited to directly be transferred between systems, as timeouts might occur. These limitations are less for SFTP. So when a large transferal of data is necessary, SFTP is the better option.

Considerations

 Please take note of the following considerations in regards to SFTP:

• Next to SFTP, Workplace also has support for FTPs. Please do not use this unless there is no other option. Support for FTPs is becoming worse in the industry, so support will also take a decline. If FTPs is used, the other steps are similar, although you might need to specify the kind of FTPs in FileZilla (please refer to documentation online to set this up).

• Workplace does not accept self-signed certificates. This is for our own and the client’s security.

• Workplace supports certificate authentication. This possibility is still in early development and should only be conducted under the guidance of a Spacewell consultant. For that reason, it falls outside of the scope of this page (for now).

• As is with any server, there might be firewalls in place (this only applies when the server is not hosted by Spacewell). This might mean that the IP address of your office as well as that of Workplace need to be whitelisted.

  • You can find the IP address of your office when searching “what is my IP” on Google

  • Contact you Spacewell consultant to request the SOURCE NAT ip

• Import can only be run once every 15 minutes. If you set a higher frequency, this will be ignored.

Testing SFTP connection

Before setting up a connection from Workplace to an SFTP server, it is important to always test the SFTP connection. The easiest way to do this is by using FileZilla. FileZilla is an open source SFTP client software and is the industry standard to connect to SFTP server. You can download FileZilla from their website. If you want to know how to use FileZilla, please refer to their YouTube channel of any online resource on how to do this. This information is not shared here, as this information might be outdated in the future.

When you have installed FileZilla, test the provided details from the previous section by setting up a connection. If an error occurs, you first need to make sure that that is resolved. Only when you have successfully created a connection, setup can take place inside Workplace.  

Setting up an automated SFTP import

Scope

In the below examples, we’ll be using the default import connectors from Workplace Management. Automating custom imports (and exports) is also possible. If this is required, custom import/ export mappings need to be created for which in depth knowledge of the Workplace object model is needed. Please contact your Spacewell contact to discuss the possibilities.

Steps

1. In the navigationMenu click on “Configuration” > click on “Import” (or use the ‘Default import’ button on your startBoard).

2. Open the imports for which you would like to setup an automated import.

   Image Removed

3. If you have not been provided with a template file, please use “Generate import template” to get a template for the data import. If you already have the import file you can skip this step.

4. Navigate to the ‘Details’ tab.

5. There are obligatory and optional field. Below the list you can find both fields. Please follow those for the setup.

6. The SFTP connection should be active after filling in all obligatory fields.

   • It is common practice to set 'Active = yes' after filling all the other obligatory fields.

7. The connection is now active and will run at the first scheduled date.

Obligatory settings

Field

Value

Remark

Name

Choose a recognizable name

Not obligatory per se, but highly recommended to fill in.

Type

Default: SFTP

Choose FTPs if that applies, please see “Considerations”

Server

Server address

This should have been received from the client

Port

Port address (only digits)

This should have been received from the client

Username

Username which has been granted access to the SFTP

This should have been received from the client

Password

Password for provided username

This should have been received from the client

Filename

Name of the file to be collected

Make sure you discuss this with the client. Preferably this is always the same to prevent problems

Delete

Default: yes

Change this to “no” if you do not want the file to be deleted once Workplace has imported the file. Preferable for debugging

Active

Default: no

Used to enable/disable the import. Set this to ‘yes’ to activate the connection.

Start

Date time value

Start date and time for when the import should be started

Cycle

Set the interval with which data should be collected. The lowest minimum is 15 minutes, everything above that is a valid value

Contact

Contact in Workplace

Set the contact that executes the import/ export. This contact should have the proper access right. Usually a system admin is selected here.

Optional settings

Field

Value

Remark

Directory

Text which indicates the location of where the file is located on the SFTP server

Can be any directory on the SFTP server, divided by / (i.e. invoices/imported)

Zip password

Password for the zip

If the client is using a zip file using a password, the password can be added here

Character set

Default: empty

If errors occur in regards to text characters, this could be due to the encoding of the file. Set to the encoding of the file (you can check this through notepad)

Errors

Specify Workplace user group

When errors occur, the group that is filled in here receives an e-mail with the errors

Notification

Specify Workplace user group

When the import is done, the notification group gets notified through e-mail

Message

Text

A message can be added here for the notification

Scheduling

Day in the month

See remark

If you want a specific day in the month to import the file

Day

See remark

If you want to specify a relative day in the month to import the file

Next connector

Select the next connector

In some cases, you want to run multiple imports after each other, you can chain imports. You can select the next connector here. Be aware that if the first connector fails, the next one will not be started

Template definition

Template definition on how to handle data

This only applies if the imported file adheres to a specific template which diverts from CSV or one level XML. Please contact Spacewell if more is necessary

Time offset

Default: 120, proposed: 0

With this value, a check is done to see if the previous file that was imported is different than the newest file. This is in seconds. With 0, the check is skipped.

Be aware: this value is also important for file locking. Please refer to help text of the field for more information

Log

Default: yes

Makes sure errors are logged

Correct

Default: no

This allows the import to overwrite some values. Most of the cases, this is not necessary. Only change this in discussion with Spacewell contact

Save documents

Default: yes

With this setting, imported files are saved inside Workplace Management. This is desirable for debugging. If there is sensitive data in the imported files, put this value to “no”. Documents will be maintained for a certain amount of months, which can be set in the client settings

Save warnings

Default: yes

Saves warnings as files. Used for debugging. Set to “no” if debugging is not necessary.

Access right checking

Default: empty

In some cases, performance might be an issue. This value can be set to “simplified” to prevent intensive access right checking

Setting up SFTP export

Scope

No default exports are available in Workplace Management. Creating an export connector is therefor by definition custom. The complexity of setting up an automated export mostly depends on the format of the file that is exported. In this article we describe how you can setup the connection, but we will not go into details regarding how to format the data (e.g. creating reports and XML templates).

Transport types

The files are always send via email or placed on an FTP server.

Supported file types

The following file are supported:

• HTML (e.g. data in email body)

• PDF

• CSV

• CVS dump

• XML

• XML dump

• XLS

How to determine what data is exported

A report is always used to determine what data is exported. This report is linked in the ‘report’ field of the export connector.

Steps

1. In the navigationMenu click on “Configuration” > click on “Export”

2. Click ‘New’ to create an export connector

3. Fill in the obligatory field (see table below)

4. Click ‘Run’ to test you connection. The report will be emails or exported to the FTP server

Obligatory settings

Field

Value

Remark

Name

Choose a recognizable name

Not obligatory per se, but highly recommended to fill in.

Report

Link a report here

Use defaults/ initialization in the report filtering to configure the export results. For example: set a default category or a request filter on ‘create time’ with the initialization ‘now minus 7 days’ (export the REQs of last week).

Execute as

Set the contact that executes the export. This contact should have the proper access right.

Export documents

Default = formatted document only

Use the help text of the field to view what the other options do.

Active

Default: no

Used to enable/disable the import. Set this to ‘yes’ to activate the connection.

Start

Date time value

Start date and time for when the import should be started

Cycle

Set the interval with which data should be collected. The lowest minimum is 15 minutes, everything above that is a valid value

Format

Fill in the required format

Choose the file type in which the report should be exported.

• CSV: when not alle data is exported because the dataset is to large, the type ‘CSV dump’ can be used. Using this option, more data can be exported, but you lose lose logic like formula’s and formatting.

• XML: for this type the 'XML dump' variety exists, also with restrictions regarding lose of logic.

Type

Default: SFTP

• Choose FTP type that applies.

• Select ‘Email’ to send the report results attached in an email. The email will be send to the ‘Execute as’ contact, unless you fill in the field “Send to (if different)“.

Server

Server address

This should have been received from the client

Port

Port address (only digits)

This should have been received from the client

Username

Username which has been granted access to the SFTP

This should have been received from the client

Password

Password for provided username

This should have been received from the client

SSH Key Pair authentication (for WPM)

Workplace Management support authentication by means of SSH Key Pair authentication.

• RSA keys are used

• OPENSSH keys are currently (d.d. May 2023) not accepted and cannot be automatically converted. If you have an OPENSSH keys please first convert these to RSA.

If this is the first import or export connector you are enabling SSH Key Pair authentication for, first execute these steps:

1. Open you own user by clicking on your name in the top right of the screen > profile

2. Click the button ‘Assign group’

3. Search for and add the groep ‘License editor’ to your user. This group is needed to configure the authentication

   1. Note: if you are not able to add this group please contact your Spacewell contact.

To configure SSH Key Pair authentication for a import/ export connector: