UAM: Shell apps technical reference guide

Detect script

Detect script is executed one to two times depending on the required action and the actual installation status. It will finish with one of the following results:

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

This is 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

This is 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 $Context.GetAttachedBinary() function call.

Calling this function does the following:

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

• Caches the downloaded file in an internal storage.

• Copies the file to a temporary folder.

• Returns 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. Nerdio Manager then attempts to find the single most suitable file based on context. There are four possible results:

• If the shell app has a single version, it selects that file.

• If the action is Install, it selects its target version's file.

• If the Detect script returned a proper version name, it selects that file.

• Raises 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 none is detected. This differs from single-version mode, which allows a Boolean return value (a simple true/false indicating whether the app is present or not).

• 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 (e.g. 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

Here are some details of version management UI that are 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 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 runs first to determine whether installation is needed. If the detection rule returns false (meaning the application is not present), the install script executes. The detection rule then runs again. If it returns false a second time, the installation is reported as a failure; if it returns true, it is reported as a success.

Multi-version mode

For multi-version installations, the detection script runs first to determine whether installation is needed. If the version detection rule returns a value that does not match the defined target version, the install script executes. The detection rule then runs again. If it still does not return the defined target version, the installation is reported as a failure; if it does return the defined target version, it is reported 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.