Application Updates

The following topics provide information on the update process for Pitram Mobile for Android.

Background

On Windows®, a Pitram Mobile unit is updated by running the desktop installer, or by the built-in AppLife updater pulling a new package from the server. Neither is available on Android: Field tablets have no desktop installer, and AppLife updates a Windows® install in place. Pitram Mobile on Android therefore updates itself - i.e. it checks the server for a newer build, downloads it, and installs it through Android's own package installer.

The server side is the same one the Windows units already use: the unit asks the General Services Server (GSS) whether a newer version is available, and the update is triggered per unit with Force Update from the Mobile Health Panel in Data Acquisition. Only the final install step differs — Android hands the downloaded package to the system installer instead of applying an in-place AppLife patch.

Pitram Postman (the data carrier) and Pitram AdHoc also run on Android and also update themselves, but along a different path: they have no connection to the GSS and no Force Update button. Instead each polls a web address on a timer, exactly as the Windows Postman polls its network share.

How an update reaches a unit

  1. A new build produces the signed Android package (an .apk) and a small version file that describes it.

  2. Someone places both files on the Pitram Server, in

    ...\ProgramData\Micromine\PITRAM\Installers\MobileAndroid

    or, when a unit is pointed at one, in a named subfolder of it (see The update source folder below) exactly the way the Windows Mobile update package is placed in Installers\Mobile. This is a manual copy from the release share; the server does not need to be reinstalled.

  3. The unit, while running, periodically asks the server whether a newer version is available. When Force Update is issued for that unit and a newer package is present, the unit downloads it (resuming if the connection drops).

  4. Android runs the Google Play Protect scan and shows the standard install dialog. The operator taps Install; the application updates and restarts on the new version. This needs the Install unknown apps permission (see step 7 of Installing Mobile for Android); the scan, including what to do if it blocks the install, is described there too.

Because the operator confirms each install on the system dialog, an update is never silent — someone taps Install on the device. An update only ever moves forward: Android refuses to install an older or equal version over a newer one.

The Update package

The package is two files that must be deployed together:

  • com.micromine.pitram.mobile-Signed.apk - the signed application.

  • com.micromine.pitram.mobile-Signed.version - a small text file holding the version, the APK's size and its checksum.

The server reads the offered version from the .version file and, before offering the update, checks that the APK on disk matches the size and checksum recorded there. If the two files were not deployed together — a new version file left next to an old APK, or the other way round — the server logs an error and offers nothing, so a mismatched package can never be handed to the units. Always keep the pair together when copying.

The update source folder

By default every Android unit takes its update from the Installers\MobileAndroid folder above. A unit can instead be pointed at a named subfolder of it; for a staged rollout, or to give different fleets different builds - the same method used for Windows Mobile units.

This is set in Reference Data, in the Update Agent Profile linked to the unit's configuration, through the Update Source Path attribute:

  • Enter the name of the subfolder only: For example, Fleet1. The unit then takes its update from ...\Installers\MobileAndroid\Fleet1.

    Create that subfolder under Installers\MobileAndroid (not beside it) and place the .apk + .version pair inside it.

  • Leave it empty to take the update from the Installers\MobileAndroid root. This is the default, and matches the behaviour before any subfolder is configured.

  • It is a folder name, not a path. Do not enter a full path or a drive letter, such as C:\ProgramData\Micromine\PITRAM\Installers\MobileAndroid\Fleet1. A value that contains a drive letter (a :) is treated as misconfigured, is ignored without an error, and the unit silently falls back to the root - so the update looks like it does nothing from the configured folder.

The same folder is honoured both when the unit downloads directly from the server and, where peer-to-peer update sharing is enabled, when units share the package with each other.

Relationship to the Windows update

  Windows Mobile Android Mobile
Version check GSS GSS (same)
Trigger Force Update (Mobile Health Panel) Force Update (same)
Package AppLife .zip + Director.xml in Installers\Mobile .apk + .version in
Installers\MobileAndroid
Update source folder Installers\Mobile, or a named subfolder set per unit Installers\MobileAndroid, or a named subfolder set per unit (same)
Deploy to server Manual copy from the release share Manual copy from the release share (same)
Install step AppLife, in place Android system installer, operator confirms

 

Pitram Postman and AdHoc on Android

Pitram AdHoc updates itself exactly like Postman, from its own web folder (for example Updates_AdHoc) set in the ApplicationUpdateSettings token linked to its AdHocNetworkServiceProfile.

Note: Everything below for Postman applies to AdHoc, with com.micromine.pitram.adhoc-Signed in the file names.

How it differs from Mobile

The Postman carrier does not talk to the GSS and has no Force Update. It keeps itself up to date the way the Windows Postman does: on a timer it looks at a configured update location, and when a newer version is published there it fetches and installs it; nobody has to trigger anything. The only differences from Windows are the location and the install step:

  • Windows Postman reads its update from a network share. Android cannot read a Windows share, so the Android carrier reads it from a web address (HTTP or HTTPS); a folder on a web server such as IIS.

  • Windows applies the update in place through AppLife. Android hands the downloaded package to the system installer, and the operator confirms. This is the same install step and the same Install unknown apps permission as for Mobile above.

     

Configuration

The update location and the check interval are not edited on the device. They come from Reference Data, in the Application Update Settings profile linked to the carrier's unit configuration, and reach the tablet through PRIS:

Attribute Android carrier
NetworkUpdatesDirectory The web address of the folder holding the package, e.g. http://server/Updates_Postman/.
Must start with http:// or https://. A network share path (\\server\share) is accepted by Windows units but ignored on Android - self-update stays off and the log says so.
UpdateCheckIntervalInMinutes How often the carrier looks at the location.
LocalUpdatesDirectory Windows only; not used on Android (the carrier keeps its download in its own app folder).

Give the Android carriers their own profile (for example Postman Update Settings Android) with the web address, and keep the Windows profile pointing at the share.

Update Package

Two files with the same base name, produced by every release build:

  • com.micromine.pitram.postman-Signed.apk - the signed application.

  • com.micromine.pitram.postman-Signed.version - the version, the APK's size and its checksum.

The build puts both into the Android folder of the release share, next to the Mobile package. The carrier reads the .version file first and, only if it offers a newer version than the one installed, downloads the APK and checks its size and checksum against the version file before installing. Always copy the pair from the same build.

Hosting the package on a web server (IIS)

IIS serves only file types it knows. .apk and .version are not among them, so without the registration below IIS returns 404 Not Found for both files (even though a directory listing shows them) and the carrier logs a failed update check every interval.

  1. Create a folder in the site (for example Updates_Postman) and copy com.micromine.pitram.postman-Signed.apk and com.micromine.pitram.postman-Signed.version into it.

  2. Put the web.config shown below into the same folder. It registers the two file types and turns on the directory listing.

  3. Check from a browser or another machine that opening http://server/Updates_Postman/com.micromine.pitram.postman-Signed.version shows the three lines of the version file. A 404 page means the file types are still not registered.

    Copy
    <configuration>
      <system.webServer>
        <directoryBrowse enabled="true" />
        <staticContent>
          <mimeMap fileExtension=".apk" mimeType="application/vnd.android.package-archive" />
          <mimeMap fileExtension=".version" mimeType="text/plain" />
        </staticContent>
      </system.webServer>
    </configuration>

 

How the update happens

  1. Within one interval of starting (and then every interval) the carrier reads the .version file from the web address.

  2. If the version offered is newer than the installed one, it downloads the APK into its own folder and validates the size and checksum. A package that does not match its version file is discarded and never installed.

  3. Android shows the standard install dialog; the operator taps Install and the carrier restarts on the new version. If the install permission has not been granted yet, the carrier opens the settings page for it; once the operator grants it and returns to Postman, the install dialog is shown straight away. If the operator does not return to Postman within 10 minutes, the install is offered again on a later check.

  4. If the carrier is stopped or the tablet is rebooted after the download but before the install, the downloaded package is applied at the next start.

An update only ever moves forward. If the version on the web server is the same as, or older than, the installed one, the carrier does nothing and (at the normal Info logging level) logs nothing about it. To test the self-update, the hosted version must be newer than the version installed on the tablet.

Deployment steps

  1. Download the com.micromine.pitram.postman-Signed.apk and .version files (a build newer than the one on the tablets) from the Pitram server (Administrators only).

  2. Copy both files into the web folder, replacing the previous pair.

  3. Make sure the web folder has the web.config above and the .version link opens in a browser.

  4. Wait one check interval; the tablet shows the install dialog. No Force Update is needed.

Postman vs Mobile on Android

  Android Mobile Android Postman
Version check GSS Web address from Reference Data (ApplicationUpdateSettings via PRIS)
Trigger Force Update (Mobile Health Panel) Timer, every
UpdateCheckIntervalInMinutes
Package com.micromine.pitram.mobile-Signed.apk + .version in Installers\MobileAndroid on the server com.micromine.pitram.postman-Signed.apk + .version in a web folder (IIS)
Web server setup 0 .apk and .version MIME types must be registered
Install step Android system installer, operator confirms Android system installer, operator confirms (same)
Pending download Applied on the next Force Update or start Applied on the next start

 

Troubleshooting

  • On the unit: mdu_update.log. Spaces mean no connection to the server; dots mean the server reported no file (check the server log for the path that was requested).

  • Mobile configured to use a custom update folder but the unit still updates from the root, or Force Update seems to do nothing from that folder: the Update Source Path in the Update Agent Profile must be a folder name only (for example Fleet1), not a full path — a value containing a drive letter (a :) is ignored and the unit falls back to the root.

    Check mdu_update.log: the Use configuration / Save configuration line shows the source path in use, and an empty first value in the brackets means the unit is on the root. Also confirm the subfolder was created under Installers\MobileAndroid, not beside it.

  • On the server: gss_gsw.log - including the error logged when a .version file and its APK do not match.

  • Postman on Android: The carrier's log <date>-PostmanService.txt in the tablet's shared Micromine\PITRAM\Logs folder. At start, it states either Self-update on: source '<address>', check every N min or Self-update off with the reason (no address, or a share path instead of a web address).

  • Application update check failed ... 404, Not Found every interval: The web server does not serve the files. Register the .apk and .version types (see the web.config in the table above) or check that the files are really in the folder.

  • Self-update is on, nothing fails, nothing happens: The hosted version is not newer than the installed one. Compare the .version file on the web server with Pitram Postman Version: 17.0.0.x in the log header.

  • Pitram Postman Version: 1.0 in the log header means a development build was installed by hand, not a release build. Release builds carry the build number and are the only ones that include the update features.

  • Android shows Harmful app blocked when installing or updating: This is a Play Protect false positive. See If Android blocks the install as a "harmful app".

     

Information on using the Pitram Mobile Android app is contained in Using Mobile for Android.

Using Mobile for Android