Welcome to the Protogrid Developer Wiki. A place to gather all the documentation and tips&tricks regarding Protogrid.

This is an old revision of the document!

Table of Contents


Agents run periodically and execute code specified by the user.

Note: Agents are only available in environments that run Protogrid 2.1 or higher.


To set up an agent, there are two necessary steps:

  • Under Design → Code, create an Agent Library and add your code to the on_schedule function.
  • Under Design → Proto, select the Proto you want to use and add corresponding the Agent Library


  1. Create a Proto with a DateTime Field and a Text Field. Copy the key of the Text Field.
  2. Create a user profile with rights to edit the proto created above.
  3. Create an Agent Library, specify the user created above as context user and copy the following code. Replace the value of defkey_status_field with the key from above.
  4. Add this Agent Library to your Proto.
  5. Based on this proto, create some cards where the date lies within the next 60 minutes. Wait one hour.
  6. The value in your Text Field should have been replaced by Frist abgelaufen.
function agent_library() {
    var defkey_status_field = "3b47a5fe-894d-4580-bc0c-563aa83d9a02"; // TODO change this value
    function set_value(card, field_key, value) {
        //sets the value of a single-value field given by field_key
        for (var i = 0; i < card.design_elements.length; i++) {
            if (card.design_elements[i]['definition_key'] === field_key) {
                card.design_elements[i]['value'] = value;
        return card;
    function on_schedule(card, cookie) {
        card = set_value(card, defkey_status_field, 'Frist abgelaufen');
        return card;
    return {
        set_value: set_value,
        on_schedule: on_schedule


Agents are checked every hour. If any DateTime Field on a card has a smaller value than the current time and the Agent has not yet run since that time, the Agent gets triggered and the code in the Agent Library is executed in the context of this card (for Date-Only Fields, the time taken into account is said date, 00:00 GMT). Agents run in the context of a specific user profile. This user's password is automatically reset during the execution process. So this user profile shall only be used for agents and not for physical users. All agent executions are logged in the agent_log on the respective card.