Using the Web Service Connector

Calling the ScriptRunner Web Service Connector

Introduction

ScriptRunner includes the PowerShell script CallASRWebSvcConnector.ps1 with complete sample code for addressing the Web service connector from the PowerShell.

It is possible to address the connector from other web-enabled environments or third-party systems if the corresponding POST packets with JSON data can be sent there.
The data structure of the request is described below.

For initial setup, or testing for errors, it is best to use this PowerShell script: CallASRWebSvcConnector.ps1

The best option for testing is to run a PowerShell console on the machine of the third party system, under the same user as used by the third party system.

In this PowerShell console, start the CallASRWebSvcConnector.ps1 script with the parameters that the third party system also uses. If the execution from the PowerShell is successful, it should also work from the third party system.

Authentication

The authentication of the client, within the request, is required for logging and verifying the authorization, analogous to the access from one of the ScriptRunner apps.

ScriptRunner works with integrated Windows authentication, from which ScriptRunner gets the identity of the caller. Each caller, via the Web Service Connector, requires a user license in ScriptRunner.

The Post Web-Request

The POST Request starts the execution of an action and transfers the required data.
The format of the web requests, is simply POST packages with data in JSON format. 
The Web service connector listens to a specific URL, the REST API of the connector uses the OData v4 web standard.

When a Web request is received, the transmitted data and the access permissions stored in the connector are checked.
The script stored in the addressed action is then started, and the connector responds to the Web request with HTTP code 200 Success.

If errors occur during the check, the connector responds with a standard Web response that contains a corresponding HTTP error code (such as 403 Forbidden if the user is not authorized for the action, or 404 Not found if an action with this name does not exist) and an error message.

URL of the POST request

To connect the Web Service Connector, the POST request is sent to a fixed URL on the ScriptRunner host, based on the host name and the IP port used by ScriptRunner.
Base URL: http://<hostname>:<port>/ScriptRunner
If HTTPS is active in ScriptRunner, the base URL is: https://<hostname>:<port>/ScriptRunner

http://localhost:8091/ScriptRunner/ActionContextItem/StartASRNamedAction 

Data structure of the Post Web-Request

  • ActionName (string)
    Required. The name of the action as configured in ScriptRunner
  • ParamNames (string[])
    Optional. The list of parameter names (without the PowerShell typical $) for which values are to be passed.
  • ParamValues (string[])
    Optional. The corresponding list of values for the parameters with which the action is to run (in the order of the param names!)
  • Options (string[])
    Optional. A list of options. Only the second entry is currently used; you can specify a "cause" for the report (e.g. ticket number, workflow case, etc.).
  • RunFlags (int[])
    Optional. A list of numbers. Only the first entry is currently in use; you can specify a
    "wait time" in seconds here.

The Post Response

ScriptRunner starts the action and the Web Service Connector returns a POST response with HTTP status code 2xx in response to the POST request.

If the JSON is invalid, a detailed HTTP error is returned.

The execution of actions in ScriptRunner is asynchronous, therefore the JSON response contains the Running field, which is TRUE if the action is still running.

The Response contains an extensive JSON data structure with fields for all the information that is also displayed in the report in the ScriptRunner apps. This is relevant for a third party system if it needs the data from the JSON response. The fields are filled when the execution was finished, the connector waits a few seconds to send the response.

If the script execution takes longer and the third system needs the result of the execution, the third system can use a second URL to ask the Web service connector whether the action is complete (polling with a GET request). The response contains the same JSON structure as the original response to the POST request.

The script CallASRWebSvcConnector.ps1 waits for the end of the asynchronous script execution and only then reports the success or failure. It queries the result element from ScriptRunner until Running is False and the remaining values are filled.

Data structure of the Post Response

  • ID (Int64)
    The ID of the status object, needed to wait for Running=FALSE
  • Running (Boolean)
    Indicates whether the script is still running
  • IsError (Boolean)
    Indicates whether the script execution in the PowerShell caused an error
  • OutResultMessage (String)
    The result of the action as given in the script to $SRXEnv.ResultMessage
  • OutReportString (String)
    The complete PowerShell report, as it can also be seen in the Admin App
  • OutSerializedPSObjects (String)
    The result of the action as given in the script to $SRXEnv.ResultObjectJSON
  • OutNumErrors (Int32)
    If IsError=TRUE: Number of PowerShell errors
  • OutErrorString (String)
    If IsError=TRUE: The PowerShell error messages as displayed in the report

This page has been automatically translated and may contain grammatical errors or inaccuracies