Product Documentation

Configuring Macro Substitution for Uploading Files

Apr 09, 2015

If you want to upload files and Mortscript script files, select the Macro must be replaced box. When you select this check box, it indicates that the script file must be checked before deployment to substitute macros with dynamic values that depend on the user and device.

An example of a macro in a Mortscript script is as follows:

result = Question( "Hello world, mail = %{ user.mail? | protect('"', '"') | encode('UTF-8') }%!", "It’s a start!", "YesNo")

The macro is located between the %{...}% tags. The server does not detect in advance the file format or its encoding. Instead, the files are analyzed in binary format. The “%”, “{“, ... are checked in ASCII format. Those are compatible with most characters encoding (but not UTF-16).

The macros are made of several parts separated by the pipe character: xxx | yyy | zzz:

  • The first element indicates a property: user.xxx for a user property, or device.xxx for a device property. You can use the ? character to indicate to use an empty string if the property is not defined.
  • The next elements are filters used to encode, transform and mostly protect the string so that it can enter the file context.

In this example, the elements are: user.mail? | protect('"', '"') | encode('UTF-8')

  • user.mail? : insert the “mail” property of the user. Use an empty string if it is empty or not defined.
  • protect(‘”’, ‘”’): protect the quote character by adding another quote before it. This protection is specific to Mortscript that requires to double that character when one wants to define one. For instance: “This is a quote “” in Mortscript”.
  • encode('UTF-8'): encode the string in UTF-8.

The last part is important since only a binary element can be inserted by Device Manager:

  • user.mail? : give a character string.
  • protect('"', '"'): takes a string in input and outputs a string.
  • encode('UTF-8'): takes a string in input and outputs a binary array.
Note: Use other encoding if necessary, like CP1252 in France if you want to use accentuated characters.

This other available functions are:

  • S64Encode: [binary => text] encodes a binary in S64.
  • S64Decode: [text => binary] decodes a S64 string to binary.
  • B64Encode: [binary => text] encodes a binary in Base64.
  • B64Decode: [text => binary] decodes a Base64 string to binary.
  • encode(encoding): [text => binary] encodes a string with a specific encoding.
  • decode(encoding): [binary => text] decodes a binary array to a string.
  • protect(searched_character, protection_character): [text => text] insert the protection_character before the searched_character.
  • transform(searched_string, replacement_string): [text => text] replace searched_string by replacement_string.

You can use the following user properties in the scripts:

  • cn
  • company
  • companyname
  • property_country
  • department
  • description
  • displayname
  • distinguishedname
  • facsimiletelephonenumber
  • givenname
  • homecity
  • homecountry
  • homefax
  • homephone
  • homestate
  • homestreetaddress
  • homezip
  • ipphone
  • mail
  • middleinitial
  • mobile
  • officestreetaddress
  • pager
  • physicaldeliveryofficename
  • postalcode
  • postofficebox
  • telephonenumber
  • samaccountname
  • sn
  • st
  • streetaddress
  • title
  • userprincipalname
  • domainname

When users connect to an LDAP directory, most these properties are completed automatically. You can also manually enter the properties in the user properties dialog.

You can use the following device properties:

  • ew_version
  • ew_revision
  • cpu_clock_speed
  • sim_id
  • memory
  • freedisk
  • tel_number
  • system_oem
  • system_platform
  • cpu_type
  • system_os_version
  • system_os_build
  • memory_available
  • total_disk_space
  • system_language
  • user_language
  • screen_width
  • screen_height
  • screen_nb_colors
  • main_battery_percent
  • backup_battery_percent
  • battery_charging
  • external_storage1_name
  • external_storage1_total_space
  • external_storage1_free_space
  • external_storage2_name
  • external_storage2_total_space
  • external_storage2_free_space
  • user_defined_1
  • user_defined_2
  • user_defined_3

You can also use any custom property defined for the device or user.

Examples of Simple Mortscripts

Ask for Reboot Script Example

Result=Question("Your device needs to be rebooted. Do you want to reboot now?", "Hello %{ user.name? | protect('"', '"') | encode('UTF-8') }%!", "YesNo")

If ( Result=YES)

Reset

EndIf

This script opens a dialog box with the Yes and No buttons. It asks for the user to reboot now or later. If Yes is pressed, the device will reboot. If No is pressed, nothing happens except that the dialog is closed.

The title of this dialog displays the name of the user, as stored in a custom property of the user.

Data Upload Script

Here is an example of a Mortscript script used to upload a file to a FTP server:

FtpUpload("My Documents\test.zip", "incoming/file.zip", "ftp.mydomain.com", "test", "test", TRUE)

This simple script will upload the file test.zip, located in the directory “My Documents” of the device, to the server ftp.mydomain.com, in the directory “incoming”. The file will be renamed file.zip. It will use the login “test”, and password “test”, and use the passive mode of the ftp protocol.

The synopsis of the FtpUpload function is the following:

FtpUpload( source file, target file, server, [ user [, password [, passive? [, port] ] ] ] )

Note: In this Device Manager release, the FtpUpload function is not yet part of the standard Mortscript program but is only available in the Device Manager release of MortScript.

To upload a MortScript file

You can add MortScript (.mscr) files to Device Manager to deploy to Windows Mobile devices. MortScript is a batch scripting language that allows you to perform basic functions, such as opening or closing apps, running processes, creating directories, establishing or closing network connections, and other basic device functions,
  1. Click the Files tab and then click New file.
  2. In the Import a file to the XenMobile MDM database dialog box, browse to the MortScript file on your computer and then click Open.
  3. Enter the following script parameters:
    1. Execute script. Select this option to execute the script automatically when the file transfer is done.
    2. Macro must be replaced. Select this option if you want to search and replace the macros inside the scripts.
    3. Specify what to do if the file already exists. If the files are different, you can choose make a copy or to not overwrite the existing one.
      Note: You must encode MortScript files by using ANSI character set if possible. Unicode is also supported with proper prefixes.
  4. Click Import.