Writing scripts for remote actions on Mac

The payload of remote actions on macOS computers are Bash scripts that run on employee devices. Bash is a command-line shell and scripting language that is supported by many UNIX-like operating systems, such as macOS, and is suited for task automation and configuration management. Bash scripts are ideal for getting on-demand data from devices, performing self-healing tasks or modifying the configuration of a device, which are typical use cases for remote actions.

This article assumes that the reader is familiar with Bash scripting.

Refer to the Remote actions group in Community for more information.

Encoding

To write your own Bash scripts for remote actions:

• Encode the files that contain the text of your scripts in UTF-8, without BOM.

• End each line in the code with the usual character in UNIX systems: LF.

Failing to provide the right encoding to your script files will result in the inability of remote actions to run on employee devices.

Signing and packaging your own scripts

For security reasons, Nexthink requires Bash scripts for remote actions on macOS to be digitally signed with the codesign tool. Additionally, package your signed script as a tar.gz file to preserve its extended attributes. Nexthink web interface only accepts files with the tar.gz extension when importing scripts for remote actions that target macOS.

Refer to the Signing remote action scripts on Mac documentation for a step-by-step guide.

Writing generic scripts

You can write scripts in a generic way to adapt them to particular use cases. To make your script generic, declare formal parameters at the beginning of the Bash script. Provide actual values to the parameters in the Nexthink web interface when editing the remote action that contains the script.

Genericity is especially useful in the case of digitally signed scripts that require customization. When a script is signed, any modification to its text content breaks the signature. By making a signed script generic, you allow its customization through the parameters. With parameters, the text of the script remains unchanged, and the digital signature remains valid. The values for the parameters that a remote action passes to the script determine its actual behavior.

Declare parameters at the beginning of a script for Bash positional parameters and enclose them between two special comments as follows:

# NXT_PARAMETERS_BEGIN
Parameter1=$1
Parameter2=$2
Parameter3=$3
# NXT_PARAMETERS_END

When uploading the script during the remote action configuration, the system the parameters between the special Nexthink comments in a Bash script and lists them in the Parameters section below the script text. Provide actual values to the parameters in the text input boxes displayed to the right of each parameter name.

The actual values are always passed to the script as text. If the script declares parameters with a type other than string, ensure that you provide values that the script can convert to their expected type.

Output variables

The execution of a script may generate output that you want to store as on-demand data. To that end, Nexthink provides a Bash script (nxt_ra_script_output.sh) that is installed on an employee device at the same time as Collector. The script includes functions to write results to the data layer.

To use the functions in the Nexthink script for remote action output, add the following header at the beginning of your Bash scripts:

#!/bin/bash
. "${NEXTHINK}"/bash/nxt_ra_script_output.sh

All write methods accept two arguments: the name of the output and the value to write. For instance, if you want to return the number of files in a directory to the data layer, the variable nfiles in your script contains that number. To write the value of nfiles through output with the name FileNumber to the data layer, call the function to write unsigned integers:

nxt_write_output_uint32 'FileNumber' $nfiles

The Remote Actions editor recognizes the calls to write outputs in the script and lists the output variables in the Outputs section. Set the label of the output to indicate how to refer to it in investigations and metrics.

The ending of each write method indicates the type of output. Because Bash is a loosely typed language, the type of output is interpreted depending on the context. The following is a list of available methods:

Interacting with employees in self-help scenarios

Obtaining a campaign identifier

The methods to run a campaign from a remote action require a campaign identifier to be passed as an argument. You can use both the campaign NQL ID (recommended) and the campaign UID (classic option).

Support for the NQL ID as an identifier requires Collector version 23.5 or later.

To pass the campaign identifier to a remote action, declare a parameter in the script of the remote action for each required campaign. Use the NQL ID (or UID) as the actual value for the parameter when editing the remote action.

Refer to the Triggering a campaign documentation for more information on how to get the NQL ID or the UID of a campaign.

Running a campaign from the script of a remote action

The following functions extend the scripting capabilities of remote actions.

nxt_run_campaign( id )

The function runs the campaign matching the NQL ID (preferred) or UID passed as a parameter and saves the answers internally.

• The function returns 0 if the campaign status is received.

• The function returns 1 in all other cases, and the error is reported in the logs.

Calling the function pauses the execution of the remote action until the employee either completes the campaign or dismisses it.

nxt_run_campaign_with_timeout( id timeout)

The function runs the campaign matching the NQL ID (preferred) or UID with the timeout in seconds (0 < T < 1 week) passed as a parameter, and saves the answers internally.

• The function returns 0 if the campaign status is received.

• The function returns 1 in all other cases, and the error is reported in the logs.

Calling the function pauses the execution of the remote action until the employee either completes the campaign, dismisses it or fails to finalize the campaign before the timeout.

nxt_run_standalone_campaign( id )

The function runs the campaign matching the NQL ID (preferred) or UID passed as a parameter and saves the answers internally.

• The function returns 0 if the campaign status is received.

• The function returns 1 in all other cases, and the error is reported in the logs.

Calling the function triggers the start of the campaign and continues the execution of the remote action without waiting for the employee's answers.

nxt_get_campaign_status( res_var )

The function returns the status of the last campaign.

• fully: the employee has fully answered the campaign questions.

• timeout: the campaign was timed out before the user finished answering.

• postponed: the employee agreed to participate in the campaign.

• declined: the employee declined to participate in the campaign.

• connectionfailed: the script was unable to connect to the Collector component that controls campaign notifications.

• notificationfailed: the script was unable to display the campaign successfully, due to one of the following:

  • The campaign definition could not be retrieved from the platform because of a non-existing campaign or non-published campaign.

  • Another campaign is already being displayed to the employee.

  • A non-urgent campaign cannot be shown due to the focus protection or do-not-disturb rules of Collector. Refer to Limiting the reception rate of campaigns for additional details.

• Empty, if the last campaign failed.

nxt_get_response_answer( res_var question_key)

Query the last campaign using a question label as a string parameter query_key. The function extracts the answer as a string value and saves it in the given variable res_var.

• Returns 0 if the campaign status is received.

• Returns 1 otherwise.

Code examples

Calling a campaign

 # This is a simple example to demonstrate the basic call for a campaign

if nxt_run_campaign "#my_campaign_nql_id"; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
    else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi 

Accessing the answers

# Simple access to the response data
 
nxt_get_campaign_status status
echo "The response status is $status"
nxt_get_response_answer answersArray key1
echo ${answersArray[1]}

# Careful - Bash uses 0 to n-1 whereas Zsh uses 1 to n.

Running a campaign with a timeout

# Run a campaign with timeout
# timeout is in seconds (100s or 00:01:40)

if nxt_run_campaign_with_timeout "#my_campaign_nql_id" 100; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
    else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi 

Running a non-blocking campaign

# Run a non-blocking campaign
 
if nxt_run_standalone_campaign "#my_campaign_nql_id"; then
    nxt_get_campaign_status status
    if [[ status == "fully" ]]; then
        echo "Campaign succeeded"
    else
        echo "Status is $status"
    fi
else
    echo "Campaign failed"
fi

Script termination and timeout

If you launch subprocesses from your remote action script and the remote action script terminates or times out, Collector terminates the subprocesses automatically. If you want the subprocess to continue executing after the remote action is terminated, ensure that your script detaches the subprocess using the & character, for example:

some_script.sh -arg1 -arg2 &

Zsh command interpreter

Starting with Collector version 6.27.2, you can run scripts written for the Zsh Unix shell. You must add the following line of code at the very beginning of the shell script:

#!/bin/zsh

This is a character sequence known as a shebang (external link).

When the system triggers a remote action on a Mac, Collector checks the first line of code and then executes the rest of the instructions using the specified interpreter. A script without a shebang will be executed using the Bash command interpreter.

Nexthink recommends always using a shebang in shell scripts and sticking to the standard interpreters.

The operations described in this article should only be performed by a Nexthink Engineer or a Nexthink Certified Partner.

If you need help or assistance, please contact your Nexthink Certified Partner.

RELATED TOPIC

• Signing remote action scripts on Mac