Trigger: Difference between revisions

Revision as of 11:41, 17 January 2022

This article is a stub.

Triggers can be used to execute external scripts and applications.

When an 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.

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 ] ],
    }

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 decial 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"
}