Device Scripting

Overview

Scripting is a feature that allows you to run a script unattended (written in any interpreted language you have installed on your Operating System) on any number of devices with a Linux or Windows based operating system.

This is useful when you have a repetitive action that you would like to perform on one or more devices.

These examples are for graphQL API scripting and do not apply to legacy.app.remote.it UI scripting. legacy.app.remote.it is deprecated and you should use this method.

Creating Scripts

Remote.It allows you to write scripts in any language your host operating system supports because the script is run just like any other executable script on your machine. This means you can write in bash, Python, Ruby, Node, etc., assuming you have the interpreter installed on your system. Scripts are executed as root.

Hello world script returning a value to Remote.It:

#!/bin/bash

Attribute() {
    ATTRIBUTE_NAME="$1"
    ATTRIBUTE_VALUE="$2"

    # Send the data to the API, including jobDeviceId and attributeName in the URL
    curl -X POST "https://${GRAPHQL_API_PATH}/job/attribute/$JOB_DEVICE_ID/$ATTRIBUTE_NAME" \
         -H "Content-Type: text/plain" \
         --data "$ATTRIBUTE_VALUE"
}

Attribute hello "world"
Attribute hostname "$(hostname)"

More example shell scripts can be found at our github repository:

https://link.remote.it/github/scripts

Files must be able to be uploaded in 30 seconds. If you need to have larger files, consider hosting at another location such as S3 and having your script fetch them.

Scripts can also have arguments which you can pass. Arguments can be created by placing commented lines like this in your code:

# The following defines arguments for selecting a file, entering a string or selecting from a list of strings:
# These arguments are optional and can be removed if not needed.
# Once defined their values can be accessed  via their name in the script (e.g., $textFile, $url, $name, $action)
# <arguments>, <type>, <name>, <prompt>, <option1>, <option2>, ... 
# r3_argument, FileSelect, textFile, Select File, .txt
# r3_argument, StringEntry, url, Enter Fully-Qualified URL
# r3_argument, StringEntry, name, Enter a Name
# r3_argument, StringSelect, action, Choose Action, ADD, REMOVE

These arguments can then be used as environment variables in you code. See script examples for usage.

API

Below is a quick reference and not all functions are listed here. For full documentation, including working with scripting in an organization, please see Scripting API. You can also download and use our examples for Insomnia and Postman.

Uploading a Script

You can upload files using a multi form post to be run as a script or a file to be used by your scripts. Setting the executable flag will determine if the file can be run as a script (see scripting API docs).

curl --request POST \
  --url https://api.remote.it/graphql/v1/file/upload \
  --header 'Authorization: ' \
  --header 'Content-Type: multipart/form-data' \
  --header 'Date: Thu, 23 May 2024 00:32:27 GMT' \
  --header 'Host: api.remote.it' \
  --header 'User-Agent: insomnia/8.5.1' \
  --form file=@/Users/ebowers/Documents/remoteit/scripting/final/script_example_no_args.sh \
  --form executable=true \
  --form 'shortDesc=New Script Example No Args' \
  --form 'longDesc=This is a new script that has no args as an example'

You must be the account owner or if you belong to an organization, an admin on the account to upload a file. For full documentation, please see Scripting API.

Files must be able to be uploaded in 30 seconds. If you need to have larger files, consider hosting at another location such as S3 and having your script fetch them.

Running a Script

You can run your recent uploaded script with a graphQL mutation. This is a quick reference. For full documentation, please see Scripting API.

View files

query GetFiles {
  login {
    account {
      id
      files {
        id
        name
        shortDesc
        longDesc
        lastVersion {
          id
          version
        }
        executable
      }
    }
  }
}

Run Script without arguments

mutation execute {
  startJob(
    deviceIds: ["80:00:00:00:01:22:37:AE"]
    fileId: "b0fd8a0f-2850-4be3-88cd-b554551e4dd4"
  )
}

Run Script with arguments

This is a quick reference. For full documentation, please see Scripting API.

mutation execute {
  startJob(
    deviceIds: ["80:00:00:00:XX:XX:XX:XX"]
    fileId: "5539cee9-3bea-4c04-add6-bd7c2aff12df"
    arguments: [
      { name: "url", value: "https://remote.it" }
      { name: "textFile", value: "6b69b085-5507-468f-93c2-d64cdd40eb8e" }
      { name: "name", value: "RemoteIt" }
      { name: "action", value: "Add" }
    ]
  )
}

Get Script/Job Status

You can query for scripts status using the API. Attributes and Status set during the script will appear in the attribute list for the job. Filtering and sorting is available. This is a quick reference. For full documentation, please see Scripting API.

query GetJobs {
  login {
    jobs {
      hasMore
      total
      items {
        id
        created
        status
        fileVersion {
          id
          file {
            id
            name
          }
        }
        jobDevices {
          id
          device {
            id
            name
          }
          attributes {
            key
            value
          }
          status
        }
      }
    }
  }
}