Работа с потоками бизнес-процессов с помощью кода

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

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

Этот раздел содержит сведения о том, как можно программно работать с потоками бизнес-процессов.

Предварительные требования для потока бизнес-процессов

Пользовательские сущности и сущности с обновленными формами пользовательского интерфейса могут участвовать в потоке бизнес-процессов. В обновленных сущностях пользовательского интерфейса свойство IsAIRUpdated имеет значение true.

Чтобы включить сущность для потока бизнес-процессов, задайте свойству IsBusinessProcessEnabled значение true.

Определение потока бизнес-процессов

Используйте визуальный конструктор потока бизнес-процессов, чтобы определить поток бизнес-процессов. Дополнительные сведения: Создание потока бизнес-процессов

По умолчанию запись потока бизнес-процессов создается в состоянии Draft.

Определение потока бизнес-процессов хранится в сущности workflow, а информация об этапах потока бизнес-процессов — в сущности processstage.

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

Прежде чем использовать поток процессов, его необходимо активировать. Для этого нужна привилегия prvActivateBusinessProcessFlow для сущности Workflow. Используйте сообщение UpdateRequest, чтобы задать для состояния записи сущности Workflow значение Activated. Дополнительные сведения см. в Выполнение специализированных операций с помощью обновления

Сущность потока бизнес-процессов

После активации определения потока бизнес-процесса путем изменения состояния соответствующей записи сущности Workflow или с помощью конструктора потока бизнес-процесса автоматически создается пользовательская сущность, предназначенная для хранения активированных экземпляров потоков бизнес-процессов, со следующим именем: "<activesolutionprefix>_<uniquename>", где uniquename является производным от указанного имени.

Например, если в качестве имени определения потока бизнес-процессов указано My Custom BPF и для активного решения используется издатель по умолчанию, имя настраиваемой сущности, созданной для хранения экземпляров процессов — new_mycustombpf.

Если значение uniquename недоступно для определения потока бизнес-процесса, например если поток бизнес-процесса был импортирован в составе решения из более ранней версии, по умолчанию имя пользовательской сущности будет "<activesolutionprefix>_bpf_<GUID_определения_потока_бизнес-процесса>:

Имя сущности потока бизнес-процессов можно получить с помощью одного из следующих способов:

• С помощью пользовательского интерфейса. Используйте интерфейс настройки для перехода к сущности потока бизнес-процесса:

  

• С помощью веб-API. Используйте следующий запрос:

  запрос

  GET [Organization URI]/api/data/v9.1/workflows?$filter=name eq 'My Custom BPF'&$select=uniquename HTTP/1.1
  

  Ответ

  {  
  "@odata.context":"[Organization URI]/api/data/v9.1/$metadata#workflows(uniquename)",
  "value":[  
       {  
           "@odata.etag":"W/\"1084677\"",
           "uniquename":"new_mycustombpf",
           "workflowid":"2669927e-8ad6-4f95-8a9a-f1008af6956f"
       }
    ]
  }
  
  

• С помощью службы организации. Используйте следующий пример кода:

  QueryExpression query = new QueryExpression
  {
      EntityName = "workflow",
      ColumnSet = new ColumnSet("uniquename"),
      Criteria = new FilterExpression
      {
          Conditions =
          {
              new ConditionExpression
              {
                  AttributeName = "name",
                  Operator = ConditionOperator.Equal,
                  Values = { "My Custom BPF" }
              }
          }
      }
  };
  Workflow Bpf = (Workflow)_serviceProxy.RetrieveMultiple(query).Entities[0]; 
  
  

GET [Organization URI]/api/data/v9.1/EntityDefinitions?$select=SchemaName,LogicalName,DisplayName&$filter=IsBPFEntity eq true HTTP/1.1

Управление безопасностью для потоков бизнес-процессов

Пользовательская сущность, которая создается автоматически при активации потока бизнес-процесса для хранения экземпляров потока бизнес-процесса, соответствует стандартной модели безопасности, как и любая другая пользовательская сущность в Customer Engagement. В ней подразумевается, что привилегии, предоставляемые для этих сущностей, определяют разрешения времени выполнения пользователей для потоков бизнес-процессов.

Настраиваемая сущность потока бизнес-процессов имеет организационную область. Обычные привилегии на создание, извлечение, обновление и удаление для этой сущности определяют разрешение, которое получит пользователь в зависимости от назначенных ему ролей. По умолчанию при создании настраиваемой сущности потока бизнес-процессов доступ к ней получают только роли безопасности Системный администратор и Настройщик системы, и вам нужно явно предоставить разрешения для новой сущности потока бизнес-процессов (например, Мой настраиваемый BPF) другим ролям безопасности, если это необходимо.

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

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

Давайте рассмотрим следующий пример, где используется межсущностный поток бизнес-процессов "Мой настраиваемый BPF" с тремя этапами: S1:Account, S2:Account и S3:Contact.

Извлечение всех записей (экземпляров) для сущности потока бизнес-процессов

Если ваша сущность потока бизнес-процессов имеет имя "new_mycustombpf", используйте следующий запрос, чтобы извлечь все записи (экземпляры процесса) для своей сущности потока бизнес-процессов:

GET [Organization URI]/api/data/v9.1/new_mycustombpfs HTTP/1.1 

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

Создание записи сущности потока бизнес-процессов (экземпляр процесса)

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

(!ПРИМЕЧАНИЕ) При создании записи в едином интерфейсе, если вы не хотите, чтобы с записью был связан поток бизнес-процесса, создайте скрипт onload, который вызывает setActiveProcess, и передайте пустой processID (GUID). Пример кода formcontext.data.process.setActiveProcess('00000000-0000-0000-0000-000000000000', (a)=>{​​alert("changed -- " + a)}​​)

Чтобы создать запись сущности потока бизнес-процессов, необходимо указать следующие значения:

• Свяжите запись сущности потока бизнес-процессов с основной записью, задав свойство навигации с одним значением, используя заметку @odata.bind. Чтобы узнать имя свойства навигации, которое указывает на запись основной сущности определения потока бизнес-процессов, ознакомьтесь с документом CSDL $metadata.

• Свяжите запись сущности потока бизнес-процессов с допустимым этапом, указанным в определении потока бизнес-процессов, задав свойство навигации с одним значением, используя заметку @odata.bind. Чтобы узнать имя свойства навигации (обычно activestageid), которое указывает на запись этапа для определения потока бизнес-процессов, ознакомьтесь с документом CSDL $metadata.

  Кроме того, можно получить сведения обо всех этапах определения потока бизнес-процесса с помощью следующего запроса веб-API, предполагая, что идентификатор определения потока бизнес-процесса — 2669927e-8ad6-4f95-8a9a-f1008af6956f:

  запрос

  GET [Organization URI]/api/data/v9.1/processstages?$select=stagename&$filter=processid/workflowid eq 2669927e-8ad6-4f95-8a9a-f1008af6956f HTTP/1.1
  

  Ответ

  {
      "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#processstages(stagename)",
      "value": [
          {
              "@odata.etag": "W/\"858240\"",
              "stagename": "S1",
              "processstageid": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b"
          },
          {
              "@odata.etag": "W/\"858239\"",
              "stagename": "S3",
              "processstageid": "a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a"
          },
          {
              "@odata.etag": "W/\"858238\"",
              "stagename": "S2",
              "processstageid": "19a11fc0-3398-4214-8522-cb2a97f66e4b"
          }
      ]
  }
  

Затем используйте следующий запрос для создания экземпляра определения потока бизнес-процесса для записи организации (ID=a176be9e-9a68-e711-80e7-00155d41e206) и первого этапа экземпляра процесса — S1 (ID=9a9185f5-b75b-4bbb-9c2b-a6626683b99b) —, установленного в качестве активного этапа:

запрос

POST [Organization URI]/api/data/v9.1/new_mycustombpfs HTTP/1.1 
Content-Type: application/json; charset=utf-8 
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Accept: application/json 

{
    "[email protected]": "/accounts(a176be9e-9a68-e711-80e7-00155d41e206)",
    "[email protected]": "/processstages(9a9185f5-b75b-4bbb-9c2b-a6626683b99b)"    
}

Ответ

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.1/new_mycustombpfs(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Обратите внимание, что если необходимо создать экземпляр определения потока бизнес-процесса, в котором в качестве активного этапа установлен этап, отличный от первого этапа, вы должны также указать в своем запросе traversedpath. Пройденный путь является разделенной запятыми строкой с идентификаторами этапов процессов, представляющих пройденные этапы экземпляра потока бизнес-процессов. Следующий запрос создает экземпляр для записи организации (ID=679b2464-71b5-e711-80f5-00155d513100) со вторым этапом — S2 (ID=19a11fc0-3398-4214-8522-cb2a97f66e4b) — установленным в качестве активного.

POST [Organization URI]/api/data/v9.1/new_mycustombpfs HTTP/1.1 
Content-Type: application/json; charset=utf-8 
OData-MaxVersion: 4.0 
OData-Version: 4.0 
Accept: application/json 

{
    "[email protected]": "/accounts(679b2464-71b5-e711-80f5-00155d513100)",
    "[email protected]": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"   
}

Обновление записи сущности потока бизнес-процессов (экземпляр процесса)

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

Навигация по этапам

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

Для перехода по этапам вам требуется идентификатор экземпляра потока бизнес-процессов, который необходимо обновить. Чтобы получить все экземпляры потока бизнес-процессов, ознакомьтесь с разделом Извлечение всех записей (экземпляров) для сущности потока бизнес-процессов выше.

Если идентификатор экземпляра процесса, который вы хотите обновить, — dc2ab599-306d-e811-80ff-00155d513100, используйте следующий запрос для изменения активного этапа с S1 на S2:

PATCH [Organization URI]/api/data/v9.1/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1
Content-Type: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

{
    "[email protected]": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"
}

Изменение состояния экземпляра процесса: "Прервать", "Активировать повторно" или "Готово"

Экземпляр процесса может находиться в одном из следующих состояний: Активно, Готово или Прервано. Состояние определяется следующими атрибутами записи экземпляра процесса:

• stateCode. Отображает состояние экземпляра процесса.

  Ценность	Этикетка
  0	Active
  1	Неактивное

• statusCode. Отображает сведения о состоянии экземпляра процесса.

  Ценность	Этикетка
  1	Active
  2	Готово
  3	Прервано

Таким образом, чтобы прервать выполнение экземпляра процесса, используйте следующий запрос, задайте значения statecode и statuscode соответствующим образом:

PATCH [Organization URI]/api/data/v9.1/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1   
Content-Type: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 
  
{ 
    "statecode" : "1", 
    "statuscode": "3" 
}

Аналогичным образом, чтобы снова активировать экземпляр процесса, замените значения statecode и statuscode в приведенном выше коде значениями 0 и 1 соответственно.

Наконец, чтобы задать экземпляру процесса состояние Готово, что возможно только на последнем этапе выполнения экземпляра процесса, замените значения statecode и statuscode в коде выше значениями 0 и 2 соответственно.

Навигация между сущностями

Для навигации между сущностями в этом примере необходимо установить последний этап — S3 (ID=a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a) — в качестве активного этапа экземпляра процесса, обновить пройденный путь соответствующим образом и задать запись контакта в качестве основной записи сущности в соответствии с определением потока бизнес-процесса.

PATCH [Organization URI]/api/data/v9.1/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1   
Content-Type: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 
  
{
    "[email protected]": "/processstages(a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b,a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a",
    "[email protected]": "/contacts(0e3f10b0-da33-e811-80fc-00155d513100)"
}

Удаление записи сущности потока бизнес-процессов (экземпляр процесса)

Используйте следующий запрос веб-API:

запрос

DELETE [Organization URI]/api/data/v9.1/new_mycustombpfs(dc2ab599-306d-e811-80ff-00155d513100) HTTP/1.1

Ответ

Если запись существует, вы получите обычный ответ с состоянием 204, что указывает на то, что операция удаления прошла успешно. Если сущность не найдена, вы получите ответ с состоянием 404.

Использование сообщений RetrieveProcessInstances и RetrieveActivePath

Используйте сообщение RetrieveProcessInstances (функция RetrieveActivePath или RetrieveProcessInstancesRequest), чтобы получить все экземпляры потока бизнес-процесса для записи сущности по всем определениях бизнес-процессов. Экземпляры потока бизнес-процессов, возвращаемые для сущности, упорядочиваются в зависимости от атрибута modifiedon экземпляра. Например, последний измененный экземпляр потока бизнес-процесса будет первой записью в возвращаемой коллекции. Последний измененный экземпляр потока бизнес-процессов является активным в пользовательском интерфейсе для записи сущности.

Каждая запись экземпляра потока бизнес-процессов, возвращенная для записи сущности в результате использования сообщения RetrieveProcessInstances, содержит идентификатор активного этапа в атрибуте processstageid, который может использоваться для поиска активного этапа и перехода к следующему или предыдущему этапу. Для этого сначала необходимо найти активный путь экземпляра потока бизнес-процесса и этапы, доступные в экземпляре потока процесса,, с помощью сообщения RetrieveActivePath (функция RetrieveActivePath или RetrieveActivePathRequest).

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

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

Применение потока бизнес-процессов во время создания записи сущности

Этот раздел содержит информацию о поведении по умолчанию для автоматического применения потоков бизнес-процессов к новым записям сущности, созданным в Customer Engagement, а также о том, как их переопределить, чтобы применить выбранные потоки бизнес-процессов к новым записям сущности.

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

1. Определите все потоки бизнес-процессов, применимые к новой записи сущности, основываясь на атрибуте Workflow.PrimaryEntity записей определения потока бизнес-процесса.
2. Определите потоки бизнес-процессов, к которым текущий пользователь имеет доступ. Дополнительные сведения о том, как определяется и контролируется доступ к потоку бизнес-процессов, см. выше в разделе Управление безопасностью для потоков бизнес-процессов.
   
3. Все определения потоков бизнес-процессов в системе подчиняются глобальному порядку для каждой сущности. Порядок потока бизнес-процессов хранится в атрибуте Workflow.ProcessOrder. Определения потоков бизнес-процессов для сущности сортируются на основе этого порядка, и выбирается определение с наименьшим порядковым значением.
4. Наконец, если запись сущности создается в бизнес-приложении (модуль приложения), применяется дополнительный уровень фильтрации для выбора потока бизнес-процессов, который автоматически применяется к новой записи сущности. При работе в приложении пользователи могут получать доступ только к соответствующим сущностям, потокам бизнес-процессов, представлениям и формам, к которым они имеют доступ благодаря ролям безопасности, присвоенным бизнес-приложению.
   • Если бизнес-приложение не содержит никаких потоков бизнес-процессов, тогда потоки бизнес-процессов применяются, как описано до шага 3.
   • Если в бизнес-приложении имеется один или несколько потоков бизнес-процессов, тогда будут применимы только те потоки бизнес-процессов, которые присутствуют в приложении. В этом случае, когда пользователь работает в рамках контекста бизнес-приложения, список потоков бизнес-процессов шага 3 продолжает фильтроваться до потоков, которые являются частью бизнес-приложения, присутствуют в модуле приложения и сортируются на основе порядка процессов.
   • Если в бизнес-приложении отсутствуют потоки бизнес-процессов для сущности или нет потоков, доступных пользователю, тогда к новой записи сущности поток бизнес-процессов не применяется.

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

• Задайте Guid.Empty, чтобы пропустить настройку потока бизнес-процессов для новых записей сущности. Это можно сделать, если вы массово создаете записи сущности, но не хотите, чтобы к ним применялся поток бизнес-процесса.
• Задайте для них определенные сущности потоков бизнес-процессов (в виде ссылки на сущность). В этом случае система применит определенные потоки бизнес-процессов вместо логики по умолчанию.

Если при создании записи сущности не установить значение для атрибута ProcessId, система применит логику по умолчанию, как объяснялось ранее.

Устаревшие атрибуты, связанные с процессами в сущностях

Устаревшие связанные с процессом атрибуты (например, ProcessId, StageId и TraversedPath) в сущностях, для которых включена поддержка потоков бизнес-процесса, уже объявлены нерекомендуемыми, вместе с клиентским API setProcess. Манипулирование этими устаревшими связанными с процессом атрибутами для целевых записей сущностей или использование устаревшего клиентского API setProcess не гарантируют согласованность состояния потока бизнес-процесса и не относятся к поддерживаемым сценариям. Рекомендуется использовать атрибуты сущности потока бизнес-процессов, как было описано ранее в разделе Создание, получение, обновление и удаление записей потока бизнес-процессов (экземпляры процессов)

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

Поддержка программируемости на стороне клиента для потоков бизнес-процессов

В Dynamics 365 есть объект на стороне клиента, который можно использовать для взаимодействия с потоками бизнес-процессов в скриптах форм. Потоки бизнес-процессов активируют события на стороне клиента каждый раз, когда процесс применяется к записи, изменяется этап или его состояние изменяется на Active, Finished или Aborted. Дополнительные сведения см. в статье formContext.data.process (Справочник по API клиента)

Максимальное число процессов, стадий и шагов

Для каждой сущности значение по умолчанию для максимального числа активированных потоков бизнес-процессов — 10. Другое значение можно указать с помощью атрибута Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity. Тем не менее, если значение больше 10, наблюдается снижение производительности системы при переключении процессов или открытии записи, которой назначен поток бизнес-процессов. Это может быть особенно заметно, если процессы охватывают несколько сущностей.

Следующие параметры нельзя настроить:

• Максимальное количество этапов для каждой сущности в процессе — 30.

• Максимальное число шагов на каждом этапе — 30.

• Максимальное количество сущностей, которые могут участвовать в потоке процессов — 5.

См. также

• Потоки бизнес-процессов