Trigger-based Hook

The following is an overview of how a trigger-based hook is defined in a server hook configuration file.

{
  "<path>": [
    {
      "when": "<trigger>",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "<endpoint_name>"
    },
    /* Other hooks */
  ],
  /* Other paths with hooks */
}

Server code (the target function name specified with the endpoint) will be executed when the specified trigger occurs on the entity specified by the path. Note that server code is executed "at least once"; the specified endpoint could be executed multiple times.

The path can point to Bucket, User, Group, Thing or Installation:

  • Bucket: Listen for a trigger that occurs on the specified bucket.

    • The path is to be specified in one of the following manners:
      • kiicloud://buckets/<bucketID> for the application-scope bucket.
      • kiicloud://groups/*/buckets/<bucketID> for the group-scope bucket.
      • kiicloud://users/*/buckets/<bucketID> for the user-scope bucket.
      • kiicloud://things/*/buckets/<bucketID> for the thing-scope bucket.
    • The possible trigger is one of the followings:
      • DATA_OBJECT_CREATED: A new object has been created in the specified bucket.
      • DATA_OBJECT_DELETED: An object in the specified bucket has been deleted.
      • DATA_OBJECT_UPDATED: An object in the specified bucket has been updated.

    Server code can take various trigger parameters. For more information, see the table of parameters of a bucket-related trigger.

  • User: Listen for a trigger that occurs on any users.

    • The path is to be specified as kiicloud://users.
    • The possible trigger is one of the followings:
      • USER_CREATED: A new user has been created.
      • USER_EMAIL_VERIFIED: A user's email address has been verified.
      • USER_PHONE_VERIFIED: A user's phone number has been verified.
      • USER_PASSWORD_RESET_COMPLETED: A user's password has been reset.
      • USER_PASSWORD_CHANGED: A user's password has been changed.
      • USER_DELETED: A user has been deleted.
      • USER_UPDATED: A user's attributes have been updated.

    Server code can take various trigger parameters. For more information, see the table of parameters of a user-related trigger.

    You can use the USER_UPDATED to listen for unsupported triggers like Disabling Users. You can, for example, update the user attributes right after this user is disabled.

  • Group: Listen for a trigger that occurs in any groups.

    • The path is to be specified as kiicloud://groups.
    • The possible trigger is one of the followings:
      • GROUP_CREATED: a new group has been created.
      • GROUP_DELETED: a group is deleted.
      • GROUP_MEMBERS_ADDED: A new group member has been added.
      • GROUP_MEMBERS_REMOVED: A group member has been removed.

    Server code can take various trigger parameters. For more information, see the table of parameters of a group-related trigger.

  • Thing: Listen for a trigger that occurs on any things.

    • The path is to be specified as kiicloud://things.
    • The possible trigger is one of the followings:
      • THING_CREATED: A new thing has been registered.
      • THING_ENABLED: A new thing has been enabled.
      • THING_DISABLED: A new thing has been disabled.
      • THING_USER_OWNER_ADDED: A new user has been added as a thing owner.
      • THING_GROUP_OWNER_ADDED: A new group has been added as a thing owner.
      • THING_USER_OWNER_REMOVED: A user has been removed from a thing owner
      • THING_GROUP_OWNER_REMOVED: A new group has been removed from a thing owner.
      • THING_FIELDS_UPDATED: Thing information has been updated.
      • THING_DELETED: A thing has been unregistered.
      • THING_CONNECTED: A thing becomes online (i.e. an MQTT connection has been established).
      • THING_DISCONNECTED: A thing becomes offline (i.e. an MQTT connection has been disconnected, either gracefully or unexpectedly).

    Server code can take various trigger parameters. For more information, see the table of parameters of a thing-related trigger.

  • Installation: Listen for a trigger that occurs when a user device is installed on Kii Cloud for receiving a push notification.

    • The path is to be specified as kiicloud://installations.
    • The possible trigger is one of the followings:
      • INSTALLATION_CREATED: a device is installed for receiving push notifications.
      • INSTALLATION_DELETED: a device is removed from receiving push notifications.

    Server code can take various trigger parameters. For more information, see the table of parameters of an installation-related trigger.

Here is a sample trigger-based hook.

{
  "kiicloud://users": [
    {
      "when": "USER_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "main"
    }
  ]
}

In this example, the endpoint main will be executed when a new user is created (which would be the perfect hook for Setting Data Automatically with a Trigger-based Hook).

Triggers to the same path

Define triggers as a JSON array as below if multiple triggers need to be set against the same path. Note that only the last trigger will be enabled if the same path is defined multiple times in the configuration file.

{
  "kiicloud://buckets/myBucket": [
    {
      "when": "DATA_OBJECT_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "func1"
    },
    {
      "when": "DATA_OBJECT_DELETED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "func2"
    }
  ]
}

You cannot set multiple endpoints on a single trigger. For example, you will receive an error message if you attempt to set the func1 and func2 endpoints on a user creation trigger. If you need to do this, implement server code accordingly so as to run the necessary logics in one endpoint execution.