Difficulty: expert
Content
Learning Objectives
After reading this article, you’ll be able to:
What SFTP is and when to use it
Setup connection to SFTP server in WPM
Configure SSH key pair authentication
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.
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
In the navigationMenu click on “Configuration” > click on “Import” (or use the ‘Default import’ button on your startBoard).
Open the imports for which you would like to setup an automated import.
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.
Navigate to the ‘Details’ tab.
There are obligatory and optional field. Below the list you can find both fields. Please follow those for the setup.
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.
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 |
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:
Open you own user by clicking on your name in the top right of the screen > profile
Click the button ‘Assign group’
Search for and add the groep ‘License editor’ to your user. This group is needed to configure the authentication
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:
Open the export or import connector
Scroll down to the ‘Trust relations’ include. If the include is missing you need to add the include “FtpConnectorObjectTrustRelationList”)
click on ‘Assign new RSA key’
Click ’New’ to create a new Trust relation
Fill in the fields:
Name = give a name
Description = give a description
Type = RSA key pair
Inheritance = merge
Click ‘Generate key’
Copy the RSA private key and the password (all the way at the bottom) from the field 'Public certificate'.
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.
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!)
Now click ‘Ok’ to navigate back the the previous screen
Select the trust relation you just created > click confirm on the top right of the page
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.
Don't forget to configure the import/export connector as usual. So add the: server, port number, directory, etc .
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