Status handlers

In this topic

Introduction
File handlers
Available variables

Introduction

A result must have a definite status assigned to it. When creating a result, it must be assigned a default status that has an option "Assign this status to all new documents" set (only one status can have this option set). During its lifetime, the status of a result may change.

To intercept and process such changes of status, the Web Form module enables a developer to provide the status handler file. A handler can call any system function to perform the desired action; for example:

create mail events to send e-mail messages;
move a user who changed the status to a different user group (e.g. to grant access to other sections of the site);
other actions.

File handlers

File handlers are PHP scripts included when a status changes. They can be located in any directory from the site root; for example in /bitrix/php_interface/include/form/handlers/.

To specify a file handler, go to the Status parameters page. This page has the following two fields that are required to install file handlers:

File handler to be called when changing this status to another... - this parameter can be set to the file handler path relative to the root. This handler will be called when a result status is changed to some other one. It will also be included when a result in this status is deleted.
File handler to be called when changing a status to this... - this handler will be called when a result status is changed to this one. It will also be included when a new result is created.

Available variables

The handler specified in the field "File handler to be called when changing this status to another..." can use the following variables.

Variable	Description
$CURRENT_STATUS_ID	The ID of the current status (before it is changed).
$NEW_STATUS_ID	The ID of the new status.
$RESULT_ID	The ID of the result that is changing its status.
$arResult	Array describing the result fields.
$ACTION	The symbolic code of the action which is to be performed: UPDATE - the result is modified; SET_STATUS - the result status has been changed directly (e.g. using the status list); DELETE - the result is deleted.

The handler specified in the field "File handler to be called when changing a status to this..." can use the following variables.

Variable	Description
$CURRENT_STATUS_ID	The ID of the current status.
$PREV_STATUS_ID	The ID of the previous status.
$RESULT_ID	The ID of the result that is changing its status.
$arResult	Array describing the result fields.
$ACTION	The symbolic code of the action which is to be performed: UPDATE - the result is modified; SET_STATUS - the result status has been changed directly (e.g. using the status list); ADD - the result has just been created.