Trigger

This article is a stub.

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