HomeSupportCommunity

Scripting

For more about script files themselves see Device Scripting

Upload File

You can upload files to be run as script or files to be used by your scripts. Setting the executable flag will determine if the file can be run as a script. Scripts can have arguments which you can pass.

You must be the account owner or if you belong to an organization, an admin 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.

    • executable: A boolean flag to set the file as executable.

    • 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 Files

Return a list of files 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
    executable
    created
    updated
    versions {
      total
      hasMore
      items{
      id
      created
      version
      arguments {
        name
        order
        options
        argumentType
      }
      }
    }
  }
  #} end of org context
}
}

Response

{
"data": {
  "login": {
      "files": [
        {
          "owner": {
            "email": "support@remote.it",
            "id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXX"
          },
          "id": "881189d3-59b8-48d7-84fe-3199bdfbc40a",
          "name": "new_script_example.sh",
          "executable": true,
          "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": "support@remote.it",
            "id": "XXXXXXX-XXXX-XXXX-XXXX-XXXXXXX"
          },
          "id": "f12d6bf2-0f6d-4bf6-95be-cd045b2471c2",
          "name": "test_upload.txt",
          "executable": true,
          "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

AttributesData TypeDescription

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

executable

Boolean

Can the file can be run as a script?

versions

Paginated FileVersions

See Pagination

File Version Attributes

Files of the same name create versions.

AttributesData TypeDescription

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 AttributeData TypeDescription

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

AttributesData TypeDescription

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

ParameterData TypeDescription

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)

TagFilter

AttributeData TypeDescription

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

AttributeData TypeDescription

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

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 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": "support@remote.it"
            },
            "user": {
              "email": "support@remote.it"
            },
            "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

AttributesData TypeDescription

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

AttributesData TypeDescription

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

AttributesData TypeDescription

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

AttributeData TypeDescription

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.

PreviousCustom AttributesNextCLI Usage

Last updated