Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt
hiddentrue

REST is now the de facto standard for modern online tool integrations.

REST is now the de facto standard for modern online tool integrations. SIL supports REST is several different ways, through HTTP routines to make outgoing REST calls. Through SIL Webhooks to support incoming REST calls, and through the SIL REST Service for ad-hoc incoming calls.

HTTP Routines

For more information about using HTTP Routines to make outgoing calls, see the information below:

Filter by label (Content by label)
showLabelsfalse
showSpacefalse
cqllabel = "http_routine" and space = currentSpace ( )

Webhooks

For more information about creating new REST endpoints that can process whatever format the data is received in, see the Web Hook Configurations page.

Image RemovedImage Added

Common REST Service

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.

Note

Authentication

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

Services

Method

Full Path

Availability

findScriptFiles

<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/findScriptFiles

4.0.0+

checkScript

<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/checkScript

4.0.0+

runScript

<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/runScript

4.0.0+

runDetachedScript

<your_base_url>/rest/keplerrominfo/refapp/latest/async-script/runDetachedScript

4.0.0+

getResult

<your_base_url>/rest/keplerrominfo/refapp/latest/async/getResult

4.0.0+

findScriptFiles

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

Parameter

Type

Required

Description

dirPath

string

yes

The 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.

regex

string

yes

The regular expression to match the filenames against

Returns a REST Capabilities#ScriptFileListResponse.

Example Request using AJS
Code Block
languagejs
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
Code Block
languagejs
{
 "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 REST Capabilities#ScriptScheduledResponse.

Parameter

Type

Required

Description

source

REST Capabilities#ScriptSource

yes

The script to check

Example Request using AJS
Code Block
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
Code Block
{
 "key" : 4
} 



runScript

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

Parameter

Type

Required

Description

source

REST Capabilities#ScriptSource

yes

The script to run

properties

array of objects containing "key" and "value"

no


example properties
Code Block
"properties": [
	{
		"key": "sil.issue.key",
		"value": "TEST-1"
	}
]


args

array of strings

no

will be passed into the script as the "argv" variable

Example Request using AJS
Code Block
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
Code Block
{
 "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).

Parameter

Type

Required

Description

source

REST Capabilities#ScriptSource

yes

The script to run

properties

array of objects containing "key" and "value"

no

example properties

Code Block
"properties": [
	{	
		"key": "sil.issue.key",
		"value": "TEST-1"
	}
]

args

array of strings

no

will be passed into the script as the "argv" variable

Example Request using AJS
Code Block
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
Code Block
HTTP 204 No content


getResult

Checks if the task identified by the provided id is still running or has finished and returns an REST Capabilities#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.

Parameter

Type

Required

Description

key

int

yes

The unique key identifying a scheduled task.

Example Request using AJS
Code Block
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
Code Block
{
 "running":false,
 "outcome": {
	 "valid": true
 }
}

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


Beans

Anchor
ScriptFileListResponse
ScriptFileListResponse
ScriptFileListResponse

Field

Type

Description

files

string []

List of absolute paths

Anchor
AsyncResultResponse
AsyncResultResponse
AsyncResultResponse

Field

Type

Description

running

boolean

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

outcome

Object

The results

Anchor
ScriptScheduledResponse
ScriptScheduledResponse
ScriptScheduledResponse

Field

Type

Description

key

int

The unique key of the scheduled task

Anchor
ScriptSource
ScriptSource
ScriptSource

Field

Type

Description

type

string

The type of the source. Either "INLINE" or "FILE".

code

string

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.

Code Block
$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"]}}

Contents

Table of Contents