New to Slingshot?
If you're new to Slingshot we recommend reading our Slingshot Introduction blog post and checking out the Slingshot Tutorial in our KB before proceeding.
API vs Task Editor GUI
You have two ways to interact with Slingshot's capabilities: the API and the Task Editor GUI.
In general, the GUI is better for easily pointing and clicking your way through a series of actions/tasks that you want to occur repetitively, on a schedule, for certain file patterns in watched folders. Whereas, the API can be used to do actions on-demand, for any files, whether they're in a watched folder or not. For the purpose of this article the table below illustrates the differences between the two methods:
| API | GUI Editor | |
| Ease of use | ✓ | |
| Watched folders | Not required | Required |
| Timing | Better for on-demand operations | Better for scheduled, repetitive operations |
| Deeper control of tasks | ✓ |
Automations, explained
Complex tasks that need to happen in sequence can be pre-defined using Automations. This can include using wildcards and regular expressions to handle multiple files. Although an Automation (i.e. a series of tasks in Slingshot) can certainly be created using just the API, it's much easier to create an Automation through the Task Editor GUI.
But! What if you want the automation to occur on-demand, instead of on a predefined frequency? The answer: Use the API to trigger your Automation. As you will see below, it is very easy to construct an API command that triggers an automation.
Once an Automation is configured (either through the GUI or the API) there are multiple ways to initiate it.
An Automation schedule is made up of a start time and repeat frequency. Once the server time reaches the start time the Automation will run once. If the start time is in the past the automation will be repeated at whatever rate is defined as the "frequency."
This method of scheduling works best for tasks that need to be repeated regularly. Tasks that happen infrequently or cannot be predicted may benefit from being triggered on-demand.
If an automation does not need to run on a schedule, we can tell it to start at some point in the past and give it a repeat frequency of a very large number. For example, you could set the repeat frequency to 175200 hours (20 years!) and be fairly confident that the automation will not run any time soon.
Another method of preventing the Automation from running is to pause it by clicking on the "State" in the Automations list and selecting "Pause." The Pause status will prevent an automation from running — even if it is triggered using the run command in the example below.
Triggering an Automation from the API
The following command should be issued as one line:
curl -u user:password -X POST --header 'Content-Type: application/json' --header 'Accept: text/plain' 'http://192.168.51.8/v1/automation/1?cmd=run'
| RESPONSE BODY |
|
EMPTY Upon submitting the command Slingshot will return only an http response code of "200" if it is accepted. The response body will be empty unless an error has occurred. |
?cmd={command}
This single-line command enables complete control over an Automation's schedule and state. With it we can trigger an active Automation immediately (in the example above we're triggering automation with the ID of '1') or prevent a scheduled Automation from running. The "run" command can be used by itself to trigger any Automation that is in the "waiting" state. That includes an automation that has been scheduled but is not currently active.
Available commands:
- "run"
- Trigger the specified automation to run now if active
- "pause"
- Put the Automation into a paused state: instances will not be started on schedule or repeat frequency
- A paused Automation will still accept a "run" command, but will wait until being resumed before beginning
- "resume"
- Automation becomes active
- If no "run" commands are pending the Automation will enter the "waiting" state
- If "run" commands are pending the Automation will run now
- "cancel"
- Automation will disregard any pending "run" commands
- Cancelled tasks will appear in logs (Instances list) once Automation is resumed
- "clear"
- Remove cancelled tasks from Instances list
| - u user:password |
Slingshot currently uses http authentication. For the curl command to succeed the -u flag is used to pass authorized EVO user to the API. Any valid EVO username can be used, however it is best practice to have a single user specifically for Slingshot.
|
| EVO Address |
Outside of the information being passed to Slingshot, the EVO IP or Domain Name must be defined as part of the curl command.
|
| automation/1 |
automation/{automation ID} The unique Automation ID must be specified; it can be found in the GUI on the Automations page. The Automation will be shown in the drop-down information view. Click the arrow next to the Automation in question to expand the drop down information.
|