Trigger: Difference between revisions
No edit summary |
mNo edit summary |
||
| (8 intermediate revisions by 3 users not shown) | |||
| Line 1: | Line 1: | ||
[[File:Api_tools_geo.png|thumb|right|400px|[[Trigger]]s in relation to [[Geo Plugin]]s]] | |||
{{stub}} | {{stub}} | ||
| Line 4: | Line 5: | ||
When a Trigger executes, it sends a web request to a specified url. The web request includes query parameters which the receiving server can use to interact with the requesting session. | When a Trigger executes, it sends a web request to a specified url. The web request includes query parameters which the receiving server can use to interact with the requesting session. | ||
{{clear}} | |||
==Request== | ==Request== | ||
| Line 32: | Line 34: | ||
==Response== | ==Response== | ||
The web server is expected to send a response which is a parseable JSON object. | The web server is expected to send a response which is a parseable JSON object. | ||
===TQL response=== | ===TQL response=== | ||
| Line 58: | Line 56: | ||
} | } | ||
}} | }} | ||
==Timing== | |||
Triggers can be executed either before the grid and indicator calculations, or after in the [[Simulation Core]]. They cannot be executed between the grid and indicator calculations. | |||
When triggers are executed, the trigger responders are required to respond within the configured timeout time, making sure there is always an upper limit on the waiting time. By default this trigger timeout is set on 10 seconds. | |||
Grid and indicator calculations are only executed once all ''before'' triggers have either responded or timed out. | |||
==Examples== | ==Examples== | ||
| Line 97: | Line 102: | ||
$globalName = strtoupper($key).'_COUNTED'; | $globalName = strtoupper($key).'_COUNTED'; | ||
//...and use that to create the TQL update statement. | //...and use that to create the TQL update statement. | ||
$queries[ 'UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_' . $globalName ] = $amountOfFeatures . '.0' ;//The Tygron Platform expects results with a | $queries[ 'UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_' . $globalName ] = $amountOfFeatures . '.0' ;//The Tygron Platform expects results with a decimal notation. | ||
} | } | ||
| Line 112: | Line 117: | ||
"UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_AREAS_COUNTED" : "1.0" | "UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_AREAS_COUNTED" : "1.0" | ||
} | } | ||
}} | |||
{{article end | |||
| notes= * Because a JSON object is expected, the keys must be unique, in principle not allowing a single Trigger to call the same Event multiple times. However, adding a nonce parameter to the name of the event will work around this. For example: {"editorarea/add/nonce1":[1],"editorarea/add/nonce2":[2]} will be valid and result in the creation of a total of 3 [[Areas]]. | |||
}} | }} | ||
{{Editor tools nav}} | {{Editor tools nav}} | ||
Latest revision as of 07:32, 15 November 2024
Triggers can be used to execute external scripts and applications when a recalculation of grids and indicators is requested.
When a Trigger executes, it sends a web request to a specified url. The web request includes query parameters which the receiving server can use to interact with the requesting session.
Request
The following query parameters are relevant:
| Type | Key | Meaning | Notes |
|---|---|---|---|
| Querystring / GET parameter | token | API token for session access | |
| Querystring / GET parameter | f | Expected return format. | Defaults to "JSON" |
| Request header | Referer | The originating Tygron server's url | "Referer" is misspelled in the original http specification. |
Response
The web server is expected to send a response which is a parseable JSON object.
TQL response
If the trigger type is "TQL", each key of the response map must be a valid TQL update statement, and each value must be a value in decimal notation.
The following result would set the Globals FOO and BAR to the specified values:
{
"UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_FOO" : 1234.0,
"UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_BAR" : 5678.0,
}
Event response
If the trigger type is "EVENT", each key of the response map must be a valid event, and the value must be an array of parameters.
The following result would execute an editor event to set the start value of the Global with ID 12 to a specified value, and disable the highest two zoomlevels in the project:
{
"EditorGlobal/set_start_value" : [ 11, 123 ],
"EditorZoomLevel/set_active" : [ [ 0, 1 ], [ false, false ] ],
}
Timing
Triggers can be executed either before the grid and indicator calculations, or after in the Simulation Core. They cannot be executed between the grid and indicator calculations.
When triggers are executed, the trigger responders are required to respond within the configured timeout time, making sure there is always an upper limit on the waiting time. By default this trigger timeout is set on 10 seconds.
Grid and indicator calculations are only executed once all before triggers have either responded or timed out.
Examples
Some simple examples exist to demonstrate the call-and-response functionality required for Triggers.
TQL example: Geometry counter
The following example is PHP code which reads out a number of Item types, and writes the results into Globals.
//The API token is retrieved from the query parameters, the server address from the referer header.
$apitoken = $_GET['token'];
$serverurl = $_SERVER['HTTP_REFERER'];
//The script will obtain 3 types of geometries, from 3 urls.
$urls= [
'buildings' => $serverurl . 'api/session/items/buildings?f=JSON&token=' . $apitoken,
'neighborhoods' => $serverurl . 'api/session/items/neighborhoods?f=JSON&token=' . $apitoken,
'areas' => $serverurl . 'api/session/items/areas?f=JSON&token=' . $apitoken,
];
$queries = [];
//For each of the prepared urls...
foreach( $urls as $key => $url ) {
//...set up a webcall to the url...
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
$webcallResult = curl_exec($ch);
curl_close($ch);
//...interpret the received data as JSON, turning it into an associative array...
$features = json_decode($webcallResult, true);
//...count the number of entries in the array...
$amountOfFeatures = count($features);
//...compose the name for the global to write the result to...
$globalName = strtoupper($key).'_COUNTED';
//...and use that to create the TQL update statement.
$queries[ 'UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_' . $globalName ] = $amountOfFeatures . '.0' ;//The Tygron Platform expects results with a decimal notation.
}
//Output the created map as a json string.
echo json_encode( $queries, JSON_PRETTY_PRINT )
exit();
The script will produce an output with the following structure:
{
"UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_BUILDINGS_COUNTED" : "11559.0",
"UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_NEIGHBORHOODS_COUNTED" : "11.0",
"UPDATE_GLOBAL_VALUE_WHERE_NAME_IS_AREAS_COUNTED" : "1.0"
}
Notes
- Because a JSON object is expected, the keys must be unique, in principle not allowing a single Trigger to call the same Event multiple times. However, adding a nonce parameter to the name of the event will work around this. For example: {"editorarea/add/nonce1":[1],"editorarea/add/nonce2":[2]} will be valid and result in the creation of a total of 3 Areas.
Tools