Triggers

Triggers are background actions that once started watch for some condition, and when this condition is fulfilled send a trigger event.

This will in place be used by Serverboards Rules to execute some action.

Manifest YAML component definition

- name: Socket is receiving connections
  id: socket.is_up
  type: trigger
  states: down up
  command: daemon
  stop: stop_trigger
  traits: url ip server
  start:
    method: socket_is_up
    params:
      - name: url
        label: URL
        type: text
        description: Full URL of the resource
        placeholder: http://example.com, https://google.com, smtp://mail.com:25, ...
      - name: frequency
        label: Check frequency
        description: Time between checks in seconds
        placeholder: 60s
        default: 60
      - name: grace
        label: Grace period
        description: Seconds that connectivity can be lost without triggering
        placeholder: 60s
        default: 60
  traits: url
  return:
    ms: Time in ms the socket is in the current state
    state: Current state: ok | nok
    ok: true if the socket is up

Trigger methods have some parameters that may be filled by the user. If any of this params has the same name as a config from the service, that configuration will be passed. UI will not ask for that information.

Also can have a service parameter.

The start function will receive also an id parameter with some string that has to be used to identify the triggered actions.

It should return some trigger id that will be passed to the stop function to stop watching such condition.

Each trigger can trigger as many action changes as desired, indicated at states.

Field Description
states List of states the trigger have
command Command component to execute
start Method and params to call to start the trigger. Returns a trigger id.
stop Method to call with the trigger id to stop the trigger.
traits Required traits at service to allow use of this trigger (any)
return Object with the name of the attributes it returns and the description

How triggers work

Trigers have a start and an end method. The start method always receives an id parameter that will be used for triggering actions.

It will also receive the required params in the trigger definition. User can supply the values for this parameters, but they will be overriden at start time with the configuration of the selected service. A parameter named service may exist that will be filled with the service id.

This start method must return some trigger_id (number or string) that will be used for stopping the the trigger using the stop method.

When the trigger is working it may trigger an event at any moment, sending the RPC event trigger with parameters:

  • id with the original id as received from the start call
  • state with the new state of the trigger

Optional start and stop methods

When not setting a start method, no remote method is called, and some other component is supposed to do the checking, listing all triggers of the given trigger type, and performing a trigger.trigger call with the proper trigger id. This helper method may be a init service or a cron service.

params are optional, and can be used for configuration as used by this helper method. If no params there is no need for an empty start section.

Triggers without start method are called shallow triggers.

It there is no stop method, the command will be just stopped following normal command lifecycle rules, which is a ok behaviour for one_for_one commands.

- id: trigger
  type: trigger
  states: ok warning expired
  start:
    params:
      - name: service
        type: service
        description: What service to watch. Leave empty for all.
for t in serverboards.rpc.call("rules.list", type="test/trigger"):
  if trigger(t):
    serverboards.rpc.call("rules.trigger", id=t["id"], state="nok", other="data")

Traits

The list of traits is used as if any is also present on the service, this trigger may be applied to it. These are now only for UI purposes, and are not enforced at the backend.

There are some special traits:

  • cloud – Show on the cloud section
  • server – Show on the server section
  • service – Only show when there is a related service
  • no-service – Only show when there is no related service

Service is required as if there are no traits set, it matches every service and no-service.

Recomendations

It is recommended that the start itself triggers a new state stating the current state, but in some triggers this may not be a good idea.

Special care must be given when creating triggers with singleton or init strategy daemons, as new calls can be received. If they are under one_for_one strategy there is no problem to block taking care that the only possible call from server side is stop, that will be followed by terminating the daemon itself.