Unified Application Management: Shell Apps Technical Reference Guide

This topic is the shell apps technical reference guide.

Execution Context

All scripts are run on behalf of the local system account.

Detect Script

Executed from 1 to 2 times depending on the required action and the actual installation status.

Return Type

• $true: Application is installed (single-version mode only).

• $false: Application is not installed (single-version mode only).

• string: Detected version name.

• $null: Application is not installed.

Install Script

Executed only when the target action is Install and Detect script returns $false, $null, or non-target version name. See Flow Examples for additional information.

Return Type:

• void: The installation completed successfully. Final compliance status is reevaluated by a second execution of Detect script.

Uninstall Script

Executed only when the target action is Uninstall and Detect script returns $true or string version name. See Flow Examples for additional information.

Return Type

• void: The uninstallation completed successfully. Final compliance status is reevaluated by a second execution of Detect script.

$Context Object Specs

A global variable managed and injected to all scripts by Nerdio Manager.

Properties

• Log(message: string | string[]): Function to log any message which is later available on the policy Details page. For example, $Context.Log('Hello world').

• GetAttachedBinary(version: string | null): Download the attached file and return the absolute path to it in a temporary folder. See File Attachment for details.

• TargetVersion: string | null: Version name configured in deployment policy's Install action, null in case of Uninstall action. [Nerdio Manager v6.6+]

• DetectedVersion: string | null: Version name returned by Detect script, null in case of any other return type. [Nerdio Manager v6.6+]

• Versions: ShellAppVersion[]: All shell app version definitions. [Nerdio Manager v6.6+]

ShellAppVersion Object Specs

Properties

• Name: string: Version name.

File Attachment

Any shell app version may have arbitrary binary data attached to it. And any script has the ability to acquire this binary data using the convenient $Context.GetAttachedBinary() function call.

Calling this function does the following:

• Download the file if it's not already downloaded.

• Cache the downloaded file in an internal storage.

• Copy the file to a temporary folder.

• Return the absolute path of the file in a temporary folder.

The function receives the optional version name parameter to provide the file attached to the specific version. If the version is not provided, then Nerdio Manager tries to find the single logically suitable file according to context:

• If the shell app has a single version then, select that file. Else:

• If the action is Install, then select its target version's file. Else:

• If the Detect script returned a proper version name, then select that file. Else:

• Raise an error.

Multi-version Mode Key Notes

• The Detect script must return a proper version name if one is detected on the host, or null if any is not (unlike Boolean allowed in single-version mode).

• The Detect script returned result is the ultimate source of truth if the application is installed or not. And it is a driver for all follow-up executions of Install/Uninstall.

• Nerdio Manager does not make any assumptions, nor track any internal state on the host, in relation to application detection.

• The customer is free to write any logic needed to track the currently installed shell app version. For example, in the registry key, in a file, etc.

Availability on Unified Catalog Page

Shell app availability in the Unified Catalog is controlled by a Public check box on the General step of the corresponding shell app management.

Version Configuration UI

This section explains some details of version management UI that is seen on the Versions wizard step of each shell app management.

• Name: The version name stored in x.x.x.x format. This must be identical to the version returned from the detection script to return a positive value to any associated install policies.

• Unzip (disabled): This is not recommended for new shell apps since this option is only supported in single-version mode and its behavior may change in future.

  Note: This option was initially introduced specifically for SCCM PowerShell applications import support. If selected, your zip file is extracted into a temporary folder and the context is set to that folder. Therefore, you are able to use the files from the archive directly. The same behavior can be achieved by using the following chain: $Context.GetAttachedBinary() -> Expand-Archive -> Set-Location.

• File : Attach a specific file to the current version which can be called from the install script script via $Context.GetAttachedBinary().

• Override install: This provides the ability to override the global install script when installing the current version. This might be convenient for some trivial versioning scenarios.

Parameterization

Starting with Nerdio Manager v6.1, any script can be parametrized with securely injected values of secure variables configured on Settings > Nerdio Environment > Secure Variables tile. See Scripted Actions Global Secure Variables for details.

To use this feature, simply insert the following boilerplate at the beginning of your script to dynamically inject variable values as script parameters.

Flow Examples

Single-version Mode

For standard single-version installations, the detection script is run initially to validate that the installation is required by confirming that the detection rule returns false. If the detection rule returns false, the install script is executed, and the detection rule is re-run. If the rule returns false, this reports as a failure. If the rule returns true, this reports as a success.

Multi-version Mode

For multi-version installations, the detection script is run initially to validate that the installation is required by confirming that the version detection rule returns a different value than that was defined in the detection rule. If the version detection rule does not equal the defined value, the install script is executed, and the detection rule is re-run. If the rule does not return the defined version value, this reports as a failure. If the rule returns the defined version value, this reports as a success.

Troubleshooting

Encountered errors stack traces are available on the deployment policy Details page. In addition, you can select the Request App management logs button in the Host Application Management task for a particular host to extract all the deployment logs.