process_trigger (POST)

Purpose

Execute the code associated to a trigger and retrieve the produced output data.


Input parameters

  • id: Function identifier for the trigger, as returned by the get_function_info command in the id parameter.
  • data: A JSON object with the following format:

    {
"form_data":{
"city":"Tokyo"
},
"saved_data":"...",
"authentication":{
"user_id":"theUser",
"auth_saved_data":"..."
}
}
  • form_data: The trigger configuration data as supplied by the user via the trigger configuration form. See the Configuring tasks with forms section for details.
  • saved_data: The data returned by the trigger in the data_to_save element (see “Output data” below) in the last execution of process_trigger for the same trigger in the same task. If it is the first time that the trigger is invoked for the current task, or the last execution of the trigger did not include a data_to_save element in the output data, this element will not be present.
  • authentication: User authentication related information. This element will be present only if the enclosing application requires user authentication (get_app_info returns a value different from “none” for the user_auth_mode element):
    • authentication/user_id: The currently authenticated user identifier, as returned in the user_id element by the authenticate_user or the end_authenticate_user command.
    • authentication/auth_saved_data: The authentication information associated to the currently authenticated user, as returned in the auth_data_to_save element by the authenticate_user or the end_authenticate_user command.

    • Output data

    A JSON object with this format:

    {
"status_code":"0",
"status_message":"Ok",
"output_data":{
"text":"Hello world",
"link":"http://www.botize.com"
},
"data_to_save":"...",
}

    • status_code: A numeric code conveying information about the function execution result. See “Notes” below.
    • status_message: A human-readable message that contains more information about the function execution result.
    • output_data: The data produced by the trigger execution. The names and types of the variables contained in this element must be consistent with the variable definitions returned in the trigger_data/output_vars element by the get_function_info command.
    • data_to_save: Any data that the trigger code needs to be saved for the next execution. The value returned in this element will be passed unmodified in the saved_data element of the data parameter in the next execution of process_trigger for the same trigger in the same task.

    Notes

    After the execution of the trigger finishes, and if the returned status code is in the appropriate range (see below), Botize will invoke the action of the task, passing in the variables returned in output_data. See the Workflow of a task execution section for details.

    This command should return a value of 500 for the HTTP status code only if an unexpected error occurs in the server (such as an unhandled exception). Errors that are not produced directly by the trigger code (for example, a third party service is not available, or the user authorization for the third party service has been revoked), the command should finish successfully at the HTTP level, and return the appropriate error information via the status_code and status_message elements of the output data.

    How concrete error conditions are mapped to status codes is application specific, however Botize will behave differently depending on the following numeric ranges for the codes:

    • 0: Success. Botize will execute the action of the task. The status message will be ignored.
    • 1-99: Warning. Botize will execute the action of the task, but the status message will be stored so that it can be later checked by the user that has created the task (the same is true for all status codes except 0).
    • 100-199: Temporary failure. Botize will NOT execute the action of the task, but the task will not be deactivated, or will be deactivated only if the failure persists.
    • 200-299: Permanent failure. Botize will NOT execute the action of the task; moreover, the task will be deactivated (that is, it will not be executed again until the user manually reactivates it).

    If 100 status codes for each category are not enough, add 1000 to get a new range of status codes with the same meaning. For example, 1001-1099 and 2001-2099 are warnings, 1100-1199 and 2100-2199 are temporary failures, etc.


    do_action »