Настройка REST роботов (действий) через приложение (встройку)

Описание

С версии 20.0.600 модуля Бизнес-процессы появилась возможность настраивать робота/действие, используя интерфейс приложения. Реализована стандартным механизмом встройки rest.placement.

Реализация на примере приложения

Рассмотрим реализацию на конкретном примере приложения (полный код приложения представлен в следующем табе страницы).

В нашем примере приложение добавляет робота, у которого есть 2 параметра типа Строка:

var params = {
	'CODE': 'robot',
	'HANDLER': 'http://handler.com',
	'AUTH_USER_ID': 1,
	'NAME': 'Пример робота-встройки',
	'USE_PLACEMENT': 'Y',
	'PLACEMENT_HANDLER': 'http://handler.com',
	'PROPERTIES': {
		'string': {
			'Name': 'Параметр 1',
			'Type': 'string'
		},
		'stringm': {
			'Name': 'Параметр 2',
			'Type': 'string',
			'Multiple': 'Y',
			'Default': ['value 1', 'value 2']
		},
	}
};
BX24.callMethod(
	'bizproc.robot.add',
	params,
	function(result)
	{
		if(result.error())
			alert("Ошибка: " + result.error());
	}
);

Для того, чтобы параметры можно было настраивать через приложение, при добавлении робота передаем параметры USE_PLACEMENT=Y и обработчик PLACEMENT_HANDLER.

Останется написать обработчик встройки, задача которого отрисовать параметры и сохранить их значения. Для этого в обработчик в PLACEMENT_OPTIONS мы передаем данные:

code — код вашего робота при регистрации
activity_name — идентификатор действия в шаблоне бизнес-процесса
properties — список свойств и их описание
current_values — текущие значения свойств
document_type — тип документа, над которым идет настройка
document_fields — список полей документа
template — список доступных полей шаблона (в коробке Битрикс24 доступно с версии 24.200.0)
Для параметра template доступны элементы:
- parameters — список параметров шаблона
- variables — список переменных шаблона
- constants — список констант шаблона
- global_variables — список глобальных переменных
- global_constants — список глобальных констант
- return_activities — список действий (роботов), которые генерируют дополнительные результаты
При этом, структура свойств в этих списках приведена к единому формату и представляет из себя структуру:
```
{
    Id: строка, идентификатор (код) свойства
    Type: строка, идентификатор типа свойства

    Name: строка, название
    Description: строка, описание

    Multiple: булевое, множественное свойство или нет
    Required: булевое, обязательное свойство или нет

    Options: смешанное. Зависит от типа свойства
    Settings: список настроек. Зависит от типа свойства
    Default: смешанное. Значение по умолчанию для свойства
}
```
Список return_activities состоит из списка действий, которые возвращают результаты и их свойства. Имеет структуру:
```
{
    Id: строка, идентификатор действия в шаблоне
    Type: строка, тип действия
    Title: строка, название действия в шаблоне
    Return: список, доступные свойства
}
```

В приложение все это приходит так:

Осталось сделать верстку и научиться сохранять параметры непосредственно в Робота. Для этого мы используем функцию setPropertyValue, которая доступна нам через BX24.placement.call.

BX24.placement.call(
	'setPropertyValue',
	{string: 'test string'}
)

В качестве параметров передаются ID свойства и значения. Можно передавать несколько значений свойств, например:

BX24.placement.call(
	'setPropertyValue',
	{string: 'test string', stringm: ['test2', 'test3']}
)

Далее пользователь сохраняет робота как обычно.

Так это выглядит в Роботах:

А так в дизайнере бизнес-процессов:

Примечание: Белая область — встройка (фрейм приложения).

Полный код приложения

<?php
header('Content-Type: text/html; charset=UTF-8');

$protocol = $_SERVER['SERVER_PORT'] == '443' ? 'https' : 'http';
$host = explode(':', $_SERVER['HTTP_HOST']);
$host = $host[0];

define('BP_APP_HANDLER', $protocol.'://'.$host.explode('?', $_SERVER['REQUEST_URI'])[0]);
?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title></title>
</head>
<body>
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css" integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T" crossorigin="anonymous">
<script src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js" integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM" crossorigin="anonymous"></script>
<script src="//api.bitrix24.com/api/v1/"></script>
<?if (!isset($_POST['PLACEMENT']) || $_POST['PLACEMENT'] === 'DEFAULT'):?>
<h1>Робот-встройка</h1>
<div class="container-fluid">
<div class="container-fluid">
		<h2>Робот</h2>
		<button onclick="installRobot();" class="btn btn-primary">Установить</button> вЂ“
		<button onclick="uninstallRobot();" class="btn btn-danger">Удалить</button>
	</div>
	<hr/>
	<div class="container-fluid">
		<button onclick="getList();" class="btn btn-light">Получить список установленных роботов</button>
	</div>
</div>
<script type="text/javascript">
	document.body.style.display = 'none';
	BX24.init(function()
	{
		document.body.style.display = '';
	});

	function installRobot()
	{
		var params = {
			'CODE': 'robot',
			'HANDLER': '<?=BP_APP_HANDLER?>',
			'AUTH_USER_ID': 1,
			'NAME': 'Пример робота-встройки',
			'USE_PLACEMENT': 'Y',
			'PLACEMENT_HANDLER': '<?=BP_APP_HANDLER?>',
			'PROPERTIES': {
				'string': {
					'Name': 'Параметр 1',
					'Type': 'string'
				},
				'stringm': {
					'Name': 'Параметр 2',
					'Type': 'string',
					'Multiple': 'Y',
					'Default': ['value 1', 'value 2']
				},
			}
		};

		BX24.callMethod(
			'bizproc.robot.add',
			params,
			function(result)
			{
				if(result.error())
					alert("Ошибка: " + result.error());
				else
					alert("Успешно");
			}
		);
	}

	function uninstallRobot()
	{
		BX24.callMethod(
				'bizproc.robot.delete',
				{
					'CODE': 'robot'
				},
				function(result)
				{
					if(result.error())
						alert('Ошибка: ' + result.error());
					else
						alert("Успешно");
				}
		);
	}

	function getList()
	{

		BX24.callMethod(
			'bizproc.robot.list',
			{},
			function(result)
			{
				if(result.error())
					alert("Ошибка: " + result.error());
				else
					alert("Коды установленных роботов: " + result.data().join(', '));
			}
		);
	}

</script>
<?php else:?>
	<form name="props" class="container-fluid">
<?php
$options = json_decode($_POST['PLACEMENT_OPTIONS'], true);

foreach ($options['properties'] as $id => $property)
{
	$multiple = isset($property['MULTIPLE']) && $property['MULTIPLE'] === 'Y';
	$val = (array) $options['current_values'][$id];
	if (!$val)
	{
		$val[] = '';
	}

	if ($multiple)
	{
		$val[] = '';
	}

	$name = $multiple ? $id.'[]' : $id;
	?>
	<div class="form-group">
		<label><?=htmlspecialchars($property['NAME'])?>:</label>
		<?foreach ($val as $v):?>
		<p><input name="<?=$name?>" value="<?=htmlspecialchars((string)$v)?>" class="form-control" onchange="setPropertyValue('<?=$id?>', this.name, <?=(int)$multiple?>)"></p>
		<?endforeach;?>
	</div>
	<?
}
?>
		<script>
			function setPropertyValue(name, inputName, multiple)
			{
				var form = new FormData(document.forms.props);
				var value = multiple? form.getAll(inputName) : form.get(inputName);
				var params = {};
				params[name] = value;

				BX24.placement.call(
					'setPropertyValue',
					params
				)
			}
		</script>
	</form>
<?php endif;?>
</body>
</html>