FMS-SFTP Setup and Connection Guide
- Robert Cox
- Tina Tan
About
MazeMap hosts a service that allows customers to push data from their Facility Management System (FMS) for updating the maps directly. This service offers two interfaces for the customer to choose from; either they upload data using SFTP or via REST API.
This document provides the specifications of the types of data that needs to be provided to MazeMap for the automatic update of POI data and Drawings via our SFTP - FMS Integration.
SSH requires a username and a generated key pair, one key is public and the other private.
For FMS updates via REST API documentation for this can be found here:
SFTP Server Details
Host: | |
Port: | 8022 |
Generating Public SSH key
As mentioned above this push service uses SSH to make sure the connection is safe.
SSH requires a username and a generated key pair, one key is public and the other private, the following section covers the creation of these keys.
a) Create Username
Create a username, please remember that this will be unique for your user. The username (black arrow below) can be anything you like, but spaces, symbols and special characters should be avoided. Also keep in mind that this username should be unique. In the following example, the username is fmsintegration.
b) Create SSH Keys
The public part of the SSH key needs to be entered to connect to the MazeMap server (red arrow above). This key has to be created on the local computer.
1) Creating SSH Keys using Windows Command Line:
Step 1: Open the command prompt on your Windows machine.
Step 2: Type the following command to generate a new Ed25519 SSH key pair with a username (fmsintegration):
ssh-keygen -t ed25519 -C fmsintegration
Step 3: It will prompt you to enter a file path to save the key pair. Press Enter to accept the default path (C:\Users\YourUsername\.ssh\id_ed25519). You can also specify a different path if desired.
Step 4: Next, it will ask you to enter a passphrase. You can choose to enter a passphrase or leave it blank for an unprotected key. Press Enter to continue.
Step 5: The command will generate both the private key (id_ed25519) and the public key (id_ed25519.pub). These files will be saved in the specified directory.
Step 6: To retrieve the public key for sharing, open the public key file (id_ed25519.pub) using a text editor.
Step 7: Copy the entire content of the public key file.
Step 8: Create a support request with MazeMap Support support@mazemap.com including the copied public key in the request.
2) Creating SSH Keys using Linux:
Step 1: Open a terminal on your Linux machine.
Step 2: Type the following command to generate a new Ed25519 SSH key pair with a username (fmsintegration):
ssh-keygen -t ed25519 -C fmsintegration
Step 3: It will prompt you to enter a file path to save the key pair. Press Enter to accept the default path (/home/yourusername/.ssh/id_ed25519). You can specify a different path if desired.
Step 4: Next, you'll be asked to enter a passphrase. You can enter a passphrase or leave it blank for an unprotected key. Press Enter to continue.
Step 5: The command will generate both the private key (id_ed25519) and the public key (id_ed25519.pub). These files will be saved in the specified directory.
Step 6: To retrieve the public key for sharing, open the public key file (id_ed25519.pub) using a text editor.
Step 7: Copy the entire content of the public key file.
Step 8: Create a support request with MazeMap Support support@mazemap.com including the the copied public key in the request.
3) Creating SSH Keys using PuTTY (Windows):
Download and install PuTTY from the official website (Download PuTTY - a free SSH and telnet client for Windows ).
Open PuTTYgen, which is part of the PuTTY installation package.
Select the desired key type as "Ed25519".
Enter "fmsintegration" in the "Key comment" field to specify the username.
Click on the "Generate" button to create the key pair.
Move your mouse cursor around the blank area of the PuTTYgen window to generate random data for key generation.
Once the key pair is generated, you can set a passphrase for the private key or leave it blank.
To retrieve the public key for sharing, select the entire content of the "Public key for pasting into OpenSSH authorized_keys file" section.
Copy the entire content of the public key file.
Create a support request with MazeMap Support support@mazemap.com including the copied public key in the request.
Create a support request with MazeMap Support support@mazemap.com including the copied public key in the request.
Connecting to the MazeMap SFTP server using SFTP Client
Here's the technical user documentation for connecting to an SFTP server using four different options: FileZilla, WinSCP, Linux command line and automated script.
Please note: Connection to the SFTP server will only work once you have provided the public key generated in the above steps to MazeMap.
1) Connecting to the SFTP Server using FileZilla:
Step 1: Download and install FileZilla from the official website (FileZilla - The free FTP solution ) if you haven't already.
Step 2: Launch FileZilla.
Step 3: Click on "File" in the top menu, then select "Site Manager" from the dropdown menu.
Step 4: In the Site Manager window, click on the "New Site" button and give your site a name.
Step 5: In the "Host" field, enter the hostname or IP the MazeMap SFTP server -
Step 6: In the "Port" field, enter the port number for SFTP - 8022.
Step 7: Choose "SFTP - SSH File Transfer Protocol" as the protocol.
Step 8: In the "Logon Type" dropdown, select "Key file".
Step 9: Click on the "Browse" button next to the "Key file" field and locate the private key file you generated previously.
Step 10: Once the private key is selected, the corresponding public key will be automatically used.
Step 11: Click on "Connect" to establish a connection to the SFTP server. FileZilla will use the provided private key for authentication.
Step 12: You should now be connected to the SFTP server and can navigate, upload, and download files as needed.
2) Connecting to an SFTP Server using WinSCP (Windows):
Step 1: Download and install WinSCP from the official website (WinSCP ) if you haven't already.
Step 2: Launch WinSCP.
Step 3: In the login window, enter the hostname sftp-updates.mazemap.com of the MazeMap SFTP server in the "Host name" field.
Step 4: Enter your username in the "User name" field.
Step 5: In the "File protocol" dropdown, select "SFTP".
Step 6: In the "Private key file" field, click on the three-dot button to browse and select your private key file.
Step 7: The corresponding public key will be automatically used.
Step 8: Click on the "Login" button to establish a connection to the SFTP server. WinSCP will use the provided private key for authentication.
Step 9: You should now be connected to the SFTP server and can navigate, upload, and download files as needed using the WinSCP interface.
3) Connecting to an SFTP Server using Linux Command Line:
Step 1: Open a terminal on your Linux machine.
Step 2: Use the ssh command with the private key file to establish an SFTP connection. Replace /path/to/private_key with the actual path to your private key file created above.
sftp -i /path/to/private_key -P 8022 fmsintegration@sftp-updates.mazemap.comStep 3: Press Enter and the connection will be established using the provided private key.
Step 4: Once connected, you can use commands like ls, cd, put, and get to navigate, upload, and download files on the SFTP server.
Step 5: To exit the SFTP session, type exit and press Enter.
4) Automating SFTP Connection and File Transfer:
By following these steps, you can automate the process of updating drawings and point of interest (POI) data for MazeMap on a nightly basis, ensuring efficient and regular updates without manual intervention.
Step 1: Generate SSH keys as described in the previous documentation.
Step 2: Develop a script or application that performs the following tasks:
Establish an SFTP connection to the MazeMap server using the generated SSH keys.
Navigate to the appropriate directory where the drawings and POI data are stored.
Identify and gather the updated drawings and POI data from the local system or a designated data source.
Use SFTP commands or a library/API to transfer the updated files and folders to the respective directories on the MazeMap server.
Implement error handling and logging mechanisms to capture any potential errors during the file transfer process.
Step 3: Schedule the script or application to run automatically on a nightly basis, using a system scheduler or task scheduling tool. Set the appropriate time and frequency to ensure the updates occur as desired.
By automating this process, you can ensure that MazeMap's drawings and POI data are regularly updated without requiring manual intervention. This helps keep the MazeMap platform up-to-date with the latest information, providing users with accurate and relevant maps.
Remember to test the automation thoroughly and monitor the updates to ensure they are executed successfully and the MazeMap platform reflects the latest drawings and POI data.
Please note that the automatic implementation details may vary based on your specific environment, programming language, and scheduling tool. Adapt the steps to fit your requirements and consult the MazeMap documentation or support for any specific integration details.
Uploading/Syncing Files
File and Folder Specifications
Building and Point of Interest files must follow a predefined format:
a) building manifest that lists campuses, buildings, floors, and connects drawings to floors
b) points of interest (POI list) with room data.
The files must be based on the Comma Separated Value format CSV and need to contain specific information in rows and be assigned a specific name to be recognised and automatically imported. There are two main CSV files that are needed to be uploaded ; Building Manifest and Point of Interest.
Folder Hierarchy
The files uploaded to the SFTP server must adhere to the following setup:
Both
Building_Manifest.csv and POIList.csv must be present, have exactly those names and placed in the root of the SFTP.
Any DWG files must be placed in a folder named
drawings and have unique names.
File Formats
The building manifest and points of interest lists are both comma separated values files (the delimiter must be comma; use double quotes to surround a column value if it contains commas). The files should be encoded with Unicode (UTF-8). Examples of both file formats can be found in the appendix.