Child pages
  • RunScript
Skip to end of metadata
Go to start of metadata

Description

The RunScript API allows the execution of a specified script. Execution permissions are controlled by the script's execute ACL.  

Apstrata provides a core scripting engine using, in a native way, the ubiquitous and powerful JavaScript language. Scripts are executed on the server, and they have full access to the apstrata code API. Moreover, they provide the developer with the ability to add more complex validation rules and business logic while interacting with the data. Scripts also provide a way to the developer to orchestrate multiple API calls, passing data from one call to another. Each Script has its own global scope which gets destroyed at the end of that Script execution. 

Each Script has its own set of read, write, and execute ACLs identifying the Users and/or Groups who can read, write, and execute that script respectively. 

A Script can be run synchronously by calling the RunScript API or asynchronously by scheduling it to run at a certain date and time. Each Script execution time is limited to 30 seconds for safety and security reasons. Hence, Scripts operating on large data sets will need to run in asynchronous mode, where a batch of the data is handled every time the script is fired. In this case, the Script keeps rescheduling itself until all the data set has been handled. 

A developer may choose to generate debug level info from any Script and have those log traces downloaded as a file using the GetScriptLogs API.

A developer is also given the choice to make his set of Scripts for a particular application mode modular by defining Script libraries that can be included in other Scripts. This is very useful for building different classes of script libraries that can be integrated in any application, such as social media script libraries, persistence script libraries, identity script libraries, messaging script libraries, etc.

The scripts that are created by the applications' owners are private and can only be accessible under that application. However, Apstrata provides a set of scripts that can be shared among all the applications; this feature grants the application owner the privileges to view those scripts and run them, to import them into their own script libraries and then apply desired updates and modifications on that private copies.

For more specific details on scripts, please refer to the Server Scripting Reference section.

  • Note that shared common system scripts can only be executed when they are not overridden by an application private script.

Specific Request Parameters

 (Refer to Common Request Parameters)

NameDescriptionRequiredDefaultPossible Values

apsdb.scriptName

The name of the script to execute

Yes

  

[paramName]

The value of a parameter named "paramName" that needs to be passed to the script (i.e: parameter1 = valueA)

Note that multiple parameters and their values can be passed to the script

No

  

apsdb.authToken

This parameter is used to sign the request with a token. For more details on signing requests, please refer to the page entitled Authentication .

No

  

Specific Response Elements

(Refer to Common Response Elements)

The following specific "result" element is a child of the common root element "response" and a sibling of the common "metadata" element:

{
	"result": "whatever is returned from the script; this could be any javascript supported type including JSON object"
}

Specific Logical Errors

(Refer to Common Logical Error Codes)

ErrorMessageStatus Code

PERMISSION_DENIED

 

403

INVALID_SCRIPT_NAME

Invalid script name [scriptName]

400

SCRIPT_ERROR

 

400

Examples

Sample Request

Request URL: http://sandbox.apstrata.com/apsdb/rest/[authenticationkey]/RunScript?apsws.time=[timestamp]&apsws.authSig=[signature]

POST Parameters

apsdb.scriptName=[script_name]

Sample XML Response

Success XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata>
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>success</status>      
    </metadata>
</response>

Failure XML:

<response xmlns="http://www.apstrata.com/services/schemas/apstrata_database_response.xsd">
    <metadata
        <requestId>xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx</requestId>
        <status>failure</status>
        <errorCode>[errorCode]</errorCode>
        <errorDetail>[failMsg]</errorDetail>
    </metadata>
</response>

Sample JSON Response

 

{
	"metadata": {
		"requestId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx", 
		"status": "success", 
		"statusCode": "200"
	}, 
	"result": "whatever is returned from the script; this could be any javascript supported type including JSON object"
}

Upload a file to the Script

To pass a file to a script, you need to send it in a multipart request. This can either be done in an HTML form with an input of type “file” representing the field under which the file will be saved (ex: <input type=”file” name=”myFileFieldName”>) or by sending a raw HTTP request as follows:

POST /apsdb/rest/[authenticationkey]/RunScript?apsws.time=[timestamp]&apsws.authSig=[signature] HTTP/1.0
Host: sandbox.apstrata.com
Content-Type: multipart/form-data; boundary=---------------------xxxxxxxxxx
Content-length: ####
-----------------------xxxxxxxxxx
Content-Disposition: form-data; name="apsdb.scriptName"
[scriptName]
-----------------------xxxxxxxxxx
Content-Disposition: form-data; name="file"; filename="myFile.txt"
Content-Type: application/octet-stream
 myfile contents, my file contents, my file contents, my file contents, my
 file contents, my file contents, my file contents, my file contents,
 myfile contents, my file contents, my file contents, my file contents, my
 file contents, my file contents, my file contents, my file contents
-----------------------xxxxxxxxxx
  • No labels