CoCoS SERVER Scripting

Introduction

Scripts in CoCoS are developed in PHP and are used to customize CoCoS to meet the needs of the cliet. In the future CoCoS scripting will support Javascript and Python. Example and standard scripting can be found in our (just started) pulic CoCoS script repository. https://github.com/Concera-Software/CoCoS-Scripts 

Event driven and cyclic scripting

Scripts can run cyclic in a specific time-interval. For example, retreiving weather information for a heater control can be run every 10 minutes autonomously. The script can store data in tags so retreived information can be used by other entities (such as other scripts) in CoCoS.

Next to that Script can (also) run event driven. To realise event drive scripts just add triggers to a script. A trigger can be a change of the value of a tag or receiving data from a device. The screenshot below shows an example where a script controls an X-Protect Server (Video Management System)  triggered by a dailstate of an intercom device. The essence of the example below is an implementation where a camera is moved to a preset position as soon as someone rings at an intercom on the premises. 

Cyclic scripts are usefull for repeating tasks where event driver scripts are usefull to act on events from processes, users and devices in the blink of an eye. Event driver operations are usally small but fast and direct. Cyclic scripts often contain interfaces with other systems and are usually larger. Creating large event driver script can result in hogging resources and therefor is discouraged.

The script editor

Scripting is available in the script item in the programming menu. Just extend the "Programming" item and click Scripts and then Scripts.    If it's you're first time using the installed CoCoS environment the list is empty.    Just hit the [ + ] button to create a new script or open an existing script for the list.

The editor of the scripting environment opens and, if an existing script is opened, shows a view like the screenshot below. Next to the obvious code editor, there are en number of settings and tools available in this view that wil help to develop, analyze and debug the script.

The header of the view shows the basic controls like save, save and close and save as new that are available for almost any item (entity) in CoCoS. Also the item reload button is available in a lot of views tot refresh or reload the data of the item. In case of a script this button is used often to reload results of a script-run. 

Save	Save to script to the database
Save and Close	Save the script to the database and close the view (editor)
Save as New	Store the script as a new script. The name needs to be changed. History and versions are not copied because it's a NEW script.
Reload	Reload all data of the opened script (item). This button is often used during development to update the "Info/Error/Warning" field to check if any errors occured during the run.
Publish Script	Publish the script to use for production mode. Scripts that are not published are only execured when run manually or when in developer mode.
Run Script NOW	The script is executed instantly with entered source and value paramters that can be entered in a popup or, depending on the version, in the

The script editor’s General tab is used the most, while the other tabs, although occasionally used, don’t appear on your screen regularly.     Settings   The Settings tab is used to edit options that are normally configured once or twice during development, or when just before the script is published. Settings such as interval (cyclic), logging suppression, and single-execution options to prevent the script from running multiple instances at once, it’s all there, monitoring settings (how to act if th script stops or produces an error or critical), etc. The details of these settings will be explained later in the manual.    Runtime The runtime tab shows all information that usually is needed by a user when checking normal operations of the system or when analyzing an issue.   Development The development tab offer a script developer, next to the script editor, all information needed to test and debug the script.   Triggers A list of all triggers that start the script on a specific event or value change and the ability to add extra triggers to a script.    Events    Depricated Hulp and explenation   Notes and tasks   Value history   Logbook   Properties

multiple

Script Arguments

$value	Meegestuurde waarde in het script. Als een script wordt aangestoten vanuit een tag-trigger, dan is de waarde $value de waarde van de tag die de trigger veroorzaakte.
$source	De naam van het 'bron-object' wat zorgde voor de aanroep van dit script. Dit kan bijvoorbeeld de naam van een tag zijn (bij een tag-trigger) of de naam van een item, bijvoorbeeld wanneer een script wordt aangeroepen vanuit een hmi-item / event.
$arguments
$bucket
$trace
$arguments_ref
$return_tag
$cocos	Object (klasse) met functionaliteiten t.b.v. het ophalen/schrijven/aanmaken van tags, alsmede het schrijven van regels in het logboek. Hierbinnen zijn onderstaande methoden/funties beschikbaar.

Quick-key's

F11	When pressing F11 when the cursor is active in the editor, the script-editor extend to the full size of the script-configuration view.
Ctrl+Alt+R	Save and Run the scirpt

Debugging a script

The Example 

To describe the process of developing and publishing a script will work with an exemple that a connection to an external weather API. This weather API is publicly available and therefore the script is usable for everyone to experiment with. In this example we will activate a tag on temperature limits.