Skip to end of banner
Go to start of banner

Common REST service

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 12 Next »

Contents

Availability

Available starting with SIL Engine™ 2.5.5.

Introduction

Starting with version 2.5.5, SIL Engine™ exposes a REST service to facilitate arbitrary execution of SIL™ scripts. These services are available via HTTP POST at <your_base_url>/rest/keplerrominfo/refapp/latest/async-script and <your_base_url>/rest/keplerrominfo/refapp/latest/async. The service responses are all JSON formatted (see Beans below).

You will notice that most of the methods will schedule a task for execution and will provide a unique identifier for the task. You will have to call getResults and provide the identifier to check the status of the task (running or finished) and retrieve the results.

Authentication

Note that all the services require that the calling user is authenticated. You can use Basic authentication with your HTTP request.


Services

MethodFull PathAvailability
findScriptFiles<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/findScriptFiles4.0.0+
checkScript<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/checkScript4.0.0+
runScript<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/runScript4.0.0+
runDetachedScript<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/runDetachedScript4.0.0+
getResult<your_base_url>/rest/keplerrominfo/refapp/latest/async/getResult4.0.0+

findScriptFiles

Allows you to scan a folder for specific files where the filename matches a specific regular expression.

ParameterTypeRequiredDescription
dirPathstringyesThe path of the directory to scan. Can be absolute or relative to the silprograms folder. If absolute, it must still point to a location under silprograms.
regexstringyesThe regular expression to match the filenames against

Returns a ScriptFileListResponse.


Example Request using AJS
AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/findScriptFiles",
 data : JSON.stringify({
 	dirPath : "D:/test",
    regex : "[^.]*\.sil"
 }),
 success : function(data) {
	console.log(data);
 },
 beforeSend: function (xhr){ 
	 xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password)); 
 }
}); 



Example JSON Response
{
 "files":[
   "D:\\test\\test_1234567890 - Copy (5).sil",
   "D:\\test\\test_1234567890 - Copy (6).sil",
   "D:\\test\\test_1234567890 - Copy.sil",
   "D:\\test\\test_1234567890.sil"
 ]
}  


checkScript

Schedules a check script task to be run asynchronously for the given script and returns a ScriptScheduledResponse.

ParameterTypeRequiredDescription
source

ScriptSource

yesThe script to check


Example Request using AJS
AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/checkScript",
 data : JSON.stringify({
   source : {
   	type: "INLINE",
   	code: "return 1;"
 	}
 }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});



Example JSON Response
{
 "key" : 4
} 




runScript

Schedules a run script task to be run asynchronously for the given script and returns a ScriptScheduledResponse. To run in the context of an issue, pass a property with the key "sil.issue.key" and value with the issue key.

ParameterTypeRequiredDescription
source

ScriptSource

yesThe script to run
propertiesarray of objects containing "key" and "value"no
example properties
"properties": [
	{
		"key": "sil.issue.key",
		"value": "TEST-1"
	}
]
argsarray of stringsnowill be passed into the script as the "argv" variable


Example Request using AJS
AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/runScript",
 data : JSON.stringify({
   source: {
   		type: "FILE",
   		code: "example.sil"
	},
   properties: [{
        "key": "sil.issue.key",
        "value": "TEST-1"
    }],
   args: ["first", "second"]
 }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});



Example JSON Response
{
 "key" : 4
} 



runDetachedScript

Schedules a task to execute the script passed in as parameter on the server side and does not return the response or any information about it (simply runs the script).

ParameterTypeRequiredDescription

source

ScriptSource
yesThe script to run
propertiesarray of objects containing "key" and "value"no
example properties
"properties": [
	{	
		"key": "sil.issue.key",
		"value": "TEST-1"
	}
]
argsarray of stringsnowill be passed into the script as the "argv" variable


Example Request using AJS
AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async-script/runDetachedScript",
 data : JSON.stringify({
   source: {
   	type: "INLINE",
   	code: "return 1;"
 }
 }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});



Example JSON Response
HTTP 204 No content



getResult

Checks if the task identified by the provided id is still running or has finished and returns an AsyncResultResponse. If the task has finished execution, the result is removed from memory and returned in the response. Subsequent calls to this method will not return the result. If the task has not finished execution, you may repeat the call to getResult until the response contains "running": false.

ParameterTypeRequiredDescription

key

intyesThe unique key identifying a scheduled task.


Example Request using AJS
AJS.$.ajax({
 type: 'POST',
 contentType: "application/json",
 url : "http://localhost:7210/rest/keplerrominfo/refapp/latest/async/getResult",
 data : JSON.stringify({
   key: 4
  }),
 success : function(data) {
    console.log(data);
 },
 beforeSend: function (xhr){
     xhr.setRequestHeader('Authorization', "Basic " + btoa(username + ":" + password));
 }
});



Example JSON Response for checkScript
{
 "running":false,
 "outcome": {
	 "valid": true
 }
}


Example JSON Response for checkScript
{
 "running":false,
 "outcome" : {
 	"errors" : [
		{
			"errLine":1
			"error":"Encountered <DOUBLE>  at line 1, column 13. Was expecting one of:  ";" , "." , "." "
		}
	]
 }
}
Example JSON Response for runScript
{
 "running":false,
 "outcome" : {
	"results":["string returned from script"] // array of values returned by script using "return val1, val2";
 }
}


Beans

ScriptFileListResponse

FieldTypeDescription
filesstring []List of absolute paths


AsyncResultResponse


FieldTypeDescription

running

booleanSignals that the script is still running and that you should wait a bit before retrying the call.
outcomeObjectThe results


ScriptScheduledResponse

FieldTypeDescription
keyintThe unique key of the scheduled task


ScriptSource

FieldTypeDescription
typestringThe type of the source. Either "INLINE" or "FILE".
codestring

If type is "INLINE", this should contain some SIL source code

if type id "FILE", this should contain a path to a file. The path can either be absolute or relative to the silprograms folder. If absolute, must still point to a file under silprograms (e.g. "/opt/jira/home/silprograms/fld1/fld2/script.sil" and "fld1/fld2/script.sil" point to the same file)

CURL Example


The following curl calls show how you would call SIL™ scripts from your favourite system (that's Linux, I hope). The commands assume that username / password is 'admin'

Notice the way you pass multiple parameters to the SIL™ scripts. The logic is the same, you post the script to start running asynchronously, then you come back later for the results.


$curl -H "Content-Type: application/json" -u admin:admin -d " {\"source\" : { \"type\": \"INLINE\", \"code\": \"return 1;\"}}" 192.168.19.250:7210/rest/keplerrominfo/refapp/latest/async-script/runScript
{"key":3}

$curl -H "Content-Type: application/json" -u admin:admin -d "{\"key\" : 3}" 192.168.19.250:7210/rest/keplerrominfo/refapp/latest/async/getResult 
{"running":false,"outcome":{"results":["1"]}}


  • No labels