View source for Trigger

[[File:Api_tools_geo.png|thumb|right|400px|[[Trigger]]s in relation to [[Geo Plugin]]s]]
{{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.
{{clear}}

==Request==
The following query parameters are relevant:

{|class=wikitable
! 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 [[Global]]s FOO and BAR to the specified values:
{{code|1=
    {
        "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:
{{code|1=
    {
        "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. 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 [[Global]]s.
{{code|1=
//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:
{{code|1=
{
  "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"
}
}}

{{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}}