Parameters for a Trigger-based Hook

This topic explains function parameters when an endpoint in server code is called by a trigger-based hook.

An endpoint is defined in the following way as shown in Server Code Syntax.

// Synchronous function
function funcName(params, context) {
  // Your code comes here...
}

// Asynchronous function
function funcName(params, context, done) {
  // Your code comes here...
}

The function name funcName becomes an endpoint name. You will use this endpoint name to associate a server hook (server event) with the target function when you register server code with the command line tool.

The first argument params is used to get execution parameters. The information you can get with this argument depends on the type of the trigger that executes the server code.

Parameters for a bucket-related trigger and how server code can get them:

Event parameters	How to get the parameter values?
Scope of the bucket that triggered the execution	"User scope" if `params.objectScope.appID` and `params.objectScope.userID` have values.
	"Group scope" if `params.objectScope.appID` and `params.objectScope.groupID` have values.
	"Thing scope" if `params.objectScope.appID` and `params.objectScope.thingID` have values.
	"Application scope" if only `params.objectScope.appID` has a value.
ID of the bucket that triggered the execution	`params.bucketID`
ID of the object that triggered the execution	`params.objectID`
URI of the object that triggered the execution	`params.uri`

Here, you can get the information of the object that triggered the execution (i.e., the object being created, updated, or deleted). If the object is created or updated, you can get its key-value pairs by creating an object instance with its ID/URI and by refreshing it. The key-value pairs you can get is after the object creation or update (you cannot get the key-value pairs before the creation or update).

The format of the value set in the params.uri depends on the object's scope:

Application Scope: kiicloud://buckets/<bucketID>/objects/<objectID>
Group Scope: kiicloud://groups/<groupID>/buckets/<bucketID>/objects/<objectID>
User Scope: kiicloud://users/<userID>/buckets/<bucketID>/objects/<objectID>
Thing Scope: kiicloud://things/<thingID>/buckets/<bucketID>/objects/<objectID>

Parameters for a group-related trigger and how server code can get them:

Event parameters	How to get the parameter values?
ID of the group that triggered the execution	`params.groupID`
URI of the group that triggered the execution	`params.uri`
IDs of an added/removed group member that triggered the execution (reported only when the trigger was the group member addition/deletion)	`params.members`
IDs of a member who failed be added/removed when the execution is triggered (reported only when the trigger was the group member addition/deletion)	`params.failed`

The format of the value set in the params.uri is kiicloud://groups/<groupID>.

Parameters for a user-related trigger and how server code can get them:

Event parameters How to get the parameter values?

ID of the user that triggered the execution params.userID

URI of the user that triggered the execution params.uri

The format of the value set in the params.uri is kiicloud://users/<userID>.

Parameters for a thing-related trigger and how server code can get them:

Event parameters	How to get the parameter values?
ID of the thing that triggered the execution	`params.thingID`
ID of the vendorThingID that triggered the execution (reported only when the trigger was the thing creation)	`params.vendorThingID`
URI of the thing that triggered the execution	`params.uri`
ID of the user added or removed from a thing owner (reported only when the trigger was the thing owner addition/removal)	`params.userID`
ID of the group added or removed from a thing owner (reported only when the trigger was the thing owner addition/removal)	`params.groupID`
The updated fields and their values (reported only when the trigger was the thing field updates)	`params.values`
A boolean value to tell if the MQTT disconnection was graceful or not. True if the disconnection was graceful. False otherwise. (reported only when the thing is disconnected)	`params.expected`

The format of the value set in the params.uri is kiicloud://things/<thingID>.

In the params.values, the added/updated fields are passed in a JSON format. The deleted fields will have null in the JSON.

Suppose, for example, that the following field updates were made on a thing.

Added the field "_lot" with the value "LOT_12345".
Updated the field "_firmwareVersion" with the value "updated_version".
Add the custom field "custom_field_1" with the value "new_value_1".
Updated the custom field "custom_field_2" with the value "updated_value_2".
Remove the custom field "custom_field_3".

The param.values will then have the following JSON data.

{
    "_lot": "LOT_12345",
    "_firmwareVersion": "updated_version",
    "custom_field_1": "new_value_1",
    "custom_field_2": "updated_value_2",
    "custom_field_3": null
}

Parameters for an installation-related trigger and how server code can get them:

Event parameters	How to get the parameter values?
ID of the user who installed/uninstalled his/her device (for FCM or APNs)	`params.userID`
ID of the thing installed/uninstalled (for MQTT)	`params.thingID`
ID of the device installation/uninstallation that triggered the execution. This is not the value of Installation Registration ID but the value of Installation ID.	`params.installationID`
URI of the device installation/uninstallation that triggered the execution	`params.uri`

The format of the value set in the params.uri is kiicloud://installations/<installationID>.

The second argument context is used to get the application-related parameters.
- Use the getAppID method to get the AppID.
- Use the getAppKey method to get the AppKey.
- Use the getAccessToken method to get the access token that was specified in the request that executed the server code. If a trigger is a bucket update, for example, you will get an access token of the user who has made an update on the bucket.
  - By executing the login with the access token, you can run server code on behalf of this user (See the sample code in User who manually executes server code).
  - You can also use this method to determine if server code is invoked by a logged-in user or by an anonymous user. The valid access token will be returned in the former case while null will be returned in the latter case.
- Use getAppAdminContext method to get the app admin context (KiiAppAdminContext). You can execute user and group operations as an app admin with this context (See the sample code in Administrator).
The third argument done is a callback function for finishing asynchronous server code. The value passed to this callback function will be ignored. See Asynchronous execution for more details.

When server code is executed with a trigger-based hook, the return value from the server code has little meaning. The value specified in the return statement (for synchronous code) and the value passed to the done function (for asynchronous code) will be thus ignored.

Determine how an endpoint is executed

By invoking the context.isInvokedByHook(), you can check if an endpoint is executed by a trigger-based hook. This method returns true only if an endpoint is executed by a trigger-based hook.

How an endpoint is executed	Value of context.isInvokedByHook()
Manual execution	false
Trigger-based hook	true
Schedule-based hook	false
Thing-IF Trigger	false

The method is useful for returning an error when an endpoint registered in a trigger-based hook is unexpectedly executed by other means such as manual execution.

function myFunction(params, context, done) {
  if (!context.isInvokedByHook()) {
    done("ERROR: The endpoint can only call by server triggers.");
    return;
  }
  // Do somethig.
  done("SUCCESS");
}

Event parameters	How to get the parameter values?
ID of the user that triggered the execution	`params.userID`
URI of the user that triggered the execution	`params.uri`