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"/>

    <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. This element 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. For a list of target roots, refer to Installation 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. Set the target root path to NIPkgMgrTempUnique and set the schedule attribute to post. Package Manager then installs the package to the NIPkgMgrTempUnique directory to run the executable. Then Package Manager deletes the 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.
    You can include a supported target root along with the following arguments:
    Note The arguments are case insensitive. For syntax requirements, refer to XML Syntax Rules for Quotation Marks.
  • %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 If you set the value of step to uninstall, set the value of ignoreErrors to y. Setting this value during the development of a package prevents Package Manager from removing 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 or asynchronous. When synchronous, Package Manager waits for the custom action to finish before continuing. When asynchronous, Package Manager does 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. This value forces Package Manager to wait and receive the return code.
    • If you omit this attribute, Package Manager uses its default value.
    • You cannot use this attribute 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. You cannot use this attribute 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 that this package defines. 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 might note be used in combination with ignoreErrors.
    		 <customExecute root="ProgramData" exeName="executable.exe" returnCodeConvention="installer"/>

    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"/>