The optional Instructions XML file you create provides Package Manager with instructions for customized execution of package installation.

The instructions XML file consists of a root <instructions> element with several child elements. Each child element is optional.
  • <targetAttributes>
  • <customDirectories>
  • <shortcuts>
  • <returnCodeConventions>
  • <customExecutes>
  • <osUninstallEntry>

Name the instructions XML file instructions, omit the file extension, and place it in the root of the data directory of a File package.

The following text is an example instructions file for a File package. 

<instructions>
    <targetAttributes readOnly="allReadOnly"/>
    <customDirectories>
        <customDirectory name="customDir1" path="D:\subdir"/>
        <customDirectory name="customDir2" path="\\myserver\subdir"/>
    </customDirectories>
    <shortcuts>
        <shortcut>
            <destination root="ProgramMenu" path="Test\Shortcut.lnk">
                <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>
                <localizedDestination root="ProgramMenu" path="Test\Raccourci.lnk" language="fr"/>
                <localizedDestination root="ProgramMenu" path="Test\ショートカット.lnk" language="ja"/>
                <localizedDestination root="ProgramMenu" path="Test\바로가기.lnk" language="ko"/>
                <localizedDestination root="ProgramMenu" path="Test\快捷方式.lnk" language="zh-CN"/>
            </destination>
            <target root="Program Files" path="Shortcuts\executable.exe"/>
        </shortcut>
    </shortcuts>
    <customExecutes>
        <customExecute root="Documents" exeName="executable.exe"/>
    </customExecutes>
</instructions>

<targetAttributes> Element

The <targetAttributes> element provides optional instructions regarding locations where Package Manager installs files on the target system.

<targetAttributes> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

Attribute Name Type Possible Values Details Examples
readOnly Enum
  • allWritable —(default) Makes all package files for installation writable regardless of the original source file's read-only attribute value.
  • allReadOnly —Makes all package files for installation read-only regardless of the original source file's read-only attribute value.
  • keepSource —Keeps the original source file's read-only attribute value when installing.
    • Declares to Package Manager whether to make all files read-only, file-writable, or to keep the read-only attribute value from the original source file.
    • The default is allWritable when you do not declare a readOnly attribute or include an instructions file.
    		<targetAttributes readOnly="allReadOnly"/>

    <customDirectories> Element

    The <customDirectories> element provides a list of absolute path locations to which Package Manager installs files on the target system.

    <customDirectories> contains the <customDirectory> child element.

    <customDirectory> Element

    The <customDirectory> element defines one absolute or network path to which Package Manager installs files on the target system.

    You can have multiple instances of <customDirectory> in the Instructions file.

    Attribute Name Type Value Examples
    name String
    Characters that are valid for a Windows directory name:
    • Consist only of lower case letters (a-z), digits (0-9), plus (+) and minus (-) signs, and periods (.)
    • Start with an alphanumeric character
    • Have a min length of two characters
    • Have a max length of 58 characters
    An error results if the name attribute:
    • Is an existing target root
    • Begins with ni_
    • Contains invalid characters
    		 <customDirectory name="examplename1" path="D:\bin"/>
    path String An absolute or network path on the target system <customDirectory name="examplename2" path="\\servername\sharename\subdir"/>

    <shortcuts> Element

    The <shortcuts> element provides a list of shortcuts that Package Manager creates during installation.

    <shortcuts> contains the <shortcut> child element.

    <shortcut> Element

    The <shortcut> element defines one shortcut that Package Manager creates during installation.

    The <shortcut> element is optional in the Instructions file, but you can include as many as needed for your package. <shortcut> contains two child elements:
    • <destination>
    • <target>

    <destination> Element

    The <destination> element specifies the location where Package Manger creates a shortcut file.

    <destination> is required and can have one or more optional <localizedDestination> child elements. It has the following attributes:

    Attribute Name Type Value Examples
    root String A supported target root. Packages with a windows_all architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. <destination root="Startup" path="testShortcut.lnk"/>
    path String The path and file name appended to the root target. Refer to XML Syntax Rules for Quotation Marks for syntax requirements. <destination root="ProgramFiles" path="Shortcuts\test.exe"/>

    <localizedDestination> Element

    The <localizedDestination> element specifies an alternate localized path to use for the shortcut file when installing the file package in a given language.

    <localizedDestination> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

    Attribute Name Type Value Examples
    root String A supported target root. Packages with a windows_all architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. <localizedDestination root="ProgramMenu"/>
    path String The path and file name appended to the root target. <localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" />
    language String

    Language code of the localized path. Possible values:

    • de
    • fr
    • ja
    • ko
    • zh-CN
    		<localizedDestination root="ProgramMenu" path="Test\Verknüpfung.lnk" language="de"/>

    <target> Element

    The <target> element specifies the location of the file for which Package Manager creates a shortcut.

    <target> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

    Attribute Name Type Value Examples
    root String A supported target root. Packages with a windows_all architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. <target root="Startup" path="testShortcut.lnk"/>
    path String The path and file name appended to the root target after it is resolved. Refer to XML Syntax Rules for Quotation Marks for syntax requirements. <target root="ProgramFiles" path="Shortcuts\test.exe"/>
    arguments String Optional arguments passed to the target file. Refer to XML Syntax Rules for Quotation Marks for syntax requirements. <target root="ProgramFiles" path="Shortcuts\test.exe" arguments="--argument1"/>

    <returnCodeConventions> Element

    The <returnCodeConventions> element provides a list of custom return code conventions for Package Manager to use when performing custom actions for this package.

    <returnCodeConventions> is optional in the instructions file, but can contain one or more <returnCodeConvention> child elements.

    <returnCodeConvention> Element

    The <returnCodeConvention> element defines how to interpret a return code for one or more custom executes in this package.

    <returnCodeConvention> can have one or more optional <returnCode> child elements. <returnCode> rules are evaluated in the order they are defined.

    Attribute Name Type Value Examples
    name String A unique name for this return code convention. A custom execute in this package can use this name in its returnCodeConvention field to associate itself with this return code convention. <returnCodeConvention name="alwaysReboot" defaultResult="rebootRequired"/>
    defaultResult Enum Indicates the semantic result of a return code that does not match any existing return code mapping rules.
    • success
    • failure
    • rebootRequired
    		 <returnCodeConvention name="ignore" defaultResult="success"/>

    <returnCode> Element

    The <returnCode> element defines a return code mapping rule for its parent <returnCodeConvention>.

    <returnCode> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

    Attribute Name Type Value Examples
    min Integer Indicates the lower bound of a range of return codes this rule matches. May not be combined with the value attribute. <returnCode min="0" max="1024" result="success"/>
    max Integer Indicates the upper bound of a range of return codes this rule matches. May not be combined with the value attribute. <returnCode min="-50" max="-1" result="success"/>
    value Integer Indicates a single return code this rule matches. May not be combined with the min or max attributes. <returnCode value="1641" result="rebootRequired"/>
    result Enum Indicates the semantic result of a return code matching this rule. <returnCode value="3010" result="rebootRequired"/>

    <customExecutes> Element

    The <customExecutes> element provides a list of custom actions for Package Manager to perform on the package.

    <customExecutes> contains the <customExecute> child element.

    <customExecute> Element

    The <customExecute> element defines one custom action Package Manager performs on the package.

    The <customExecute> element is optional in the Instructions file, but you can include as many as needed for your package. <customExecute> is an empty element, meaning that it has attributes, but does not contain elements or text content. It has the following attributes:

    Attribute Name Type Required Value Description Examples
    root String Yes The root path to the executable. Packages with a windows_all architecture cannot use 64-bit specific target roots, such as ProgramFiles_64 or LV2017DIR64. Specifies the root path to the executable.

    A supported target root. Refer to Installation Target Roots to see supported target roots.

    Note To run an executable, you must first install the package that includes the executable. You can configure a package to temporarily install the executable by setting the target root path to NIPkgMgrTempUnique and setting the schedule attribute to post. Package Manager then installs the package to the NIPkgMgrTempUnique directory and runs the executable from there before deleting files in the directory.
    		 <customExecute root="Documents" exeName="executable.exe"/>
    exeName String Yes The file name of the executable. Specifies the file name of the executable.

    Can include a path relative to the root. Refer to XML Syntax Rules for Quotation Marks for syntax requirements.

    		 <customExecute root="ProgramData" exeName="actions\executable.exe"/>
    arguments String No Command line arguments to pass to the executable. Specifies command line arguments for Package Manager to pass to the executable.
    The value is formatted. You can include a supported target root and/or the following arguments:
    Note The arguments are case insensitive. Refer to XML Syntax Rules for Quotation Marks for syntax requirements.
  • %REBOOTPENDING%—Passes pending reboot information. If a reboot is required at the end of the transaction, Package Manager replaces %REBOOTPENDING% with 1. Otherwise, Package Manager replaces %REBOOTPENDING% with 0. You can use this argument only if the value of the schedule attribute is postall.
  • %NIPMLANGUAGECODE%—Specifies the language in which Package Manager runs using the ISO language code. Possible values: en, de, fr, ko, ja, or zh-CN.
    • <customExecute root="ProgramData" exeName="executable1.exe" arguments="-open %desktop%\file.txt"/>
    • <customExecute root="ProgramData" exeName="executable2.exe" arguments="-reboot %rebootpending%" schedule=postall/>
    • <customExecute root="ProgramData" exeName="executable3.exe" arguments="-language %nipmlanguagecode%"/>
    step Enum No
  • install —(default) Package Manager runs the executable when installing the package.
  • uninstall —Package Manager runs the executable when removing the package.
  • reinstall—Package Manager runs the executable when repairing the package.
    		• Specifies the transaction step during which Package Manager runs the executable.
    • To run the same executable in multiple steps, such as install, uninstall, and repair, list a <customExecute> element for each step.
    • If you omit this attribute, Package Manager uses its default value.
    Note During the development of a package, if you set the value of step to uninstall, set the value of ignoreErrors to y in order to avoid a situation where Package Manager cannot remove a package from the target system.
    		 <customExecute step="uninstall" root="ProgramData" ignoreErros="y" exeName="actions\executable.exe"/>
    schedule Enum No
    • post (default)
    • pre
    • postall
    		 Specifies the relative point within the transaction steps when Package Manager runs the executable.

    If you omit this attribute, Package Manager uses its default value.

    		 <customExecute step="install" schedule="post" root="ProgramData" exeName="executable.exe"/>
    wait Boolean No
    • n (default)
    • y
    		 Specifies whether the custom action is synchronous, where Package Manager should wait for it to finish before continuing, or asynchronous, where Package Manager should not wait.

    If you omit this attribute, Package Manager uses its default value.

    		 <customExecute root="ProgramData" exeName="executable.exe" wait="n"/>
    ignoreErrors Boolean No
    • n (default)
    • y
    		 Specifies whether Package Manager reports an error if it cannot run the executable or the executable returns a value other than 0.
    • Requires you to set the value of wait to y so Package Manager will wait to receive the return code.
    • If you omit this attribute, Package Manager uses its default value.
    • This attribute may not be used in combination with either ignoreLaunchErrors or returnCodeConvention.
    		 <customExecute root="ProgramData" exeName="executable.exe" wait="y" ignoreErrors="y"/>
    hideConsoleWindow Boolean No
    • n (default)
    • y
    		 Specifies whether to hide the console window for console applications.
    • Does not display console messages when you run GUI applications.
    • Console applications still run, but without a console window for user input or message output.
    • If you omit this attribute, Package Manager uses its default value.
    • Does not prevent the application from creating additional console windows.
    		 <customExecute root="ProgramData" exeName="executable.exe" hideConsoleWindow="y"/>
    ignoreLaunchErrors Boolean No
    • n (default)
    • y
    		 Specifies whether Package Manager reports an error if it cannot run or cannot find the executable. This attribute may not be used in combination with ignoreErrors. <customExecute root="ProgramData" exeName="executable.exe" ignoreLaunchErrors="y"/>
    returnCodeConvention String No Must match the name of a predefined convention or a <returnCodeConvention> element defined in this package. The following predefined conventions are available:
    • console (default)
    • installer
    • ignore
    		 Indicates how to interpret the return codes the executable returns.
    • wait must be set to y, so the agent waits to receive the return code
    • For console, 0 = success and any other value is an error.
    • For installer, 0 = success, 1641 = reboot required, 3010 = reboot required, and any other value is an error.
    • For ignore, Package Manager ignores the return code.
    • This attribute may note be used in combination with ignoreErrors.
    		 <customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/>

    Behavior of Executables Scheduled as Postall

    For Instructions files in which you include a <customExecute> element where schedule="postall", Package Manager demonstrates specific behaviors that may affect package installation.

    The postall value instructs Package Manager to run the executable after completing the installation, reinstallation, and/or removal steps for all packages.

    • Package Manager runs postall executables in the specified order of package installation. Dependencies install first.
    • If only a postall executable in a package fails, Package Manager considers the package installed.
    • When there are multiple packages with postall executables, Package Manager does not run the remaining executables if one of the postall executables fails. Packages are considered installed assuming no other errors occurred during installation.
    • If installation of a package fails, either through MSI failure or failure of an executable scheduled as pre or post, Package Manager displays an error message stating that the package failed to install. Next, it runs all the executables from packages installed up to the point where installation failed. Package Manager does not consider the broken package installed and does not run the postall executables of the broken package. All packages installed before the failure occurred remain installed and Package Manager runs the postall executables of these packages.

    XML Syntax Rules for Quotation Marks

    Review the XML syntax rules for quotation marks to adhere to Microsoft's conditional statement syntax and to enclose paths with spaces within quotation marks.

    You must enclose literal text within quotation marks to adhere to Microsoft's conditional statement syntax. The Instructions XML syntax provides two ways of adhering to this requirement:

    • Use single quotation marks to delimit the XML string. This allows the use of double quotation marks inside the string. For example:
      <customExecute condition='IEDETECTED~="Yes" AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE'/>
    • Use the XML escape character for double quotation marks, &quot;, to delimit the literal text in the XML string. With the XML escape character, you can use double quotation marks or single quotation marks to delimit the XML string. For example:
      <customExecute condition="IEDETECTED~=&quot;Yes&quot; AND VersionNT64 = 601 AND NIRUNNINGINSILENTMODE"/>

    You must enclose paths with spaces within quotation marks. Single quotation marks are not allowed in the path:

    • Use the XML escape character for double quotation marks, &quot;, to enclose path in the XML string. For example:
      <customExecute exeName="&quot;VC RunTime Installer.exe&quot;" arguments="/q /norestart" inPackage="y"/>

    Custom Execute Examples

    The following invokes a PowerShell script that the package could have installed and passes two arguments after installation.

    <customExecute root="BootVolume" exeName="Windows\System32\WindowsPowerShell\v1.0\powershell.exe" arguments="-File &quot;%ProgramData%\My App Name\MyInstallScript.ps1&quot; &quot;argument 1&quot; &quot;argument 2&quot;" step="install" schedule="post" wait="y" ignoreErrors="n" hideConsoleWindow="y" />

    <osUninstallEntry> Element

    The <osUninstallEntry> element provides optional instructions for the package to appear in the Add/Remove Programs interface.

    <osUninstallEntry> is an empty element. That is, it has attributes but does not contain elements or text content. <osUninstallEntry> has the following attributes:

    Attribute Name Type Possible Values Details Examples
    ux Enum
  • ni—(default) Shows normal Package Manager interface elements during a modify or uninstall operation.
  • oem—Hides all dialog text and links referring to NI during a modify or uninstall operation.
    		• For third-party packages, the oem value allows the package to appear as a first-class item in the list of installed applications. When performing modify and uninstall operations, the Add/Remove Programs interface only refers to the named package. <osUninstallEntry ux="oem"/>