Run Once Packaging

Available for: Windows 1.4.1 and later clients.

Run Once Packaging enables Open Mobile administrators to create a downloadable package for end users that can deliver third-party software components or execute upgrades to device drivers and firmware. Subsequent processing or of the delivered files can be performed by means of an included script or executable that customers create.

About Run Once Packaging

Run Once Packaging is intended for dynamic delivery of device drivers or firmware updates. However, a properly constructed Run Once package could be used to deliver nearly any software component to users.

A Run Once package is created as part of an Open Mobile profile. When the Open Mobile client receives a test or published profile that specifies an unexecuted Run Once package, the client downloads the package, and then runs the associated script or executable. By default, a package runs in the user context, but can be set to run in the administrator context. A profile may include any number of packages, and each package can be up to 16 MB in size.

Package files themselves are not included in an Open Mobile profile. A profile merely includes the package definition file, ropimage.xml, which includes the specifications and download URLs for the actual package files.

A Run Once package does not ‘install’ or ’uninstall’ in the Windows context. The package is merely a vehicle for the one-time delivery of a payload of files, and can be controlled by a script, batch file, or executable written by an Open Mobile administrator. (Note, however, that depending on the individual files included in a package, these may be subsequently installed or uninstalled in the Windows context. For example, upon being executed, an MSI file would be installed in the Windows context, but this is the expected functionality for MSI files and not part of the ROP feature.)

A Run Once package delivers no other files than the ones specified in the package, nor does a package itself alter any Windows registry entries. (As above, an individual file in a package may alter registry entries as part of its normal functionality, but this is not part of the ROP feature.) Because of the power and flexibility of Run Once Packaging, an Open Mobile administrator should plan, design, and collect the included files for a Run Once package before assembling the package on the Open Mobile Portal. Any included scripts and the overall package functionality should be tested thoroughly before deploying to users.

About the Startup Command

Execution of the files in the Run Once package is accomplished by means of a startup command, which can be a script/executable or a set of operating system commands:

Script/Executable

A script or executable can be included in the package that will install the component files to the user’s system. An ROP script can be any valid script that runs on Windows, such as a VBScript or JavaScript file, batch file, or compiled executable. There is no required syntax for such scripts or executables, and they may be up to 16 megabytes in size (that is, up to the 16 MB package size limit). The designer of the package is responsible for creating (and testing) the ROP script or executable. If your package includes a script, use one of the following:

Script TypeStartup Command
VBScript or Javascriptwscript.exe <script name>
HTA scriptmshta.exe <script name>
Power Shell scriptps.exe <script name>
Always use the full path for the script name if its location is not in the Windows path.

OS Commands

Alternatively, a package can be launched by operating system commands. A package need not include a script or executable of any kind, and could be executed entirely through OS commands. For example, if a package comprised an MSI file, the package could be launched by having the user invoke the local msiexec.exe executable.

About Included Files

An included file may be any valid Windows file up to 16 MB in size.

The files to be included in a package (such as device driver files) should be collected before creating the package on the Open Mobile Portal.

Creating a Run Once Package

You create a Run Once package as part of a profile on the Open Mobile Portal. In order to create a Run Once package, you must have the Custom Install Package Manager role. To create a Run Once package on the Open Mobile Portal:

  1. On the Configure Profile page, next to Run Once Packaging, click Configure.
  2. In Package Name, enter the name of the package.
  3. In Startup Command, enter the syntax for your ROP script or executable to run, including all arguments. Startup Command may be up to 2000 characters in length.
  4. To run the startup command from the System account with the administrator privilege, select Run as administrator.
  5. Click Add New File, and then browse to the location of a component file.
  6. Repeat Step 5 for each subsequent included file.
  7. Click Save.
  8. Continue configuring the profile as needed. When configuration is complete, publish the profile to test.

After publication, Run Once packages can be viewed or deleted in the Open Mobile Portal, as part of the profile to which they belong.

Download Process

Upon publishing a profile to Test, the package definition file (ropimage.xml) is created as part of the profile. ropimage.xml lists all Run Once packages associated with the profile, their startup commands, and the URL of the download server from where the files are downloaded. A sample ropimage.xml file is shown under Example Files, below.

ropimage.xml contains the specifications for all packages in a profile, even the ones that have already been executed in previous updates. Execution of these packages is tracked separately. See Execution Tracking, below for more information.

When Open Mobile receives a profile with the unexecuted package (either as part of a new profile or updated one) the definition file is read by the Open Mobile Software Update Manager. Open Mobile begin any the file downloads when an Internet connection is detected. Like Software Update, a package downloads one file at a time. If the process is interrupted, Open Mobile will try to download the package at the beginning of the interrupted file.

Package files are downloaded to the <Open Mobile>\SoftwareUpdate\DownloadedFiles folder, where <Open Mobile> is the local Open Mobile installation folder.

On completion of the download of all files listed in ropimage.xml, they are copied to a temporary location for execution: <Open Mobile>\SoftwareUpdate\ROPTemp. After execution, the temporary files are deleted.

Interrupted Downloads

ROP downloads are by individual files. If a package download is interrupted, Open Mobile will re-download the entirety of any file that was interrupted when the Internet connection was previously disconnected.

Execution Tracking

Open Mobile will track the execution of the package. The success or failure of individual package components is not considered by Open Mobile—just the execution of the script or command line actions. Open Mobile does not log ROP execution. If execution needs to be logged, an administrator should make the logging part of the package script or executable.

An execution tracking flag is written to the persistent files in %PROGRAMDATA%\NGCROP, which record the execution of each package and prevent it from being executed again.

If a script takes longer than 1 hour (3600 seconds) to execute, Open Mobile will mark the script as successful and not run it again. However, if the script is configured to return an error code of (-4200), the package will be re-run.

The package will also be re-run if the script execution is interrupted by a system reboot or a stopping of Open Mobile client services (iMobility.exe and iPlatform.exe).

  • Multiple packages in a profile are executed in the order they are listed in ropimage.xml.
  • Silent background processing of Run Once packages is not currently supported.

Uninstalling Open Mobile from a system does not uninstall the ROP execution tracking flags. As a result, installing a new Open Mobile client on the same machine does not trigger any ROP action, since the old flags indicating package execution will be read by the new client.

Example Files

An example of the ropimage.xml file is shown here. The file is automatically produced as part of the Open Mobile profile when you configure the package on the Open Mobile Portal.

This package would launch the batch file copy.bat, which copy some XML files from the Open Mobile \bin folder to the \profile folder.

<?xml version="1.0" encoding="UTF-8" ?> 
- <RunOncePackageImage xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="RunOncePackageImage.V1.0.xsd">
  <ProfileID>6304</ProfileID>
- <- <RunOncePackage Description="ROP5" Locked="true" Name="ROP5" Timestamp="2011-06-06T03:52:38" UID="ad0bd817-b868-4aae-9f41-7f9cb92f4b41" Version="">
  <BinarySource URL="http://qa-om-download2.ipass.com/custominstall/ad0bd817-b868-4aae-9f41-7f9cb92f4b41/" /> 
- <Target>
  <File DigestValue="99540DF573D0B80CB4FD3D7D7F98C207D44673F9" FileName="copy.bat" Length="514" Timestamp="2011-03-23T02:47:24" /> 
  </Target>
  <RunCLI Context="User">cmd.exe /c copy.bat</RunCLI> 
  </RunOncePackage>
  </RunOncePackageImage>

Copy.bat is a short batch file shown here. This file would be created by an Open Mobile administrator and included as part of an Open Mobile profile.

copy "C:\Program Files\iPass\Open Mobile\bin\SampleMBLiteCdma.xml" "C:\ProgramData\NGC\Open Mobile\Profiles"
copy "C:\Program Files\iPass\Open Mobile\bin\SampleMBLiteGprs.xml" "C:\ProgramData\NGC\Open Mobile\Profiles"
copy "C:\Program Files\iPass\Open Mobile\bin\SampleMBLiteCdma.xml" "C:\Documents and Settings\All USers\Application Data\NGC\Open Mobile\Profiles"
copy "C:\Program Files\iPass\Open Mobile\bin\SampleMBLiteGprs.xml" "C:\Documents and Settings\All USers\Application Data\NGC\Open Mobile\Profiles"

Running a Package More than Once

As the name implies, a Run Once package is intended to be run a single time and deliver its payload. Once executed, it cannot be executed again.

To run a Run Once package more than a single time on the same computer, the administrator should create a new package with the same files as the previous one, and include it in an Open Mobile profile.

For example, a company wants to deliver monthly device driver updates to a group of Open Mobile users who share the same profile. Each delivery would be a differently named Run Once package included in the group’s Open Mobile profile. The profile would need to be updated monthly on the Open Mobile Portal with each successive package.

Alternatively, you can delete all files in %PROGRAMDATA%\NGCROP, and then run the package again. This will remove any existing package files, as well as the flag that indicates whether a particular package has been executed.

Best Practices

When creating a Run Once package, the following best practices are recommended:

Testing

Thorough testing of your script or executable, as well as the package files themselves is crucial to ensuring proper functionality. A proper testing regime will test across a range of Windows environments and in a variety of situations.

Robust Scripts

A single script must be able to recover robustly from error, and may even need to be executed multiple times. For example, a user may interrupt the file execution process by rebooting the machine in the middle of first execution, causing the script to fail before completion. As a result, it is recommended that parameters be included in your scripts to check if the package is actually required by the user. For example:

IF <MyPackage> EXIST THEN EXIT
INSTALL MY PACKAGE

Limited Package File Size

An interrupted ROP file download is started again from the beginning of the file that was interrupted. Although there is a 16 MB limit on the size of an ROP package, it is recommended that very large files be broken into smaller pieces. If the package download is interrupted, the download can begin again with the interrupted file rather than starting from the beginning of the package. Many file compression utilities, such as WinRAR, are capable of breaking large files into smaller units.

Logical Paths

Where possible, specify logical paths in scripts rather than physical ones to ensure that your scripts work across different Windows platforms. For example, the physical location of downloaded files on a Windows XP machine differs from their physical location on a Windows 7 machine. Correct use of logical paths (or environmental variables) can obviate this issue.

Go to: Open Mobile for Windows Help

 

©2015 iPass Inc. All rights reserved. Terms of Use