Execution runs a plug in to return a response.
The plug in is passed parameters to the execution in the "data" attribute, the context in the "context" attribute, the user in the "user" attribute and options in the "options" attribute, plus the appropriate entityMapping object in "entityMapping" (to allow the execution plug-in to access additional entity details). The "options" attribute is largely redundant and is only provided for compatibiltiy with other calls types and should not generally be used (pass all parameters in data). It should return a response as a string in the "response" attribute, which can be a JSON object, JSON array or a string. The response is assumed to be have a content type of "application/json".
If you are using the script plugin, a simple "Hello World" execution would look like this:
attributes.put('response',{message:'Hello world'});
Each execution is represented by an entity in the schema, with the "execute" property set to true. The plugin and its configuration is identified using the "processor" and "processorConfig" properties, the same as post processing.
Executions can be run through the instance servlet. When run through the instance servlet, the plugin may also set the "httpStatus" attribute to set the HTTP status code, and the "httpHeaders" attribute to set the HTTP response headers (which can be a JSON string, JSON object or Map). Use the "Content-Type" header to set a content type other than "application/json".
Execution processing is not prescriptive about how errors are returned.
If you want to return errors that are similar to the put interface, return in the "response" attribute a JSON object of the form.
{
"status": statusCode,
"errorMessage": "Error message"
}
Use the status codes defined in the MessageStatus table, of which a status code of 20 can be used as a catch-all error code.
You can, if you prefer, return the status and error message in the attributes "status" and "errorMessage", which will be used to build a suitable response if one has not yet been set.
If you are writing a plug-in to be used through the instance servlet, the status will automatically be translated to an appropriate HTTP status code. Alternatively, you can signal an HTTP error explicitly by setting the attribute "httpStatus" to an HTTP error, and optionally setting the "response" attribute to a suitable error message.
The execute SQL plug in can be used to execute a SQL command or run a SQL query.
The configuration for the plug in defines the SQL, which may have
? placeholders. If there are any ? placeholders, the parameters
array lists fields definitions for these, which follow the same
format as the field definitions within an entity definition (they
can have reference, type, length, precision and scale). The
parameters can also have a "default" property for a default value.
Remember to use "reference", rather than "name", to identify the
parameters (to be consistent with other field definitions).
The plug in assumes the command will be a select (or a stored
procedure call which returns a result set). It you want to run a
command rather than a query, set the execute propery to true.
The Execute SQL is configured using JSON which describes the SQL and parameters to it.
{
"sql": "call getDoorCostPrice(?,?,?,?,?,?,?);",
"execute": false,
"parameters": [
{
"reference": "range",
"type": "string",
"length": 255
},
{
"reference": "style",
"type": "string",
"length": 255
},
{
"reference": colour
"type": "string",
"length": 255
},
{
"reference": "component",
"type": "string",
"length": 255
},
{
"reference": "hinge",
"type": "string",
"length": 255
},
{
"reference": "height",
"type": "decimal"
"precision": 18,
"scale": 6
},
{
"reference": "width",
"type": "decimal"
"precision": 18,
"scale": 6
}
]
}
A typical call might be something like this in curl.
curl -d@request.json -H "Content-Type: application/json" https:/www.your-data-hub.com/product/services/get_product
... where the request.json would be a simple JSON object. This
can also be passed in the data URL parameter.
{
"range": "Aspire",
"style": "Ascot",
"colour": "Brown Grey Avola",
"component": "Door",
"hinge": "3 Hinge Holes - Left",
"height": 285"
"width": 296
}
This would return a table of data, like a get, even if there is
only one row in it.
[
{
"product_id": "1058150103",
"price": 23.47
}
]
If execute is set, a successful response would return an object with a status of 10 (which means "processed").
{
"status": 10
}
If execute is set, you can run the execute against multiple sets of data by passing an array of data objects rather than a single data object. The SQL will be executed with each set of values in turn. This can be much more efficient than performing multiple calls because it removes the call overhead and the commit is only carried out at the end of processing the data. The data option is valid when execute is not set, but only the results from the last run are returned. This may be useful if calling a stored procedure that performs an action and returns data.
The SQL is run against the database defined by the dataStore property in the config or on the entity in the schema, which is used in the same way as it is when writing to a data store. This means that the dataStore will default to that used for other table accesses, unless overridden in the config.
If the passThrough option on the plug in config is set to true,
then sql, parameters and execute will be read from the call data,
and the data values read from a "data" property within the call
data (which may be an array, as when passThrough is not being
used). To allow execute in the call, execute must also be set in
the config (if execute is set in the config but not the call,
execute is treated as false). Be careful with the passThrough
option: secure the service calls effectively and consider
carefully before using it in a production environment.