Работа со статусами заявок и других объектов

Демо компонента переключения статусов некой сущности - https://demo.web-automation.ru/list/watch/upravlenie-statusom-nekoego-ob-ekta---113

или компактный режим (data-compact=1): 

Введение в сущности

Сущность - это некий объект, который должен иметь возможность последовательно менять свой статус.

При этом возможна реализация разграничения полномочий на смену статуса между ролями. А также автоматизация дополнительных функционалов при смене статуса сущностью (например, отправка уведомлений, формирование неких других объектов, добавление комментариев, и т. д.).

В системе автоматически ведется лог изменения статусов сущности.

Реализация механизма Сущности

Будем рассматривать на примере. Допустим есть такой объект в нашей системе как Проект. Мы хотим реализовать Проект как Сущность.

1. Создание новой сущности, описание возможных статусов

В меню Компоненты / Статусы добавим запись о новой сущности Проект, указав её код project. При этом в БД добавится новая запись в системную таблицу as_en_entities.

Далее перейдем на страницу со статусами новой сущности и добавим там последовательно все необходимые статусы. Физически статусы сущности хранятся в системной таблице as_en_statuses.

При добавлении статуса указывается его код, желательно уникальный в системе, чтобы не перепутать его со статусом имеющим такое же название для какой-то другой сущности в системе.

Обязательно указывайте номер по порядку для статуса, а также цвет.

Далее необходимо заполнить возможные переходы из каждого статуса в меню Доступные статусы.

Например, из статуса Черновик проект можно перевести только в статус Опубликован, либо в Аннулирован. Причем право на выполнение этого перехода есть только у роли customer. На кнопках выбора следующих статусов будет написано соответственно Опубликовать и Аннулировать.

2. Экземпляры сущности

Сама сущность Проект - это одна запись в таблице as_en_entities с кодом project.

Экземпляры сущности, например, Проект №1, Проект №2, Проект №3, и т. д., будут храниться в таблице as_en_entityInstances.

В первом пункте мы создали сущность Проект. Необходимо теперь привязать это понятие к нашим проектам в базе данных. Делается это следующим образом.

Допустим наши проекты и вся информация по ним лежит в таблице au_projects. Теперь необходимо добавить в эту таблицу еще одно поле - instanceID. Это будет внешний ключ к таблице as_en_entityInstances. Таким образом, создастся связь типа “один к одному” между au_projects и as_en_entityInstances.

3. Добавление нового экземпляра сущности

Самый простой способ создания нового экземпляра сущности - это реализация FastCreate в таблице с перечнем экземпляров данной сущности.

Например, в таблице проектов projects быстрым созданием по названию будет создаваться новый проект. При этом необходимо в crud_projects_fastCreate прописать вставку новой записи не только в au_projects, но и предварительно вставку новой записи в as_en_entityInstances. И только потом с полученным новым instanceID вставлять новую запись в au_projects.

4. Страница экземпляра сущности

Для формирования страницы для работы с отдельным экземпляром сущности необходимо предварительно создать форму объекта, который выступает сущностью. Форма объекта, как обычно, будет содержать поля объекта для просмотра или редактирования.

В нашем случае создадим форму entityProject для управления полями объекта Проект.

После этого создадим страницу для экземпляра сущности, на которой расположим сниппеты:

• Обычный сниппет формы:
  

  <div class="as-form" data-code="{formCode}" data-itemid="falcon-space--rabota-s-sushchnostyami"></div>

• Cниппет для управления статусами экземпляра сущности:
  

  <div class="as-entity" data-code="{entityCode}" data-itemid="falcon-space--rabota-s-sushchnostyami" data-type="item" data-compact="1"></div>

5. Переход от страницы с перечнем сущностей к странице с выбранным экземпляром

Очень важно правильно настроить переход на страницу выбранного экземпляра сущности из таблицы с перечнем. Тут есть следующий нюанс.

Когда вы делаете одну из колонок таблицы ссылкой на страницу экземпляра, то под видом itemID следует передавать не id из проектной таблицы экземпляров, а именно instanceID.

6. Логирование смены статусов

Запись о смене статуса в лог as_en_statusesLog производится автоматически только в случае естественного перевода экземпляра в следующий статус - нажатием пользователем соответствующей кнопки перевода в статус.

Если где-либо вы программно прописываете реализацию принудительного перехода экземпляра в статус, то не забывайте также вставлять соответствующую запись в as_en_statusesLog.

7. Таблицы БД 

Это все таблицы с префиксом as_en_

Хранимые процедуры для работы с сущностями

Процедура ДО изменения статуса

Процедура en_{entityCode}_checkStatus вызывается для выполнения необходимых проверок перед сменой статуса у экземпляра сущности.

CREATE PROCEDURE [dbo].[en_example_checkStatus]
	@instanceID int,
	@fromStatusCode nvarchar(32),
	@toStatusCode nvarchar(32),	
	@username nvarchar(32)
AS
BEGIN
	-- check can change status for entity
	-- if SoftMode = 1,  then show alert, but user can change status 
	declare @id int = 1 -- test
	
	if(@id>0)
	begin 
		select 'Please confirm action' Msg, 1 Result, 0 SoftMode
	end else
	begin
		select 'Some message about problem, Confirm?' Msg, 0 Result, 1 SoftMode
	end	
END

На входе:

• @instanceID - ID экземпляра сущности,
• @fromStatusCode - какой был статус до изменения,
• @toStatusCode - каким стал статус после изменения статуса,
• @username - текущий пользователь.

На выходе:

SELECT 1 msg, result, bit softMode, withoutConfirm, okButtonStyle, okButtonText, cancelButtonStyle, cancelButtonText.

Параметр softMode:

• Если softMode = 1, то это означает, что ограничение является нежестким и можно по подтверждению все равно сменить статус.
• Если softMode = 0, то в случае невозможности сменить статус, идет сообщение об этом, без возможности принудительно сменить статус.

withoutConfirm - если 1, то подтверждение операции не будет запрошено у пользователя (по умолчанию 0)

okButtonText,cancelButtonText - задают текст кнопки для Отмены и для Подтверждения действия.

okButtonStyle, cancelButtonStyle - задают стиль кнопки. Значения - danger, warning,success, secondary, primary, info, light

Процедура ПОСЛЕ изменения статуса

Процедура en_{entityCode}_afterChangeStatus вызывается после успешной смены статуса у экземпляра сущности.

CREATE PROCEDURE [dbo].[en_example_afterChangeStatus]
	@instanceID int,
	@statusCode nvarchar(32),
	@username nvarchar(32)
AS
BEGIN
	-- call after change status (logging, notification, ...)

	-- SELECT 1
	Select '' Msg, 1 Result

	-- SELECT 2 Outer actions	
END

На входе:

• @instanceID - ID экземпляра сущности,
• @statusCode - статус сущности,
• @username - текущий пользователь.

На выходе:

SELECT 1:

• msg,
• result,
• icon - задает иконку в окне результата (например, 'fa-code'),
• refreshContainer (после смены статуса идет обновление некоего контейнера на странице, чей селектор указан в параметре),
• redirectUrl (если указан, то после смены статуса пользователь перенаправляется на указанную страницу).

SELECT 2: вызовы внешних действий (почта, смс, уведомление и т.д.). См. вызов внешних действий.

Например, в эту процедуру удобно вставить вызов процедуры для формирования уведомлений участникам операции в системе, либо автоматизацию формирования каких-либо документов.

На клиентскую сторону (в коллбек afterChangeStatus) передаются параметр Msg из хранимки (если непустой) и параметр AdditionalData как результат выполнения внешних действий.  

Процедура вывода дополнительной панели для статуса

Процедура en_{entityCode}_getStatusAdditionalToolbar содержит в себе вывод дополнительной разметки под кнопками переходов в доступные статусы.

CREATE PROCEDURE [dbo].[en_example_getStatusAdditionalToolbar]
	@instanceID int,
	@entityCode nvarchar(32),
	@statusCode nvarchar(32),	
	@username nvarchar(32),
	@langID int = 1
AS
BEGIN
	-- add makeup under status buttons (additional actions for current status)
	select '' Msg, 1 Result
END

На входе:

• @instanceID - ID экземпляра сущности,
• @entityCode - код сущности,
• @statusCode - статус сущности,
• @langID - текущий язык,
• @username - текущий пользователь.

На выходе:

SELECT 1 msg, result

В данном случае msg содержит строку разметки дополнительной панели.

Например, когда проект будет переведен в статус Выполнен, можно добавить в дополнительную панель кнопку “Добавить отзыв”. Тогда msg должна содержать, к примеру, вызов модальной формы на добавление отзыва исполнителю проекта.

CREATE PROCEDURE [dbo].[en_project_getStatusAdditionalToolbar]
	@instanceID int,
	@entityCode nvarchar(32),
	@statusCode nvarchar(32),
	@username nvarchar(32),
	@langID int = 1
AS
BEGIN
	if @statusCode = 'done'
           SELECT 'Добавить отзыв' Msg,
                   1 Result
        else
           SELECT '' Msg, 0 Result
END

Хранимая процедура вывода доступных статусов

По умолчанию используется стандартная процедура as_en_getAvailableStatusesForInstance.

Если вам необходима своя процедура, то вы устанавливаете режим Кастомная процедура AvailStatuses = ДА (поле useCustomStatusSP в таблице as_en_entities) и реализуете процедуру en_{entityCode}_getAvailableStatusesForInstance (столбец SQL доступных статусов). 

Как выглядит процедура по умолчанию: 

CREATE PROCEDURE [dbo].[en_example_getAvailableStatusesForInstance]
	@entityCode nvarchar(256),
	@instanceID int,	
	@username nvarchar(32)
AS
BEGIN
	-- custom SP for show additional statuses for entity with entityCode
	
	-- SELECT 1
	select *, as_en_statuses.id StatusID ,
		(case isnull(buttonTitle,'') when '' then as_en_statuses.name else buttonTitle end ) Name
	from as_en_availableStatuses inner join as_en_statuses on as_en_statuses.id = as_en_availableStatuses.availableStatusID
	where 
		currentStatusID in (select statusID from as_en_entityInstances 
			where id = @instanceID and entityID in (select id from as_en_entities where code = @entityCode) 
		) 
		and ( ( isnull(users, '') ='' and isnull(roles, '') ='' ) or dbo.sec_hasAccessByUsersRoles(@username, users, roles) = '1')

END

На входе:

• @instanceID - ID экземпляра сущности,
• @entityCode - код сущности,
• @username - текущий пользователь.

На выходе:

SELECT 1 Модель статуса  StatusID, Code, Name, Color, Ord

Как сделать JS коллбек после смены статуса 

Для этого объявляем функцию 

$(function(){
   as.entitycallbacks["{entityCode}_afterChangeStatus"]=function(data, params){
       // data - то что пришло от сервера, params - code, itemID, statusCode
   }
});

Обновление апрель 2021. Вместо объекта  as.entity.callbacks теперь используется as.entitycallbacks

Компактный режим отображения статусов

В этом случае кнопки действий по смене статусов прячутся в подменю. 

Для этого в сниппете используем data-compact="1". 

Дополнительные настройки для компактного режима (в as.systemOptions):

• "entity.dropdownActionsTitle": "Поменять статус" - заголовок окна в подменю (если нужно спрятатать, то ставим пробел ' '),
• "entity.dropdownStatusLabelSize" : "xs" - размер кнопки статуса (xs, sm, ld, md).