Scripting

For more about script files themselves see Device Scripting

Upload File

You can upload files to be run as script against your devices. Scripts can have arguments which you can pass.

You must be the account owner or if you belong to an organization have administrator priviledges on the account to upload a file.

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.

Details

Example of File Upload is part of the Insomnia Collection and Postman Collection under Scripting

• Endpoint: /file/upload

• Method: POST

• This is not a graphQL mutation. It is REST

• Form Parameters:

  • file: The file or script name to be uploaded, designated with its file path.

  • shortDesc - Short description for the Script File (optional)

  • longDesc - Long description for Script File (optional)

  • selections: A JSON array which defines selection criteria and options.

Uploading a file of the same name as an existing file will create a new version of the file.

Arguments

Arguments can be of three types:

• FileSelect: A previously uploaded file

• StringSelect: A preset collection of strings

• StringEntry: User entered string

Arguments are passed as a list to the form entry called 'arguments'. Each list item contains the following:

• name - a reference for this argument

• type - (FileSelect, StringSelect or StringEntry)

• options -

  • For FileSelect this will limit the files shown by the strings given

  • For StringSelect this will be the list of strings that can be chosen

  • For StringEntry no options are required

Get List of Script Files

Return a list of scripts that have been uploaded to your account. Additionally, if you add the context of an account (organization) where you have manage with scripting capabilities or admin role.

Query

query GetFiles {
login {
# Add the following line if you need to do this in Org context.
# The ID is the Org ID
  #account(id:"XXXXXX-XXXX-XXXXXX-XXXXX") {
  files {
    owner {
      email
      id
    }
    id
    name 
    shortDesc
    longDesc
    created
    updated
    versions {
      total
      hasMore
      items{
      id
      created
      version
      arguments {
        name
        order
        options
        argumentType
      }
      }
    }
  }
  #} end of org context
}
}

Response

{
"data": {
  "login": {
      "files": [
        {
          "owner": {
            "email": "[e-mail]",
            "id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXX"
          },
          "id": "881189d3-59b8-48d7-84fe-3199bdfbc40a",
          "name": "new_script_example.sh",
          "created": "2024-01-11T00:11:50.388Z",
          "updated": "2024-01-11T06:03:26.000Z",
          "versions": {
            "total": 7,
            "hasMore": false,
            "items": [
            {
              "id": "bf0273c8-9077-408e-9560-975a504a47b2",
              "created": "2024-01-11T00:11:50.639Z",
              "version": 1
            },
            {
              "id": "50e0c466-8312-455e-9ebd-1f5afd7aa733",
              "created": "2024-01-11T05:40:06.679Z",
              "version": 2
            },
            {
              "id": "16dbff8b-596d-4785-9908-659bb10e7987",
              "created": "2024-01-11T05:44:28.539Z",
              "version": 3
            },
            {
              "id": "28e8647a-a2c7-4bd9-8f8a-130db01fa7e4",
              "created": "2024-01-11T05:49:09.608Z",
              "version": 4
            },
            {
              "id": "d3449672-74e6-4745-8c25-2ffd79e6be36",
              "created": "2024-01-11T05:57:45.977Z",
              "version": 5
            },
            {
              "id": "3d94ad75-35a0-4af8-b0fa-5cbdfbfaaa77",
              "created": "2024-01-11T05:58:08.464Z",
              "version": 6
            },
            {
              "id": "50046b34-186c-47ee-a171-968f43ef2d96",
              "created": "2024-01-11T06:03:25.730Z",
              "version": 7
            }
          ]
          }
        },
        {
          "owner": {
            "email": "[e-mail]",
            "id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXX"
          },
          "id": "f12d6bf2-0f6d-4bf6-95be-cd045b2471c2",
          "name": "test_upload.txt",
          "created": "2024-01-11T00:06:25.781Z",
          "updated": "2024-01-11T00:06:26.000Z",
          "versions": {
            "total": 1,
            "hasMore": false,
            "items": [
            {
              "id": "3f5f04d4-23f4-4cd8-a9ba-70814952dff7",
              "created": "2024-01-11T00:06:26.074Z",
              "version": 1
            }
            ]
          }
        }
      ]
    }
  }
}

File Attributes

Attributes	Data Type	Description
id	Int	The primary key of the file
name	String	The given short name for a file
shortDesc	String	Optional short description for the file
longDesc	String	Optional long description for the file. Can be used to provide further information to your team.
owner	User	User who owns the file. id and email are available as attributes of a User.
created	Date	DateTime of the File creation in ISO 8601 format Date String
updated	Date	DateTime of the File last updated in ISO 8601 format Date String
versions	Paginated FileVersions	See Pagination

File Version Attributes

Files of the same name create versions.

Attributes	Data Type	Description
id	Int	The primary key of the file version.
version	int	The Version number
created	Date	DateTime of the Version creation in ISO 8601 format Date String
arguments	[FileArgument]	The list of arguments that are required to run the script.

Version Filtering Arguments

Filter Attribute	Data Type	Description
sort	String	sortable attributes - ids, created. prepend attribute with - for sorting descending
from	Int	Index of results to start from given the applied filters
after	String	Version ID for to return results from.
size	Int	Size of the results to return. Max of 100
id	String	Filter on the given version ID
ids	Strings	Filter to return the given versions
latest	Boolean	return the latest version
maxDate	DateTime	ISO 8601 format date string - Return versions created before the given DateTime
minDate	DateTime	ISO 8601 format date string - Return versions created after the given DateTime

File Argument Attributes

Attributes	Data Type	Description
name	string	Named used to reference the argument
desc	string	The string used when selecting a value for the argument.
order	int	The order the options will be placed
options	[string]	The list of options given to the user to choose
argumentType	FileArgumentType	The type of argument (FileSelect, StringSelect or StringEntry)

Download File

You must be the account owner or if you belong to an organization, the owner, an admin or a user with Manage role with scripting permission.

Use the base graphQL url + /file/download/{fileVersionId}

Delete File

You must be the account owner or if you belong to an organization, an admin on the account to delete a file.

Mutation

mutation deleteFile {
  deleteFile(fileId: "881189d3-59b8-48d7-84fe-3199bdfbc40a")
}

Response

{
  "data": {
     "deleteFile": true
  }
}

Delete File Version

You must be the account owner or if you belong to an organization, an admin on the organization to delete a file version.

Mutation

mutation deleteFileVersion {
  deleteFileVersion(fileVersionId: "d3449672-74e6-4745-8c25-2ffd79e6be36")
}

Response

{
  "data": {
    "deleteFileVersion": true
  }
}

Create a Job (Run a Script)

Owners of the devices or managers or admins which have access to the selected devices can run a script. For example, if a user has a role which only allows them manage capabilities on devices tagged with "support". If there are any devices which are not valid for the user, then the entire job is rejected.

Script jobs should not be sent to more than 50 devices at a time. Job execution is sent to all devices by separate processes at nearly the same time. The Remote.It server wil attempt to send a job to a given device 26 times with an exponential backoff that will end after 1.5 days. This will allow for a device that might be offline temporarily to still receive a script job.

Mutation

When you have file versions, you can pass the file version ID in the "fileId" field to specify the version. See Creating Scripts section for more on authoring the scripts themselves.

mutation execute {
  startJob(
    #fileId or fileVersionId are required. If both are passed, the fileVersionId is used.
    fileId: "881189d3-59b8-48d7-84fe-3199bdfbc40a",
    #fileVersionId: "3f5f04d4-23f4-4cd8-a9ba-70814952dff7",
    #Device IDs OR Tags are used to identify the devices for the job. If both device IDs and tags are passed, device Ids will be used.
    deviceIds: ["80:00:00:00:01:22:37:AE"],
    #optional device tags (can be used to run a group of scripts against a set of devices with these tags at time of execution)
    #ANY/ALL (i.e. or/and), when tags are used, operator should accompany
    tagFilter: {operator: ANY, values:["reboot"]},
    arguments: [
      {
        name: "url"
        value: "https://remote.it"
      },
      {
        name: "imageFile"
        value: "3f5f04d4-23f4-4cd8-a9ba-70814952dff7"
      },
      {
        name: "bookmarkName"
        value: "RemoteIt"
      },
      {
        name: "action"
        value: "Add"
      }
    ]
  )
}

Response

Success will result in a job ID. If there are any devices which are not valid for the user, then the entire job is rejected. A job will also be rejected if a script is not valid for the account.

{
  "data": {
    "startJob": "57592ee3-ed89-4265-89af-337c8fb8d36d"
  }
}

Job Parameters

Parameter	Data Type	Description
fileId	String	Primary key of Script file to be executed (either fileID or fileVersionID are required, if both are present, then fileVersionId is used)
fileVersionId	String	Primary of version ID of the file to be executed. (either fileID or fileVersionID are required, if both are present, then fileVersionId is used)
deviceIds	Array of Device IDs	Device Ids for job to execute script against. If both tags and deviceIds are given in mutation, deviceIds will be used. (required if not using fileTags)
tagFilter	Tag Filter Arguments	Tags and operator for job execution parameters. If both tags and deviceIds are given in mutation, deviceIds will be used. (required if not using deviceIds)
arguments	Array of argument	ArgumentType (Optional) - Only supported in the API and not in app.remote.it or the Desktop application.

TagFilter

Attribute	Data Type	Description
operator	TagOperatorEnum	ANY,ALL (or/and) (optional, if not using fileTags)
values	Array of tag names (Strings)	Devices with tags at time of job creation will be selected for job execution

Job Arguments (only in API)

Attribute	Data Type	Description
name	String	Name of argument used in script
value	String	User selected argument value, could be arbitrary string or file id depending or argument type used in script

Cancel Job (Run)

Owners of the devices or managers or admins which have access to the selected devices can run a script. Cancel Job requires the job ID and will cancel the job that is in progress but cannot revert any scripts that have already executed. Any currently executing script will no longer update the Remote.It backend for updating attributes or legacy task notifier, but the script will finish running. Any scripts not yet received by devices will be cancelled.

Mutation

mutation cancelJob {
  cancelJob(jobId: "41fc0cec-4efd-40ef-8e48-1aa109019f1c")
}

Response

{
  "data": {
     "cancelJob": true
   }
}

View Jobs (Runs) and Device Status

Get a list of Jobs and their devices' status. Optionally you can filter by passing an array of jobIDs, array of statuses. Examples of Pagination.

Query

query GetJobs {
   login {
     # Add the following line if you need to do this in Org context.
     # The ID is the Org ID
     #account(id:"XXXXXX-XXXX-XXXXXX-XXXXX") {
     #see documentation on paginated responses for iteration
     #examples of filtering below
      jobs(ids: ["41fc0cec-4efd-40ef-8e48-1aa109019f1c","41fc0cec-4efd-40ef-8e48-xxxxx"], statuses:[FAILED,WAITING,RUNNING,SUCCESS,CANCELLED],size: 1000)
      {
	  hasMore
          total
          last
          items {
	     id
             owner {
          	email
             }
	     user {
	   	email
	     }
	     created
	     updated
             # One of the following FAILED,WAITING,RUNNING,SUCCESS,CANCELLED
             status
             #tags associated with job
             tags {
	       name
             }
             #ANY/ALL (i.e. or/and)
             tagOperator,
             fileVersion {
   		id
                file {
                   name
 	        }
             }
             jobDevices {
    		id
    		device {
                   id
    		}
		#attributes associated with the job.
		attributes {
			 created
			 id
			 key
			 value
		}
	   	#one of the following: FAILED,WAITING,RUNNING,SUCCESS,CANCELLED
	   	status
	      }
	      arguments {
		  id
		  fileArgument {
		   id
		   name
		   desc
		   order
		   options
		   argumentType
		   created
		  }
		  name
		  desc
		  order
	          argumentType
	          value		
              }
          }
       }
    }
}

Response:

{
  "data": {
    "login": {
      "account": {
        "jobs": 
           {
	     "hasMore": false,
	     "total": 1,
	     "last": "57592ee3-ed89-4265-89af-337c8fb8d36d",
	"items": [
          {
            "id": "57592ee3-ed89-4265-89af-337c8fb8d36d",
            "owner": {
              "email": "[e-mail]"
            },
            "user": {
              "email": "[e-mail]"
            },
            "created": "2024-01-13T01:34:38.358Z",
            "updated": "2024-01-13T01:34:57.000Z",
            "status": "SUCCESS",
            "tags": [{"name":"reboot"}],
            "tagOperator":"ANY",
            "fileVersion": {
              "id": "50046b34-186c-47ee-a171-968f43ef2d96",
              "file": {
                "name": "new_script_example.sh"
              }
            },
            "jobDevices": [
              {
                "id": "e88583b3-dac4-44f3-8c17-43f4fd22174f",
                "device": {
                  "id": "80:00:00:00:01:22:37:AE"
                },
                "status": "SUCCESS"
                "attributes": [
                {
                  "created": "2024-01-13T01:34:38.358Z"
                  "id": "XXXX-XXX-XXX-XXX",
                  "name": "category1",
                  "value": "pi reboot"
                }
                ]
              }
            ],
            "arguments": [
              {
                "id": "25e905cf-e649-42f2-92d8-2df637893b15",
                "fileArgument": {
                  "id": "2c1ff728-a6fb-4d8d-9c44-3e952b40f4fb",
                  "name": "action",
                  "desc": "Choose Action",
                  "order": 4,
                  "options": [
                    "Add",
                    "Remove"
                  ],
                  "type": "StringSelect",
                  "created": "2024-01-11T06:03:26.264Z"
                },
                "name": "action",
                "desc": "Choose Action",
                "order": 4,
                "argumentType": "String",
                "value": "Add"
              },
              {
                "id": "42e83021-a5f2-4770-ae31-0c7a981a71cc",
                "fileArgument": {
                  "id": "55968a9c-edc6-4fb4-a233-431bdeeb07e9",
                  "name": "fileName",
                  "desc": "Select File",
                  "order": 1,
                  "options": [
                    ".png"
                  ],
                  "argumentType": "FileSelect",
                  "created": "2024-01-11T06:03:25.803Z"
                },
                "name": "fileName",
                "desc": "Select File",
                "order": 1,
                "argumentType": "File",
                "value": "3f5f04d4-23f4-4cd8-a9ba-70814952dff7"
              },
              {
                "id": "5a42272b-6402-457b-9350-4d9a8d8ac9dc",
                "fileArgument": {
                  "id": "3ae9b823-0c60-4f2c-a8d6-84ae287cb3d9",
                  "name": "bookmarkName",
                  "desc": "Enter Name For Bookmark",
                  "order": 3,
                  "options": [],
                  "argumentType": "StringEntry",
                  "created": "2024-01-11T06:03:26.055Z"
                },
                "name": "bookmarkName",
                "desc": "Enter Name For Bookmark",
                "order": 3,
                "argumentType": "String",
                "value": "RemoteIt"
              },
              {
                "id": "d6fdfd65-3083-4546-a30b-f7416e729a2c",
                "fileArgument": {
                  "id": "96bde6a5-f252-4b17-9d41-1ac0c044e895",
                  "name": "url",
                  "desc": "Enter Fully-Qualified URL",
                  "order": 2,
                  "options": [],
                  "argumentType": "StringEntry",
                  "created": "2024-01-11T06:03:25.898Z"
                },
                "name": "url",
                "desc": "Enter Fully-Qualified URL",
                "order": 2,
                "argumentType": "String",
                "value": "https://remote.it"
              }
            ]
          }
        ]
      }
    }
  }
}

Job Attributes

Attributes	Data Type	Description
id	String	Id of the job
owner	User	User who owns the job/devices
user	User	User who ran the job
created	Date	DateTime created in ISO 8601 format Date String
updated	Date	DateTime updated in ISO 8601 format Date String
status	JobStatusEnum	FAILED,WAITING,RUNNING,SUCCESS,CANCELLED
tags	Array of TagObjects	tags being used for identification of devices. If any. name is the only attribute at this time.
tagOperator	TagOperatorEnum	ANY,ALL (Or/And)
fileVersion	FileVersion	the file version that was used to run the script
jobDevices	[JobDevice]	A list of job devices with status
arguments	[JobArgument]	List of job Arguments

Job Device Attributes

Attributes	Data Type	Description
id	String	The primary key of the Job Device.
device	Device	Remote.it Device
status	JobStatusEnum	WAITING, RUNNING, FAILED, SUCCESS, CANCELLED
created	Date	DateTime of the Device was created in ISO 8601 format Date String
updated	Date	DateTime of the Device was last updated in ISO 8601 format Date String
attributes	Array of Device Attributes applied to device	Device Attributes

Job Argument Attributes

Attributes	Data Type	Description
name	string	Named used to reference the argument
desc	string	The string used when selecting a value for the argument.
order	int	The order the options will be placed
argumentType	JobArgumentType	The type of argument (File or String)
value	string	Value selected for this job
fileArgument	FileArgument	The FileArgument this J obArgument is based on

Device Attributes

Attribute	Data Type	Description
created	Date	DateTime of the Attributes creation in ISO 8601 format Date String
id	String	The primary key of the Job Device.
name	String	Name of the attribute
value	String	Value of the attribute

Pagination

The list responses from the versions and jobs queries return paginated results. We implement a pagination model with from/after and size pagination arguments. Responses can return hasMore, last and total . If the hasMore response returns true, this indicates do another fetch. For example if your size is 100 and hasMore returns true, the from will increment to 101 to fetch the next set. You could also determine this by iteration until you get to the total. Size is limited to 1000 max in each return.