Creating Own Activities

User-defined activities are created in the folder /bitrix/activities/custom/ from the website root. Each activity is located in a separate folder. The folder name must be written in lower case letters.

The activity folder must contain an activity class file. The name of the activity class file (in our example it will be myactivity) must coincide with the activity folder name (in our example, /bitrix/activities/custom/myactivity/), but without the first characters “CBP,” and have a php extension. Also, the activity folder may contain other files required for the activity. E.g., a file with activity description, files with activity localization, images, resource files, etc.

The structure of the activity folder is generally similar to the component structure:

.description.php - description of future activity;
properties_dialog.php - form for activity settings;
myactivity.php – activity code;
icon.gif – the icon to display the activity in the general list;
/lang/en/ – contains folders with language messages. The names of the folders must be consistent with the language IDs, e.g., de, en. Each folder contains files with phrases named after corresponding activity files:

.description.php - description of language messages;
myactivity.php – language messages proper.

The file .description.php contains an activity required for proper operation of the system. The activity description file must contain a code similar to the following:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

$arActivityDescription = array(
	"NAME" => GetMessage("MYACTIVITY_DESCR_NAME"),
	"DESCRIPTION" => GetMessage("MYACTIVITY_DESCR_DESCR"),
	"TYPE" => "activity",
	"CLASS" => "MyActivity",
	"JSCLASS" => "BizProcActivity",
	"CATEGORY" => array(
		"ID" => "other",
	),
);
?>

Here, the activity type is determined in the TYPE element which must have two possible values: activity for activities and condition for conditions. Also, the activity name and description, JavaScript class for rendering in a visual editor, category, etc. are set.

The subfolder lang of the activity folder contains files with the localization of activity phrases into different languages.

The activity class file looks similar to the following:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true) die();

class CBPMyActivity
	extends CBPActivity
{
	public function __construct($name)
	{
		parent::__construct($name);
		// Determine the property of the action MyText
		// It can be set in the visual editor when
 		// placing the action in the business process template
		$this->arProperties = array("Title" => "", "MyText" => "");
	}

	// Executable method of the activity
	public function Execute()
	{
		// The essence of the activity – writing of a property value into the file
		if (strlen($this->MyText) > 0)
		{
			$f = fopen($_SERVER["DOCUMENT_ROOT"]."/dump.txt", "a");
			fwrite($f, $this->MyText);
			fclose($f);
		}

		// Return the instruction that the activity is terminated to the executing system
		return CBPActivityExecutionStatus::Closed;
	}

	// The static method returns the HTML code of the action property setting 
// dialog in the visual editor. If the action has no 
// properties, this method is unnecessary
	public static function GetPropertiesDialog($documentType, $activityName,
 		$arWorkflowTemplate,$arWorkflowParameters, $arWorkflowVariables,
 		$arCurrentValues = null, $formName = "")
	{
		$runtime = CBPRuntime::GetRuntime();

		if (!is_array($arWorkflowParameters))
			$arWorkflowParameters = array();
		if (!is_array($arWorkflowVariables))
			$arWorkflowVariables = array();

		// If the dialog opens for the first time, we upload the value
 	// of the property which was saved in the business process template
		if (!is_array($arCurrentValues))
		{
			$arCurrentValues = array("my_text" => ""); 

			$arCurrentActivity= &CBPWorkflowTemplateLoader::FindActivityByName(
 				$arWorkflowTemplate,
 				$activityName
 		);
			if (is_array($arCurrentActivity["Properties"]))
				$arCurrentValues["my_text "] =
 $arCurrentActivity["Properties"]["MyText"];
		}

		// The code that generates the dialog is located in a separate file
		// properties_dialog.php in the activity folder.
		// We return this code.
		return $runtime->ExecuteResourceFile(
			__FILE__,
			"properties_dialog.php",
			array(
				"arCurrentValues" => $arCurrentValues,
				"formName" => $formName,
			)
		);
	}

	// The static method receives the values entered in the property setting 
// dialog and saves them in the business process template. If the activity 
// has no properties, this method is unnecessary.
	public static function GetPropertiesDialogValues($documentType, $activityName, 
		&$arWorkflowTemplate, &$arWorkflowParameters, &$arWorkflowVariables,
 	 	$arCurrentValues, &$arErrors)
	{
		$arErrors = array();

		$runtime = CBPRuntime::GetRuntime();

		if (strlen($arCurrentValues["my_text "]) <= 0)
		{
			$arErrors[] = array(
				"code" => "emptyCode",
				"message" => GetMessage("MYACTIVITY_EMPTY_TEXT"),
			);
			return false;
		}

		$arProperties = array("MyText" => $arCurrentValues["my_text "]);

		$arCurrentActivity = &CBPWorkflowTemplateLoader::FindActivityByName(
 			$arWorkflowTemplate,
 			$activityName
 		);
		$arCurrentActivity["Properties"] = $arProperties;

		return true;
	}
}
?>

The code located in the file properties_dialog.php which generates activity setting dialog in the visual editor may look like the following:

<?if (!defined("B_PROLOG_INCLUDED") || B_PROLOG_INCLUDED!==true)die();
?>
<tr>
	<td align="right" width="40%"><span style="color:#FF0000;">*</span> :</td>
	<td width="60%">
		<textarea name="my_text" id="id_my_text " rows="5" cols="40"><?= htmlspecialchars($arCurrentValues["my_text"]) ?></textarea>
		<input type="button" value="..." onclick="BPAShowSelector('id_my_text', 'string');">
	</td>
</tr>

The user can introduce an explicit value in the my_text or select one of the values using the dialog that opens using the button . In the second case, the user can establish that the property value of the root activity set as an input parameter upon launching the business process is the property value.

Bitrix Framework