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.
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
queryGetFiles {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}}
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.
mutationexecute { 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.
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.
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
queryGetJobs { 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 } } } }}
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.
DateTime of the Version creation in ISO 8601 format Date String
arguments
[FileArgument]
The list of arguments that are required to run the script.
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
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)
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)
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
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
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
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
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
created
Date
DateTime of the Attributes creation in ISO 8601 format Date String
