File Distribution Service
The Pitram File Distribution Service (PFDS) allows files from various sources to be collated and distributed to multiple clients (typically Mobile devices) via a server service.
The most common usage of the PFDS will be to distribute files from a desktop PC (for example, where Carlson files are edited) to Pitram mobile units (for example, running Carlson software). However, the PFDS must also be able to handle the case where source files have been uploaded to a mobile device by other means, for example, from a USB storage device. To cover this, the solution is modelled around a two-way "drop box" style of synchronisation.
Software Components
The software is made up of two components:
- A central server service
- A client connector startup application
Server Service
The Server Service runs on a central server that all mobile clients can connect to. It uses a single TCP connection (with no authentication enabled). The Server Service looks after all central file staging and synchronisation logic. Typically there will only be one installation of the Server Service.
Client Connector
The Client Connector can be installed on any client machine that wants access to a Pitram File Distribution "drop box" (i.e. a synchronised folder). Typically, there will be many installations of the Client Connector on mobile devices, and on any office computer that wants to distribute files to other machines. The Client Connector uses a single TCP connection to connect to the PFDS server. It does not connect to any other Pitram services.
Key Concepts / Terminology
| Remote Box | Think of the Remote Box as a Mailing box, a central "location" where files sync between different machines. A Remote Box is identified via its RemoteBoxId (see below). |
| RemoteBoxId | An "address" to identify a "folder location" (Remote Box) that will be synchronised between multiple machines. This can be any string. |
| Watched Folder | A root folder of the file distribution service. |
| PFDS | The Pitram File Distribution Service (this system). |
File Versioning
File versioning will record the date and time that a file in the Watched folder is either:
- dropped into the folder,
- edited,
- renamed, or
- deleted
Important - These operations are only picked up if the client connector is running. If a file is deleted, for example, when the Client Connector is not running, once the Client Connector is restarted, it will just think the file is missing and re download it, rather than send a Delete command to other nodes.
Constraints and Limitations
The PFDS is designed for the transfer of small-to-medium-size data files, it is not meant to replicate the features of a full blown “drop box” system. Unlike such systems, the PFDS does not require an Internet connection in order to work.
| Max file size | 100 MB (104857600 bytes where 1MB is 1048576 bytes) |
| Conflict Resolution | The file with the latest date-time stamp wins. |
| Computer clock synchronisation | For the two-way sync to work correctly, the system time must be synchronised. |
| Caution: | Caution should be exercised if editing files in watched folders with software that may use many intermediate and temporary files, e.g. MS Office products, in particular Excel. Most of the time these files "should" end up correct on the remote system, however if the editing session is interrupted, we could still end up with inconsistent states. |
| Folder Support | Empty folders are not supported. |
Service Login Accounts and Permissions
Preferably, the service will log onto the “Local System”. The Server service must be permitted to:
- Read/write to the File distribution database
- Read/write to the file system
- Communicate via WCF/TCP
- Write to the Windows Event Log
The Client service must be able to:
- Read/write to the file system
- Communicate via WCF/TCP
- Open a HTTP port (see Runtime Information below)
- Write to the Windows Event Log
For more information on Windows service logins, refer to the MSDN documentation.
Runtime Information
The connector client connector runs a self hosted REST endpoint for runtime queries that is used by Pitram Mobile, and for any external applications (including its own diagnostic page). This is configured by the fields RuntimeInfoEndpointServer and RuntimeInfoEndpointServerPort in the PFDCConfiguration.xml file. There should never be any need for these default values to change. The installation will add the required permissions to allow the service to use this http port (831). If this port is ever changed, then the http reservation will need to be manually updated using the netsh command.
If the runtime information does not appear to be working, the following command can be run from an administration cmd prompt:
netsh http show urlacl > x.txt
This should result in something like:
Reserved URL : http://+:831/
User: PERTH\timmy
Listen: Yes
Delegate: No
SDDL: D:(A;;GX;;;S-1-5-21-1547161642-764733703-854245398-2674)
If the above reservation information is not present, it can be manually added from an admin cmd prompt with the following:
netsh http add urlacl url=http://+:831/ user="NT AUTHORITY\Authenticated Users"
To manually delete:
netsh http delete urlacl url=http://+:831/
The trailing ‘/’ is important.
Administration Page
The PFD client connector provides a simple admin page that can be used to help with diagnostics, in particular on a Mobile unit where it is hard to get access to the machine. This is a feature to help with internal support and diagnostics, in particular to allow tracing information, of which there is an extensive amount, to be easily viewed.
A web browser can be used to navigate to the machine name. To open the Admin page, the runtime information port must be supplied:
e.g. http://mm000851:831
This page allows easy remote access to some common diagnostic related operations, as described below.
Debug View Agents
The PFDS installation will install an instance of Debugview (the primary tool used to view diagnostic tracing information). By running Debugview in "agent" mode on a remote machine, it is possible to connect to another instance of Debugview on a local machine, in order to capture the remote tracing.
The two options in the admin page allow this remote agent to be opened and closed.
Trace Level
The remote trace level, which is dynamically picked up by the connector, can be adjusted here.
Message Log
Allows the last 50 or so messages logged by the connector to be viewed. This is a quick view of messages, rather than having to use the Debugview option (i.e. it is possible to use it on a device other than a PC which does not have Debug view installed, for example, a tablet or mobile phone, or on a PC that does not have Debugview installed).
Remote Files
This will provide a list of the files (and timestamps) being watched by the connector.