Web API for Scripts: Difference between revisions
| (6 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
Scripts API is used to start and stop script runs and get the current or last completed script run log. | Scripts API is used to start and stop script runs and get the current or last completed script run log. | ||
Note that the [[Web API for Workspace Elements|Workspace Elements API]] supports also scripts. | |||
==Script Entity== | ==Script Entity== | ||
| Line 8: | Line 10: | ||
* Description (string): Script description. | * Description (string): Script description. | ||
* Code (string): Script code. | * Code (string): Script code. | ||
* Language (string): Scripting language, either ''Expression'' or ''SQL''. | |||
==Methods== | ==Methods== | ||
| Line 28: | Line 31: | ||
=== Get current run log === | === Get current run log === | ||
<pre> | <pre> | ||
GET api/scripts/runlog/current/{scriptId} | GET api/scripts/runlog/current/{scriptId}?startFromPosition=<number> | ||
</pre> | </pre> | ||
Gets the current run log for script with given id, i.e. a run that is currently in progress. Returns | Gets the current run log for script with given id, i.e. a run that is currently in progress. Returns an object with the following fields: log, additionalData, operationId. Returns null if the script is not running. Requires the global RunScript permission. Returns NotFound if a script does not exist, or Forbidden if current user has no access to the script. | ||
There is an optional parameter '''startFromPosition''' which skips the beginning of the log and returns the tail of the log starting from that defined position as number of characters. This parameter is useful to get the tail of the log, for example when the start of the log has already been fetched earlier. Position zero is the start of the log. | |||
=== Get last run log === | === Get last run log === | ||
| Line 38: | Line 43: | ||
</pre> | </pre> | ||
Gets the last completed run log for script with given id. Returns | Gets the last completed run log for script with given id. Returns an object with the following fields: log, additionalData, operationId. Returns null if the script is has never been run yet. Requires the global RunScript permission. Returns NotFound if a script does not exist, or Forbidden if current user has no access to the script. | ||
=== Create script === | === Create script === | ||
| Line 45: | Line 50: | ||
</pre> | </pre> | ||
Creates a new script. Takes the script | Creates a new script. Takes the script entity in the body (id is ignored if specified). Returns the created script id. Returns ''Forbidden'' if script cannot be created due to lack of permissions. | ||
=== Edit script === | === Edit script === | ||
| Line 52: | Line 57: | ||
</pre> | </pre> | ||
Updates an existing script. Takes the script | Updates an existing script properties. Takes the script entity in the body. The Id property is mandatory, as the script is identified using it. Returns ''NotFound'' error if script does not exist. Returns ''Forbidden'' if script cannot be modified due to lack of permissions. | ||
=== Delete script === | === Delete script === | ||
| Line 59: | Line 64: | ||
</pre> | </pre> | ||
Deletes a script with given id. Returns NotFound error if script does not exist. Returns ''Forbidden'' if script cannot be deleted. | Deletes a script with given id. Returns NotFound error if script does not exist. Returns ''Forbidden'' if script cannot be deleted due to lack of permissions. | ||
[[Category: QPR ProcessAnalyzer]] | [[Category: QPR ProcessAnalyzer]] | ||
Latest revision as of 16:17, 8 September 2021
Scripts API is used to start and stop script runs and get the current or last completed script run log.
Note that the Workspace Elements API supports also scripts.
Script Entity
The scripts API is based on the script entity, which has the following properties:
- Id (integer): Script id.
- ProjectId (integer): project id. Empty if script belongs to system level.
- Name (string): Script name.
- Description (string): Script description.
- Code (string): Script code.
- Language (string): Scripting language, either Expression or SQL.
Methods
The scripts API has the following methods.
Start script run
POST api/scripts/run/{scriptId}
Starts to run script with given id. Returns id of the started script run operation. Returns immediately without waiting for a script run to be finished. Returns 0 if the script is already running. Requires the global RunScript permission. Returns NotFound if a script does not exist, or Forbidden if current user has no access to the script.
End script run
POST api/scripts/end/{scriptId}
Terminates run of script with given id. Returns id of the terminated script run operation. Returns immediately without waiting for a script run to be aborted. Returns 0 if the script is not running. Requires the global RunScript permission. Returns NotFound if a script does not exist, or Forbidden if current user has no access to the script.
Get current run log
GET api/scripts/runlog/current/{scriptId}?startFromPosition=<number>
Gets the current run log for script with given id, i.e. a run that is currently in progress. Returns an object with the following fields: log, additionalData, operationId. Returns null if the script is not running. Requires the global RunScript permission. Returns NotFound if a script does not exist, or Forbidden if current user has no access to the script.
There is an optional parameter startFromPosition which skips the beginning of the log and returns the tail of the log starting from that defined position as number of characters. This parameter is useful to get the tail of the log, for example when the start of the log has already been fetched earlier. Position zero is the start of the log.
Get last run log
GET api/scripts/runlog/last/{scriptId}
Gets the last completed run log for script with given id. Returns an object with the following fields: log, additionalData, operationId. Returns null if the script is has never been run yet. Requires the global RunScript permission. Returns NotFound if a script does not exist, or Forbidden if current user has no access to the script.
Create script
POST api/scripts
Creates a new script. Takes the script entity in the body (id is ignored if specified). Returns the created script id. Returns Forbidden if script cannot be created due to lack of permissions.
Edit script
PUT api/scripts
Updates an existing script properties. Takes the script entity in the body. The Id property is mandatory, as the script is identified using it. Returns NotFound error if script does not exist. Returns Forbidden if script cannot be modified due to lack of permissions.
Delete script
DELETE api/scripts/{id}
Deletes a script with given id. Returns NotFound error if script does not exist. Returns Forbidden if script cannot be deleted due to lack of permissions.