Trigger: Difference between revisions

From Tygron Support wiki
Jump to navigation Jump to search
mNo edit summary
No edit summary
 
(20 intermediate revisions by 2 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}}


API Triggers can be used to execute external scripts and applications.
Triggers can be used to execute external scripts and applications when a recalculation of grids and indicators is requested.


When an API 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 session from which the call originated.
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 31: Line 33:


==Response==
==Response==
The web server is expected to send a response which is a parseable JSON object. If the trigger type is TQL, each key of the object must be a valid TQL update statement, and each value must be a value in decimal notation.
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==
==Examples==
Some simple examples exist to demonstrate the call-and-response functionality required for API triggers.
Some simple examples exist to demonstrate the call-and-response functionality required for Triggers.


===TQL example: Geometry counter===
===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.
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}}

Latest revision as of 10:48, 19 December 2023

Triggers in relation to Geo Plugins
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. 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.