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.

The Client Connector runs as a startup application. When the service is installed on a desktop or mobile computer, a Tray icon is visible on the task bar.

Status

The tray icon indicates the status of the connector. This status can also be seen by hovering the mouse over the icon to show a tool-tip.

Connected
Paused
Syncing files
Disconnected from server

If the icon is not visible in the taskbar the Client Connector is not running.

Running the Client Connector

The Client Connector starts automatically when Windows starts. In newer versions of Windows (version 8 and above) the connector can be enabled and disabled from the Task Manager. In older versions of Windows, the connector is started by running msconfig from the command prompt.

Clicking the tray icon in the task bar will give the following options:

  • Pause – stops syncing once any current sync operation is complete. Files added in the Root Sync Folder while paused will not be synced until the Pitram File Distribution Connector is resumed.
  • Resume – visible only when paused, resumes the Pitram File Distribution Connector.
  • About – shows the version number of the Pitram File Distribution Connector.
  • Exit – exits the Pitram File Distribution Connector.

The Client Connector will run on all machines that want to synchronise files. It communicates with the server via a single TCP connection (see configuration below) and requires the user running it to have:

  • Access to a port for the server communication (830 is the default)
  • Full Read/write access to root folder location(s) for the file synchronisation
  • Access to the Event Log for logging (permissions should be set by the installer)
  • Access to the configuration file PFDCConfiguration.xml (see below)
  • For Mobile setup, access to other configuration settings:

    • HKLM\SOFTWARE\Micromine Pty Ltd\Pitram\AppDataConfiguration registry setting, and

    MachineGlobalSettings.xml

    More details on these below.

Connector Configuration

The installation creates and configures the following file:

File name: PFDCConfiguration.xml

This configuration file is located in the <appdata>Micromine\PITRAM\Configuration\Machine folder

Configuration Fields

Field Name Example Value Description
FileDistributionServer MM-SRV123 Address (Id of IP) of the File Distribute server
FileDistributionServerPort 830 File Distribute server communications port. 830 is the default value, and should never really be a reason to change
RuntimeInfoEndpointServer + Runtime service host address to use (to open service)
RuntimeInfoEndpointServerPort 831 Runtime service port
TraceLevel Off No tracing.
  Verbose Provide detailed trace information and diagnostics.
  Information Provide trace information for system messages, warnings and errors.
  Warning Provide trace information for warnings and errors.
  Error Provide trace information for errors.
Culture en-AU Language culture
RemoteBoxConfigMode Desktop ‘Desktop’ mode for the service to run in.
  Mobile ‘Mobile’ mode for the service to run in.
RemoteBoxes (config section)   List of RemoteBoxes
RemoteBoxConfiguration (config section)   Collection of properties, that are interpreted depending on the RemoteBoxConfigMode
RootSyncFolder C:\data A root folder location for synchronised file. The service must have full Read/write access to this.
RemoteBoxId Carlson* An "address" for the remote box or boxes. How this is interpreted depends on the value of RemoteBoxConfigMode, and explained below under the sub-heading: RemoteBoxId
IsPrimaryBox true This identifies whether this instance of a remote box, is a primary target. A primary target means this is typically a target for file, as on a mobile device
UpdateLocationUrl http://server.com/pfd

ftp://server.com/pfd/updates/

\\network-server\pfdupdates\

 Gets or sets the network location of the updates for the application. Any UNC, HTTP, or FTP location can be specified. If left blank the Client Connector will not check for updates.
CheckForUpdateSeconds 600 Number of seconds to poll UpdateLocationUrl to check for new updates. See: AppLife Updates
UpdateDownloadPath C:\Updates\PFD Local file path to download updates to. Once downloaded updates will only only be applied when the Client Connector starts again.

Configuration Mode

The configuration file will look quite different depending on whether this service is running on a Mobile device (file target) or a Desktop office machine typically producing files to be pushed to a Mobile device (we call this Desktop mode). Depending on this configuration, the service will have two different behaviours and "RemoteBoxes" settings. However, once these RemoteBoxes are setup, the synchronisation behaviour is the same for either a Desktop or a Mobile client (except that “under the hood” a Mobile client will have one extra 'result' acknowledgement).

As discussed above, the two configuration modes are:

  • Desktop
  • Mobile

Desktop Configuration Mode

This mode is for a desktop machine that typically will want to push files to many mobile devices, therefore it will have many "Remote boxes". In other words, it will have a watch folder for each mobile device that is running the PFDS client connector. These remote boxes are discoverable, i.e. once a root watch folder is configured, the service in "desktop mode" will create a watch folder for each mobile device connected to the file distribution server. To do this, the client connector asks the server for all clients that have synced in the last 7 days. To do this, the server will query the RemoteBoxSyncRegister database table and return all entries that meet the following criteria:

  1. IsPrimaryBox is set to 1
  2. LastSyncTImeUtc is within the last 7 days

This value is not currently configurable (is hardwired to 7 days). If a client is offline for longer, as soon as it comes back online the box will be re-added to the list (the client constantly looks for an updated list, so it can also pick up any new clients coming online).

Below is an example of Desktop mode, which is discussed further:

The <RemoteBoxConfigMode> tag is set to Desktop.

Next notice the RemoteBoxes, there may be multiple <RemoteBoxConfiguration> sections. Each of these can point to a completely different root folder, for a different set of remote boxes (see more below). For Carlson, there is only one RemoteBoxConfiguration, however this example shows that it is possible to more than one.

Example Client Connector Configuration configured in Desktop mode

<?xml version="1.0"?>
<Configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <FileDistributionServer>MM00851</FileDistributionServer>
  <FileDistributionServerPort>830</FileDistributionServerPort>
  <RuntimeInfoEndpointServer>http://+</RuntimeInfoEndpointServer>
  <RuntimeInfoEndpointServerPort>831</RuntimeInfoEndpointServerPort>												
  <TraceLevel>Verbose</TraceLevel>
  <Culture>en-AU</Culture>  
  <RemoteBoxConfigMode>Desktop</RemoteBoxConfigMode>  
  <RemoteBoxes>  
    <RemoteBoxConfiguration>
      <RootSyncFolder>h:\00\pfd</RootSyncFolder>
      <RemoteBoxId>carlson*</RemoteBoxId>	
      <IsPrimaryBox>false</IsPrimaryBox>	  
    </RemoteBoxConfiguration> 
	
	 <RemoteBoxConfiguration>
      <RootSyncFolder>h:\00\pfd</RootSyncFolder>
      <RemoteBoxId>health*</RemoteBoxId>	
      <IsPrimaryBox>false</IsPrimaryBox>	  
    </RemoteBoxConfiguration> 		
  </RemoteBoxes>
</Configuration>

Lets examine a Desktop RemoteBoxConfiguration that we will use for Carlson in detail:

<RemoteBoxConfiguration>
   <RootSyncFolder>h:\00\pfd</RootSyncFolder>
   <RemoteBoxId>carlson*</RemoteBoxId>	
   <IsPrimaryBox>false</IsPrimaryBox>	  
 </RemoteBoxConfiguration>

RemoteBoxId

In Desktop mode, the client connector will auto create a separate watch folder for all other mobile devices using the system, i.e. for any device that has its IsPrimaryBox set to 1, AND which matches the Regular Expression set in the RemoteBoxId (see the Client Connector Configuration section). The Desktop client will then create a subfolder under the RootSyncFolder using each RemoteBoxId as the name of the subfolder.

So, if we have two mobile devices with RemoteIds, carlson1, carlson2, we will get the following folders:

Therefore, as is explained in the Mobile Configuration Mode section below, in order to arrive at an appropriate folder structure, a scheme such as carlson\<equipment code> can be used for the remote box ids. Since there is a path separator, the desktop client will create the nested sub folders as necessary.

For example:

If there are two drills, Drill01, Drill 02, and these have RemoteboxIds carlson\Drill01 and carlson\Drill02, the following folders will be created on the Desktop client:

This way of defining RemoteBox Ids gives complete flexibility when creating folders and nested folders on the Desktop client.

For example:

If the folders were named <equipment code>\carlson, then the RemoteBoxIds could be defined using *\carlson.

Mobile Configuration Mode

As well as using the PFD configuration file PFDCConfiguration.xml, a mobile device will also need to obtain information from two other places:

Data Folder As is the case for Pitram Mobile, the data folder for the PFDS client connector may not be in the Windows default location. Previously defined in a Pitram Mobile-specific AppDataConfiguration.xml file, this setting is now moved to a global location that can be accessed by both Pitram Mobile and the PFDS. Future installations will write this setting to the registry at: HKLM\SOFTWARE\Micromine\Pitram\AppDataConfiguration.
Mobile Device Equipment Code Previously, this setting was also defined in a Pitram Mobile-specific configuration file: MobileSettingsConfiguration.xml, but is now moved to a globally accessible file: MachineGlobalSettings.xml (which exists alongside other Pitram configuration files in the same machine data folder).

Below is an example of how a Mobile device PFDCConfiguration.xml file may be configured:

<RemoteBoxConfigMode>Mobile</RemoteBoxConfigMode>  
 
<RemoteBoxes>  
   <RemoteBoxConfiguration>
     <RootSyncFolder>C:\Data</RootSyncFolder>
       <RemoteBoxId>carlson\@#equipment@</RemoteBoxId>	
       <IsPrimaryBox>true</IsPrimaryBox>	  
    </RemoteBoxConfiguration> 
</RemoteBoxes>

Once again, there are multiple RemoteBoxConfiguration sections (another one for Health might be added, for example). Note the following differences to the example shown for the Desktop client:

  • <RemoteBoxConfigMode> is now set to Mobile
  • <RemoteBoxId> uses a "configuration variable" @#equipment@ (see below)
  • <IsPrimaryBox> is set to True

Configuration Variables

In the Desktop setup, the RemoteBoxId was used to get the equipment name. These equipment names (codes) are set on the Mobile devices using "configuration variables". They have the form:

@#<variable name>@

In other words, they are prefixed with a '@#', and suffixed with a '@'. These variables allow us to use "placeholders" in the RemoteBoxId.

Currently, only an Equipment variable: @#equipment@ is supported.

The PFDS client connector will read the above, and when it sees the @#equipment@ variable it will lookup the value from MachineGlobalSettings.xml.

For example, given the following:

<?xml version="1.0"?>
<MachineGlobalSettings xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <EquipmentCode>Drill01</EquipmentCode>
</MachineGlobalSettings>

The remote box Id for this device will become carlson\Drill01. This format will allow the Desktop service to use the RemoteBoxId as a path for its subfolders.

AppLife Updates

Overview

The Pitram File Distribution Client Connector can automatically update itself by downloading updates from a server.

Configuration

Update configuration is specified in the PFDCConfiguration.xml file and is initially set in Step 4. Automatic Updates of the Client Connector installer. See the Client Connector Configuration section.

Permissions

The user running the Client Connector (specifically FileDistributionConnectorTray.exe) requires local Administrator rights for automatic updates, otherwise updates will not be applied though the Client Connector will still function. If the user has local Administrator rights the user may get a UAC prompt when the Client Connector starts (which is normally when the user logs in) to which they must answer Yes for updates to work.

If UAC is turned off, as is typical on mobile devices, there will be no UAC prompt so the user does not need to respond (and if they have local Administrator rights updates will work).

In short: local Admin rights are required for updates.

Applying Updates

AppLife update packages are placed on the server (the .ZIP file and updated Director.xml file) accessible by the specified by UpdateLocationUrl on the clients. Clients will then automatically download updates and apply them when next started.

File Distribution Service