System commands are used to automate Crunch.io operations outside of datasets. Unlike dataset scripts, system commands do not act inside datasets. There are currently two families of system commands:
- Folder scripts — executed inside a given folder: anything you refer to must be in that folder or one of its subfolders.
- User scripts — executed at the account level and require admin permissions.
API
Project-level scripts
To execute a command, POST the script contents to the folder’s /execute/ endpoint:
POST /api/projects/<project_id>/execute/
{
Element: shoji:view,
Value: """script contents"""
}
Or, as a plain text request:
POST /api/projects/<project_id>/execute/
Content-type: text/plain
Script contents ….
If successful, a 204 response is returned.
Account-level scripts
To execute a command at the account level, POST the script contents to the account’s /execute/ endpoint:
POST /api/account/execute/
{
Element: shoji:view,
Value: """script contents"""
}
Or, as a plain text request:
POST /api/account/execute/
Content-type: text/plain
Script contents ….
If successful, a 204 response is returned.
Concepts
Current folder
System commands are always executed on a folder, which acts as the context for all the commands inside the script. Any mention to a dataset or a folder always means that it is in the current folder or a subfolder.
Dataset functions
Dataset functions allow you to select datasets based on its attributes, including:
- DATASET("path") — Selects a dataset by its path relative to the current folder.
- Example: DATASET("Client1|Published|My Dataset")
- DATASET_ID("id") — Takes a known Dataset ID anywhere under the tree of the current folder and returns that specific dataset.
- Example: DATASET_ID("abcdefghijklmnop")
Folder paths
Folder paths indicate a folder hierarchy and are separated by the pipe (|)character.
An example structure:
If A → B → C then the folder path would be A|B|C.
If the script is being executed in folder A and you wish to refer to folder C, then the path to use is B|C since B is the first child of A that is mentioned.
If the script is executed from B and you wish to refer to C, then the path is C as there is no need to descend to more levels since C is a direct child of B.
Dataset Paths
For the DATASET() function, the argument is a "Dataset path", which is very similar to a folder path but the last part must refer to a dataset name.
For example, the folders A → B → C and the dataset "DS1" exists under B and the dataset "S2" exists under C.
If the script is executed on folder A and you then wish to refer to DS1, the path is DATASET("B|DS1"); to refer to DS2, the path is DATASET("B|C|DS2").