Server Hook Configuration File

A Server Hook configuration file defines the timing when your Server Code is launched. It is to be deployed together with the Server Code.

There are two types of timing (hooks) you can specify in the Server Hook configuration file (for the detailed explanation, please read Server Code Execution in the Function Guide).

All settings are to be written in one JSON file. Please check the following example of the Server Hook configuration file. In this example, five hooks (user creation, creation and deletion of an application scope bucket, every 0 min and every day on 2:30 UTC) are defined.

{
  "kiicloud://users": [
    {
      "when": "USER_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "userCreated"
    }
  ],
  "kiicloud://buckets/highScore": [
    {
      "when": "DATA_OBJECT_CREATED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "highScoreCreated"
    },
    {
      "when": "DATA_OBJECT_DELETED",
      "what": "EXECUTE_SERVER_CODE",
      "endpoint": "highScoreDeleted"
    }
  ],
  "kiicloud://scheduler": {
    "HourlyCheck": {
      "what": "EXECUTE_SERVER_CODE",
      "cron": "0 * * * *",
      "endpoint": "checkData",
      "parameters": {
        "executionType": "hourly",
        "target": "user"
      }
    },
    "DailyCheck": {
      "what": "EXECUTE_SERVER_CODE",
      "cron": "30 2 * * *",
      "endpoint": "checkData",
      "parameters": {
        "executionType": "daily",
        "target": "all"
      }
    }
  }
}

An endpoint specified in the Server Hook configuration file will be automatically launched when the conditions are met. It can be also launched manually via the client SDK.

Hook for Server Triggered Execution

The following is an overview of how the server triggered execution is defined in a Server Hook file.

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

The Server Code (the target function name being specified with the endpoint) will be executed when the specified trigger occurs on the entity specified by the path.

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.

    Your Server Code can get various bucket trigger parameters. Please read here for more information.

  • 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.

    Your Server Code can get various user trigger parameters. Please read here for more information.

    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.

    Your Server Code can get various group trigger parameters. Please read here for more information.

  • 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 have 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).

    Your Server Code can get various user trigger parameters. Please read here for more information.

  • 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.

    Your Server Code can get various installation trigger parameters. Please read here for more information.

Here is the sample Server 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 this sample Server Code).

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, please implement the Server Code accordingly so as to run the necessary logics in one endpoint execution.

Hook for Schedule Based Execution

The following is an overview of how the schedule based execution is defined in a Server Hook file.

{
  "kiicloud://scheduler": {
    "<job_name>": {
      "cron": "<cron_expression>",
      "endpoint": "<endpoint_name>",
      "parameters": {
        "arg1": "xxxx"
      },
      "what": "EXECUTE_SERVER_CODE"
    }
    /* more hooks */
  }
  /* more paths with more hooks */
}

The Server Code (the target function name being specified with the endpoint) will be executed at the time designated by the cron_expression. You can also assign a job_name on each schedule definition so as to make it easy to later check if the defined hook is properly executed. You can optionally define parameters you want to pass to the endpoint in the parameters property.

You can set multiple schedules under "kiicloud://scheduler". When setting multiple schedules, make sure to use different job_name so as to distinguish them (Kii Cloud will not give you an error if the name is duplicating). If you set the same schedule with multiple names, the specified endpoint will be executed for the number of the times it was set.

The following illustrates how to define the time with the cron expression.

Note that time should be specified in UTC.

You can also use the following special characters.

  • Asterisk (*) means that the cron expression matches with any field values.
  • Hyphen (-) indicates ranges.
  • Slash (/) means the incrementation. For example, "0/10" in the first field (min) means "every 10 minutes".
  • Comma (,) means a list of values. For example, "MON,WED,FRI" in the fifth field (day of the week) means "Monday, Wednesday, and Friday".

Here are some examples:

#run hourly
0 * * * *

#run at one minute past midnight (00:01) on every day:
1 0 * * *

#run at 05:00 on weekdays (Monday to Friday)
0 5 * * MON-FRI

#run every two hours, at midnight, 2 am, 4 am, 6 am, 8 am, and so on:
0 0/2 * * *

#run every 5 minutes starting at 2 pm and ending at 2:55 pm, every day:
0/5 14 * * *

#run at 11:00 and 16:00 on weekends (Sunday and Saturday)
00 11,16 * * SUN,SAT

Please be aware of the following limitations:

  • You cannot use "*" with "/" at the same time.

    • OK: 0/5 14 * * *
    • NOT OK: */5 14 * * *
  • You can use just one range (e.g. 4-7), one incrementation (e.g. 2/5) or one list (e.g. 0,5,10,15) in single cron expression item (minute, hour,...). You cannot mix them in the same item.

    • OK: 0,5,10 21-23 * * MON-FRI
    • NOT OK: 5-8/2 * * * *
  • You cannot set a day-of-week and a day-of-month at the same time.

    • NOT OK: 0 0 1 1 SUN

Here is the sample Server Hook.

{
  "DailyMessage_5am": {
    "cron": "0 5 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "5am"
    },
    "what": "EXECUTE_SERVER_CODE"
  },
  "DailyMessage_10pm": {
    "cron": "0 22 * * *",
    "endpoint": "sendDailyMessage",
    "parameters": {
      "time": "10pm"
    },
    "what": "EXECUTE_SERVER_CODE"
  }
}

In this example, the endpoint sendDailyMessage will be executed on 5:00 am and 10:00 pm every day (in UTC). For each execution, the different parameters are passed to the Server Code (Please check here for a sample Server Code that works well with this hook).