App Distribution Package Actions and Detection Rules
Package actions define how app distribution will deploy your packages. Package detection rules help app distribution decide whether an app should be deployed to a device.
Package actions
Configure package actions in App distribution > App catalog. Add or edit an app, and select the Package tab. Drag the actions you want to use and drop them in the builder tree. Select an action in the builder tree to configure it.
The available package actions include:
These can help determine whether the app is already installed and therefore should not be installed again.
IMPORTANT: If any detection step resolves as true, package processing stops and the device's app state will display as compliant.
See Package detection rules later in this topic for more information on the available detection rules.
: Downloads a file to the Ivanti app distribution default working path:
C:\Program Data\Ivanti\Ivanti Cloud Agent\Agent\SWD\working
Any action that accepts a file path will assume this path unless you specify otherwise. This folder is cleared before and after each package is run.
You can specify multiple files here and you can have multiple download file actions if necessary. Files can be hosted on any HTTP(S) location that does not require authentication and that clients you are deploying to can access.
Cloud file explorer
The Choose file button opens the Cloud file explorer, where you can choose files from your organization's Microsoft Azure Blob Storage. An Azure storage account is not included with Ivanti Neurons. For information on how to create a storage container in Azure, see this Microsoft article.
Before using the cloud file explorer, you must add your Azure Blob Storage credentials in Admin > Credentials. For more information, see Credentials. With Azure, we recommend you create credentials in Ivanti Neurons for both your Azure key1 and Azure key2 to allow for Azure key rotation. You can then select the account you want in the cloud file explorer.
These credentials are used to populate the folder and file list so the download file action can get Shared Access Signature URLs (Microsoft Azure) for the files you select. Clients will not use these credentials.
Once you have added credentials, you can select your cloud storage Account and Container in the cloud file explorer. The container browser shows files and folders stored there. Add one or more files by selecting the check box next to them and selecting the Add button. URLs for the files you added then appear in the Download file action properties.
Cloud storage providers require that generated URL tokens have an expiration. App distribution sets the token expiration to seven days, and every five days it renews the token to prevent loss of access from targeted clients.
When viewing Azure Blob Storage, there is an Upload button that allows you to browse for and upload files you select. Uploaded files are put in the folder you have selected in the explorer. It can take a while for large files to finish uploading, so you may not see uploaded files immediately in the explorer.
Cloud file filtering in the Filter by prefix text box is limited by the Microsoft API. The filter is limited to the folder you have selected and does not include subfolders. The filter text you enter must be an exact filename (case-sensitive) match and start with the first character of the filename you want. You do not have to include the full filename, just the initial characters.
SHA256 hash value
The download file option also includes an optional hash value field. If you provide a hash value, app distribution will validate the downloaded file's hash value. If the values do not match, app distribution will delete the downloaded file and stop the distribution. If you want app distribution to use advanced distribution technologies like peer download, you must provide a hash value.
The plain Execute action allows you to specify a file to execute, a command line, and what user the installer should run as. The Execute MSI and Execute MSIX actions let you select MSI, MSP, and MSIX-specific operations and display options.
Includes create folders; move, copy, and delete files; zip or unzip.
Reboots the device according to the device's agent policy. When an app requires a reboot, no other apps can be installed to that device until it reboots.
Create or delete registry keys. Set or delete registry values.
Execute a batch file or PowerShell script. The PowerShell Core option does not install PowerShell Core if it is missing. The Auto option will first try PowerShell Core, and if that isn't installed it will fall back to PowerShell. A script editor is built in to this action. Your script code needs to be added inside this editor.
Pauses package execution for the number of seconds you specify. Use this if earlier actions need additional time to complete.
Package detection rules
Package detection rules can help determine whether a package is already installed and therefore should not be installed again.
Configure package detection rules in App distribution > App catalog. Add or edit an app, and select the Package tab. Add the Detection pre-deployment action to the builder tree and select it to configure it.
Detection rules are only checked at the beginning of processing a package, and so a detection action will always be the first item in the builder if it is used. Detection rules run in the order that they are defined.
IMPORTANT: If any detection step resolves as true, package processing stops and the device's app state will display as compliant.
The available detection rules include:
Provide the full file path and file name. Select either Exists or Does not exist.
File version information is generally only available for executable files. App distribution uses the "File version" value, not the "Product version" value. Provide the full file path and file name. The operator can be variants of less than or greater than, equal, or is between. If the file and path you specify does not exist or if the file does not have a parsable version, it returns false.
For details on how version and comparison operators work, see this article from Microsoft.
Provide the full file path and file name. Specify the file size in bytes. App distribution uses "Size" and not "Size on disk." If the file and path you specify does not exist, it returns false.
Provide the full file path and file name. Select the SHA-2 bit length you are comparing. If the file and path you specify does not exist, it returns false. You can use PowerShell to generate a hash digest:
-
Get-FileHash -Algorithm SHA256 -Path C:\MyApp\myfile.exe
This rule looks only at the date, not the time. Provide the full file path and file name. Select an operator, like Equals. The file date must be specified in UTC (coordinated universal time), matching your locale's equivalent of mm/dd/yyyy format. App distribution uses the "Modified" date, not the "Created" date. If the file and path you specify does not exist, it returns false. You can use PowerShell to retrieve the file date in UTC:
-
(Get-Item C:\MyApp\myfile.exe).LastWriteTimeUtc
Provide the MSI product code GUID and select whether the MSI Is installed or Is not installed. Use Microsoft's Orca tool to view the "ProductCode" GUID. You can also see installed MSI GUIDs under these registry keys:
- HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall
- HKLM\SOFTWARE\WOW6432Node\Microsoft\Windows\CurrentVersion\Uninstall
- HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall
Provide the MSIX package full name and whether the MSIX Is installed or Is not installed. Use the PowerShell Get-AppxPackage command to find the package full name, as Microsoft describes here.
Provide the registry key information for the key you want to detect.
- Registry version: Select 32-bit or 64-bit as appropriate, or you can select System if you want to automatically match the version that the targeted device is using.
- Root key: Select the root key containing the key you want to detect, such as HKEY_LOCAL_MACHINE.
- Key: Enter the full path (do not include the root key you already specified) to the registry key name you want to detect.
- Specify Exists or Does not exist
Provide the registry key and value information for the value you want to detect. If the key or value does not exist or is not accessible by the user, the rule will return false (unless the comparison operator is Does not exist).
You must specify a value name, unless you want to check the "(Default)" value, in which case it must be left blank.
When doing a version comparison, the comparison operand(s) and the data associated with the registry value must be in the version format described here. If any of those is not, the detection rules (and the package) will generate an error.
For details on how version and comparison operators work, see this article from Microsoft.
String comparison is case-sensitive. If the registry value has data that is not of type REG_SZ (String), it is converted to a string as follows:
- REG_DWORD: The decimal form (as shown in regedit.exe) is used.
- REG_QWORD: The decimal form (as shown in regedit.exe) is used.
- REG_BINARY: The byte pair form used by regedit.exe is used, but capitalized (e.g. "46 AA 6C 6B 65 6E").
- REG_MULTI_SZ: The lines are concatenated together with spaces to form a single line (for example, "Line1 Line2 Line3").
- REG_EXPAND_SZ: All environment variables are expanded.
Detection scripts can use PowerShell (not PowerShell Core) or batch syntax. Detection success is based on the script's numeric exit code. An exit code of "0" (zero) equals true. Any other exit code is considered false. The exit code must be numeric and not the word "True". Use the built-in script editor to create your script.
Use the built-in script editor to create a script, or you can use the Select file option and browse for a file. The file and path you provide must exist on the target system. If the script file is not already on the device, use the Download file action to place it there. When you do this, the downloaded file is placed in a default path and you can just specify the file name.
Since detection rules run before other package actions, this places detection rule scripts at a unique stage in the app installation process. It is possible to do more complex things here, such as runnning a customized upgrade script that looks for an older app installation and if it finds it, uninstalls it before proceeding on with the rest of the package.
Detection rule and action logging
App distribution creates a log file for each app deployed to a device. The log has entries for each detection rule and other package actions. If detection rules are not working as expected, use the log file to help determine why. Logs are stored on each device in this folder:
- C:\ProgramData\Ivanti\Ivanti Cloud Agent\Logs\SWDApps
Each log file name includes the package GUID. If you edit a package in the App Catalog, you can see its package GUID in the web browser URL. This will help you find the log file you are interested in.
You can view a simplified log remotely from the App Distribution > Deployment Status page. Find the device and package you want to see, and on the right, select the action menu's View log option.