# Writing scripts for remote actions on Mac

{% hint style="info" %}
If you need help performing the operations described in this article, please contact your Nexthink Certified Partner.
{% endhint %}

This article details the process of preparing Nexthink remote action scripts on Mac. The scripts are written in Bash, a command-line shell and scripting language supported by many UNIX-like operating systems, and then signed with a certificate for security purposes. Bash scripts are suited for automating tasks and configuration management; They allow for remote actions to be run on employee devices.

The main use cases for remote actions are on-demand data collection from devices, self-healing tasks and modifying configuration settings.

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

Refer to the [Remote actions group in Community](https://community.nexthink.com/s/group/0F92p000000kI80CAE) documentation for more information.

## Creating the script

### Generic scripts and input variables

Generic scripts are useful when a digitally signed script requires customization, as modifying a signed script breaks its signature. A generic script can be customized by parameters, keeping the signature intact.

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 takes 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.

{% hint style="info" %}
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 the script can convert to their expected type.
{% endhint %}

### Creating output variables

Executing a script may generate output that you want to store as on-demand data. 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 calls to write outputs in the script and lists the output variables in the Outputs section. Set the output's label 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:

| nxt write method                 | Constraints                                                                        |
| -------------------------------- | ---------------------------------------------------------------------------------- |
| nxt\_write\_output\_string       | 0 - 1024 characters (output truncated if bigger)                                   |
| nxt\_write\_output\_bool         | true / false                                                                       |
| nxt\_write\_output\_uint32       | <ul><li>Min: 0</li><li>Max: 4 294 967 295</li></ul>                                |
| nxt\_write\_output\_float        | <ul><li>Min: -3.4E+38</li><li>Max: 3.4E+38</li></ul>                               |
| nxt\_write\_output\_size         | <ul><li>Min: 0</li><li>Max: 3.4E+38</li></ul>                                      |
| nxt\_write\_output\_ratio        |                                                                                    |
| nxt\_write\_output\_bitrate      |                                                                                    |
| nxt\_write\_output\_duration     | <ul><li>Min: 0 ms</li><li>Max: 49 days</li><li>Precision in milliseconds</li></ul> |
| nxt\_write\_output\_date\_time   | DD.MM.YYYY\@HH:MM                                                                  |
| nxt\_write\_output\_string\_list | 0 - 1024 characters (output truncated if bigger)                                   |

### Implementing campaigns

Combine remote actions with campaigns to help employees solve issues independently. Campaigns let you inform employees about the detection of an issue and guide them through its resolution.

To display a campaign on the desktop of an employee who is interacting with a device:

* The campaign must have a **Remote action** trigger and be published.
* The script of the remote action can be executed either:
  * In the context of the employee, if the action does not need any special privileges.
  * In the context of the local system account, if the action needs administrative privileges.

### **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.

For more information on how to get the NQL ID or the UID of a campaign, refer to the [Triggering a campaign](/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/campaigns/managing-campaigns/triggering-campaigns.md) documentation.

### **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 a 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 the [Limiting the reception rate of campaigns](/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/campaigns/managing-campaigns/limiting-the-reception-rate-of-campaigns.md) documentation for more information.
* 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.

### Encoding the script

To write Bash scripts for remote actions:

* Encode the files that contain the script in UTF-8, without BOM.
* End each line in the code with the usual character in UNIX systems: `LF`.

Ensure proper encoding to avoid errors or nonfunctioning scripts.

## Code examples

<details>

<summary>Calling a campaign</summary>

In this example, the remote action executes a basic campaign call by its ID, outputting a status message if successful or an error message if unsuccessful.

```bash
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
```

</details>

<details>

<summary>Accessing the responses</summary>

In this example, the remote action calls for campaign answer data and outputs it as an array. Each answer is represented by its corresponding numbered option. Bash uses 0 as its lowest option, while Zsh uses 1.&#x20;

```bash
nxt_get_campaign_status status
echo "The response status is $status"
nxt_get_response_answer answersArray key1
echo ${answersArray[1]}
```

</details>

<details>

<summary>Running a campaign with a timeout</summary>

In this example, the remote action is set to run a campaign that times out and closes after a specified time, using seconds as input.

```bash
# 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
```

</details>

<details>

<summary>Running a non-blocking campaign</summary>

In this example, the remote action does not require user input and continues executing after triggering a campaign. The user can dismiss the campaign at any point. This is used mainly to provide users with information rather than to obtain data.

Refer to the [Conducting engaging campaigns](/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/campaigns/getting-started-with-campaigns/conducting-engaging-campaigns.md#conductingengagingcampaigns-determinecampaigngoals) documentation for more information.

```bash
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
```

</details>

## Signing the script

{% hint style="danger" %}
For security reasons, Nexthink requires Bash scripts for remote actions on macOS to be digitally signed with the `codesign` tool. Pack 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.
{% endhint %}

{% hint style="info" %}
Nexthink recommends signing all scripts in a production environment. Unsigned scripts should only be used in testing environments.
{% endhint %}

### Creating a certificate

* Launch Keychain Access on your Mac device.
* Go to Keychain Access > Certificate Assistant > **Create a Certificate…**

<figure><img src="/files/jLnYGVwWCjOHXkLDr44Q" alt="Keychain Access for Mac"><figcaption></figcaption></figure>

* Enter the name of your certificate.
* Choose **Code Signing** for the **Certificate Type**.
* For testing purposes, you can leave **Let me override defaults** unchecked.<br>

<figure><img src="/files/mIkM1YBc6ocnNKyxcTJo" alt="Certificate creation on Mac"><figcaption></figcaption></figure>

* Click **Create** and **Done**. The system has generated the certificate.

<figure><img src="/files/wjiiXCTsJZLl3cv3glsj" alt="Finishing the certificate creation process"><figcaption></figcaption></figure>

### Signing

Sign the remote action scripts using the standard macOS codesign utility.

```
codesign -s <your certificate identity> --timestamp --prefix=<code signature identifier prefix> --force <script file name>
```

Parameters:

```
-s <your certificate identity>
```

The identity of your code signing certificate is in the Keychain. Generally, it is a certificate subject common name or a certificate hash. Refer to the [codesign manual page](https://www.unix.com/man-page/osx/1/codesign/) documentation from UNIX for more information.

```
--timestamp
```

A trusted timestamp for a signature.

```
--prefix
```

A prefix to a code signature identifier. It attaches your company identity to an identifier and helps to make an identifier unique. See the code signature identifier generation rules on the [codesign manual page](https://www.unix.com/man-page/osx/1/codesign/) documentation from UNIX.

```
--force
```

This forces a code signature to be rewritten if it already exists.

### **Example**

Example of a test certificate for *example\_ra\_script.sh* remote action script:

```
codesign -s "RA scripts code signing certificate" --timestamp --prefix=com.my-organisation.remote-action.macos. --force example_ra_script.sh
```

The signature for the script file is generated in the file system extended attributes associated with the file. Use the codesign utility to get the code signature details and validate the signature:

<figure><img src="/files/ccw33PIhdOBYrcVhQKJR" alt="Example of signed script"><figcaption></figcaption></figure>

### Packaging

Package the remote action script with a .tar archive and .gzip compression. The extension ".tar.gz" is mandatory.

```
tar -czvf ./<your script name>.tar.gz ./<your script name>.sh
```

If the script file is signed, the tar utility will pack its extended attributes as well. This way, the system can transport the code signature and a script file.

### **Limitations**

* Only one script can be put into one archive.
* A script file should be placed in the root package folder; the `./myscript/myscript.sh` path is incorrect.
* A script must have the .sh extension.
* A script filename must be UTF-8 encoded, which is the default on macOS.

**Example**

Example of packaging the `test.sh` script:

```
tar -czvf ./example_ra_script.tar.gz ./example_ra_script.sh
```

The resulting `example_ra_script.tar.gz` is the remote action script file.

{% hint style="info" %}
Nexthink recommends using this script to simplify the signing and packaging process.
{% endhint %}

```
#!/bin/bash
#
# script_signing.sh
# 
# Copyright (C) 2023 by Nexthink S.A., Switzerland. Any usage, copy or partial copy of
# this code without the explicit agreement of Nexthink S.A. is prohibited and will be
# pursued to the full extend of the law.
#
# The arguments for the script:
# - input script filename
# - output archive filename
# - Certificate owner
# - Prefix
#
 
 
# Error handling
set -euo pipefail
trap "echo unrecoverable error !" ERR
 
 
# Check codesign
if [[ ! -x /usr/bin/codesign ]]
then
    echo "Error: this script requires that codesign is installed"
    exit 2
fi
 
# Check tar
if [[ ! -x /usr/bin/tar ]]
then
    echo "Error: this script requires that tar is installed"
    exit 2
fi
 
 
# Check arguments
if [[ $# -lt 4 ]]
then
    echo "Usage: script_signing.sh inputScriptFilename outputArchiveFilename CertificateOwner prefix"
    echo "Example: ./script_signing.sh script.sh script.tar.gz \"John Doe\" com.john.remote-action.macos."
    exit 1
fi
 
/usr/bin/codesign -s "$3" --timestamp --prefix="$4" --force "$1"
/usr/bin/tar czf "$2" "$1"
```

### Deploying the certificate to endpoints

If you have your code signing certificate in the Keychain and want to install its public version on endpoints, you need to export it first.

<figure><img src="/files/6uGZ2hgmnRBE3cfUNoCH" alt="Exporting the certificate"><figcaption></figcaption></figure>

* Choose the *Certificate (.cer)* file format for a public certificate in the pop-up window.

### Importing a certificate to the Keychain on endpoints

* Import your code-signed certificate into the System keychain to use remote action scripts with a *Trusted Publisher* execution policy.
* Double-click a .cer file and choose the **System** option in the **Keychain** drop-down menu.

<figure><img src="/files/dwPEBh5VMgWoFymxGG4q" alt="Importing a certificate"><figcaption></figcaption></figure>

* Enter the root password to import the certificate.

If the certificate is self-signed, it should also be trusted for code signing.

* Double-click the Keychain Access utility certificate and choose **Always trust** for the **Code Signing** option.

<figure><img src="/files/fI9F5g6A5EGJTKxIIMfk" alt="Trusting the certificate"><figcaption></figcaption></figure>

To automate these tasks, use the [security utility](https://www.unix.com/man-page/osx/1/security/) (external link) or your automation framework.

### Verify that the certificate was properly imported to an endpoint

* Copy and unpack your signed remote action script to the endpoint.

```
tar -xzvf example_ra_script.tar.gz
```

* Verify your signature.

```
codesign -vvvv -R="certificate leaf trusted" example_ra_script.sh
```

If the signature is properly imported, you should see the following output:

<figure><img src="/files/d7Z3QRuO7npqJEnHvV1S" alt="Verifying the import"><figcaption></figcaption></figure>

## Maintaining the script

### Comparison and validation

Before deploying a remote action script, it is possible to compare it with other scripts prepared by Nexthink. This step is optional but recommended if it is your first time preparing a script.

1. In the Nexthink Library, select **Content**.
2. Filter by **Remote action**.
3. Navigate to the **Remote Actions** management page.
4. Select any remote action script installed directly from the Nexthink Library that matches the target operating system.
5. Export the script and compare its syntax with your script’s.

### Script termination and timeout

When launching 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](https://en.wikipedia.org/wiki/Shebang_\(Unix\)) (external link).

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

{% hint style="info" %}
Nexthink recommends always using a *shebang* in shell scripts and sticking to the standard interpreters.
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.nexthink.com/platform/~/changes/Sh4xqs4GDClkDKT9Hvux/user-guide/remote-actions/managing-remote-actions/writing-scripts-for-remote-actions-on-mac.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.