Trabalhar com fluxos de processos empresariais usando código

Um fluxo de processo empresarial permite criar processos de vendas, serviços e outros processos empresariais mais eficientes e simplificados. Ele cria uma visualização de seu processo empresarial colocando controles especiais na parte superior dos formulários de entidade. Os usuários serão guiados em vários estágios dos processos de vendas, marketing ou serviços até a sua conclusão. Cada processo oferece suporte a vários estágios e etapas. É possível adicionar ou remover etapas, alterar a ordem dos estágios ou adicionar novas entidades ao fluxo de processos empresarial.

As instâncias de fluxo de processo empresarial diferentes podem ser executadas simultaneamente no mesmo registro de entidade. Os usuários podem alternar entre as instâncias de processo empresarial simultâneas e retomar seu trabalho em um estágio atual do processo.

Este tópico fornece informações sobre como você pode trabalhar, por meio de programação, com fluxos de processo empresarial.

Pré-requisitos para o fluxo de processo empresarial

As entidades personalizadas e as entidades que contêm formulários da interface do usuário atualizados podem participar do fluxo do processo empresarial. As entidades da interface do usuário atualizadas têm a propriedade IsAIRUpdated definida para true.

Para habilitar uma entidade para usar o fluxo do processo empresarial, defina a propriedade IsBusinessProcessEnabled para true.

Definir o fluxo do processo empresarial

Use o designer de fluxo do processo empresarial visual para definir um fluxo de processo empresarial. Mais informações: Criar um fluxo de processo empresarial

Por padrão, um registro de fluxo do processo empresarial é criado no estado Draft.

Uma definição de fluxo de processo empresarial é armazenada na entidade workflow e as informações de estágio para o fluxo do processo empresarial são armazenadas na entidade processstage.

Ativar fluxo do processo empresarial

Antes de usar um fluxo de processo, é necessário ativá-lo. Para ativá-lo, você deve ter o privilégio prvActivateBusinessProcessFlow para a entidade Workflow. Use a mensagem UpdateRequest para definir o estado do registro de entidade Workflow como Activated. Mais informações: executar operações especializadas usando Update

Entidade de fluxo de processo empresarial

Depois de ativar uma definição de fluxo de processo empresarial alterando o estado o registro de entidade Workflow correspondente ou usando o designer de fluxo do processo empresarial, uma entidade personalizada com o seguinte nome é criada automaticamente para armazenar as instâncias de fluxo de processo empresarial: ""<activesolutionprefix>_<uniquename>", em que o nome exclusivo é derivado do nome que você especificar.

Por exemplo, se você especificou "Meu BPF personalizado" como o nome da definição de fluxo de processo empresarial e estiver usando o editor padrão (novo) para sua solução ativa, o nome da entidade personalizada criada para armazenar as instâncias de processo será "new_mycustombpf".

Se o valor uniquename não estiver disponível para uma definição de fluxo de processo empresarial, por exemplo, se o fluxo do processo empresarial foi importado como parte da solução de uma versão anterior, o nome padrão da entidade personalizada será "<activesolutionprefix>_bpf_<GUID_BPF_Definition>:

Você pode recuperar o nome da sua entidade de fluxo do processo empresarial usando qualquer uma das seguintes maneiras:

• Usando a interface do usuário: use a interface do usuário de personalização para navegar até sua entidade de fluxo do processo empresarial:

  

• Usando a API Web: use a seguinte solicitação:

  Solicitação

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

  Resposta

  {  
  "@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"
       }
    ]
  }
  
  

• Usando o serviço da organização: use o seguinte exemplo de código:

  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

Gerenciar seguranças dos fluxos do processo empresarial

A entidade personalizada, que é automaticamente criada ao ativar um fluxo do processo empresarial para armazenar instâncias desse fluxo, adere ao modelo de segurança padrão, assim como quaisquer outras entidades personalizadas no Customer Engagement. Isso implica que os privilégios concedidos nessas entidades definem as permissões do tempo de execução para usuários dos fluxos do processo empresarial.

A entidade personalizada do fluxo do processo empresaria tem um escopo da organização. Os privilégios básicos para criar, recuperar, atualizar e excluir nessa entidade definem a permissão do usuário de acordo com as funções atribuídas a eles. Por padrão, quando a entidade personalizada do fluxo do processo empresarial é criada, somente as funções de segurança Administrador do Sistema e Personalizador do Sistema recebem acesso a ela, e você precisa conceder as permissões explicitamente para a nova entidade do fluxo do processo empresarial (por exemplo, Meu BPF personalizado), para outras funções de segurança, conforme o necessário.

Criar, recuperar, atualizar e excluir registros de entidade do fluxo do processo empresarial (instâncias de processo)

A entidade personalizada que é automaticamente criada na ativação de uma definição de fluxo do processo empresarial armazena todas as instâncias de processo para a definição do fluxo do processo empresarial. A entidade personalizada permite a criação e o gerenciamento programáticos padrão de registros (instâncias de processo) usando a API Web e o ponto de extremidade do CRM 2011.

Vamos considerar o seguinte exemplo contendo um fluxo do processo empresarial entre entidades, "Meu BPF personalizado", com três estágios: S1:Account, S2:Account e S3:Contact.

Recuperar todos os registros (instâncias) de uma entidade do fluxo do processo empresarial

Se o nome da entidade do fluxo do processo empresarial for "new_mycustombpf", use a seguinte consulta para recuperar todos os registros (instâncias de processo) dessa entidade:

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

Neste ponto, você não poderá obter todas as instâncias em sua resposta, pois não há nenhuma. Execute esta solicitação depois de criar uma instância de sua definição de fluxo de processo empresarial neste tópico.

Criar um registro de entidade de fluxo de processo empresarial (instância de processo)

Crie um registro de entidade de fluxo de processo empresarial (instância de processo) por meio de programação se quiser alternar para outro fluxo de processo empresarial para um registro de entidade sem usar a interface do usuário.

(!OBSERVAÇÃO) Quando você cria um registro na Interface Unificada e não deseja ter um fluxo de processo empresarial associado ao registro, crie um script de carga que invoque setActiveProcess e passe um GUID (processID) vazio. Exemplo de código formcontext.data.process.setActiveProcess('00000000-0000-0000-0000-000000000000', (a)=>{alert("changed -- " + a)})

Para criar um registro de entidade de fluxo de processo empresarial, você precisará especificar os seguintes valores:

• Associar o registro de entidade de fluxo de processo empresarial a um registro de entidade principal definindo a propriedade de navegação de valor único usando a anotação @odata.bind. Para descobrir o nome da propriedade de navegação que aponta para o registro de entidade principal para sua definição de fluxo de processo empresarial, use o documento CSDL $metadata.

• Associar o registro de entidade de fluxo de processo empresarial a estágio válido especificado na definição do fluxo de processo empresarial definindo a propriedade de navegação de valor único usando a anotação @odata.bind. Para descobrir o nome da propriedade de navegação (normalmente, activestageid) que aponta para o registro de estágio para sua definição de fluxo de processo empresarial, use o documento CSDL $metadata.

  Além disso, você pode recuperar informações sobre todos os estágios para uma definição de fluxo do processo empresarial usando a seguinte solicitação da API Web, supondo que a ID da sua definição de fluxo de processo empresarial seja 2669927e-8ad6-4f95-8a9a-f1008af6956f:

  Solicitação

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

  Resposta

  {
      "@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"
          }
      ]
  }
  

Em seguida, use a seguinte solicitação para criar uma instância de sua definição de fluxo de processo empresarial para um registro de conta (ID=a176be9e-9a68-e711-80e7-00155d41e206) e o estágio ativo definido como o primeiro estágio da instância do processo, S1 (ID=9a9185f5-b75b-4bbb-9c2b-a6626683b99b):

Solicitação

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 

{
    "bpf_accountid@odata.bind": "/accounts(a176be9e-9a68-e711-80e7-00155d41e206)",
    "activestageid@odata.bind": "/processstages(9a9185f5-b75b-4bbb-9c2b-a6626683b99b)"    
}

Resposta

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)

Observe que, se você quiser criar uma instância de sua definição de fluxo de processo empresarial com estágio ativo definido como um estágio diferente do primeiro, você também deverá fornecer traversedpath na sua solicitação. O caminho percorrido é a cadeia de caracteres delimitada por vírgulas de IDs de estágio do processo que representam estágios visitados da instância de fluxo do processo empresarial. A solicitação a seguir cria uma instância de um registro de conta (ID=679b2464-71b5-e711-80f5-00155d513100) e estágio ativo definido como o segundo estágio, 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 

{
    "bpf_accountid@odata.bind": "/accounts(679b2464-71b5-e711-80f5-00155d513100)",
    "activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"   
}

Atualizar um registro de entidade de fluxo de processo empresarial (instância de processo)

Você pode atualizar uma instância de processo para mover para o estágio seguinte ou anterior, abandonar uma instância de processo, reativar uma instância de processo ou concluir uma instância de processo.

Navegação de estágio

Para navegar até um estágio diferente, você precisa atualizar um registro de instância de processo para alterar sua ID de estágio ativo e atualizar adequadamente o caminho percorrido. Observe que você só deve mover para o estágio anterior ou seguinte ao atualizar uma instância de fluxo de processo empresarial.

Para executar a navegação de estágio, você precisará da ID da instância de fluxo do processo empresarial que você deseja atualizar. Para recuperar todas as instâncias do seu fluxo de processo empresarial, consulte Recuperar todos os registros (instâncias) para uma entidade de fluxo de processo empresarial mencionado anteriormente.

Supondo que a ID da instância do processo que você deseja atualizar seja dc2ab599-306d-e811-80ff-00155d513100, use a seguinte solicitação para atualizar o estágio ativo de S1 para 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

{
    "activestageid@odata.bind": "/processstages(19a11fc0-3398-4214-8522-cb2a97f66e4b)",
    "traversedpath": "9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b"
}

Alterar o estado de uma instância do processo: Anular, Reativar ou Concluir

Uma instância de processo pode ter um dos seguintes estados: Ativo, Concluído ou Anulado. O estado é determinado pelos seguintes atributos no registro de instância do processo:

• statecode: exibe o status da instância do processo.

  Value	Etiqueta
  0	Active
  1	Inativos

• statuscode: exibe informações sobre o status da instância do processo.

  Value	Etiqueta
  1	Active
  2	Concluída
  3	Anulada

Portanto, para Anular uma instância de processo, use a seguinte solicitação e defina os valores statecode e statuscode adequadamente:

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" 
}

Da mesma forma, para reativar uma instância de processo, substitua os valores statecode e statuscode no código acima com 0 e 1, respectivamente.

Por fim, para definir um status da instância de processo como Concluído, que é possível apenas no último estágio de uma instância de processo, substitua os valores statecode e statuscode no código acima por 0 e 2, respectivamente.

Navegação entre entidades

Para a navegação entre entidades neste exemplo, você deve definir o estágio ativo da instância do processo para o último estágio, S3 (ID=a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a), atualizar o caminho percorrido adequadamente e definir um registro de contato como o registro de entidade principal de acordo a definição de fluxo do processo empresarial.

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 
  
{
    "activestageid@odata.bind": "/processstages(a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a)",
    "traversedpath":"9a9185f5-b75b-4bbb-9c2b-a6626683b99b,19a11fc0-3398-4214-8522-cb2a97f66e4b,a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a",
    "bpf_contactid@odata.bind": "/contacts(0e3f10b0-da33-e811-80fc-00155d513100)"
}

Excluir um registro de entidade de fluxo de processo empresarial (instância de processo)

Use a seguinte solicitação de API Web:

Solicitação

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

Resposta

Se o registro existir, você obterá uma resposta normal com status 204 para indicar que a exclusão foi bem-sucedida. Se a entidade não for encontrada, você receberá uma resposta normal com o status 404.

Use as mensagens RetrieveProcessInstances e RetrieveActivePath

Use a mensagem RetrieveProcessInstances (RetrieveActivePath Function ou RetrieveProcessInstancesRequest) para recuperar todas as instâncias de fluxo de processo empresarial para um registro de entidade em todas as definições de processo empresarial. As instâncias de fluxo do processo empresarial de uma entidade retornadas são ordenadas com base no atributo modifiedon da instância. Por exemplo, a instância do fluxo do processo empresarial modificada recentemente será o primeiro registro na coleção retornada. A instância do fluxo do processo empresarial modificada é a única que fica ativa na interface do usuário de um registro da entidade.

Cada registro de instância de fluxo de processo empresarial retornado para um registro de entidade como resultado do uso da mensagem RetrieveProcessInstances armazena a ID do estágio no atributo processstageid que pode ser usado para localizar o estágio ativo e, em seguida, mover para o estágio seguinte ou anterior. Para fazer isso, você primeiro precisa localizar o caminho ativo de uma instância de fluxo de processo empresarial e os estágios disponíveis na instância de fluxo de processo usando a mensagem RetrieveActivePath (RetrieveActivePath Function ou RetrieveActivePathRequest).

Depois que tiver as informações do estágio ativo e do caminho ativo de uma instância do fluxo do processo empresarial, você pode usar as informações para ir para um próximo estágio ou anterior no caminho ativo. A navegação de estágios deve ser feita em sequência, isto é, você só deve avançar para o próximo estágio no caminho ativo.

Para a amostra completa do código que demonstra o uso desses dois métodos e a navegação de estágio usando o serviço da organização, consulte Amostra: trabalhar com fluxos de processo empresarial.

Aplique o fluxo do processo empresarial ao criar um registro da entidade

Esta seção fornece informações sobre o comportamento padrão para aplicar os fluxos do processo empresarial automaticamente a novos registros da entidade criada no Customer Engagement e como você pode substituí-los para aplicar um fluxo do processo empresarial de sua escolha para novos registros da entidade.

Por padrão, para que a entidade tenha vários fluxos de processo empresarial definidos para ela, o sistema aplica um fluxo do processo empresarial para o novo registro da entidade, usando a seguinte lógica de várias etapas:

1. Identificar todos os fluxos de processo empresarial aplicáveis para o novo registro de entidade com base no atributo Workflow.PrimaryEntity dos registros de definição de fluxo do processo empresarial.
2. Identifique as definições de fluxos do processo empresarial ao qual o usuário atual tem acesso. Para obter informações sobre como o acesso a um fluxo de processo empresarial é determinado e gerenciado, consulte Gerenciar a segurança para fluxos de processo empresarial anteriormente neste tópico.
   
3. Todas as definições de fluxos de processo empresarial do sistema estão sujeitas a uma ordem global por entidade. A ordem do fluxo de processo empresarial é armazenada no atributo Workflow.ProcessOrder. As definições de fluxos do processo empresarial de uma entidade são classificadas com base nessa ordem, e a que tiver o menor valor da ordem é selecionada.
4. Por fim, se o registro da entidade for criado de um aplicativo de negócios (módulo do aplicativo), um nível maior de filtragem é aplicado para selecionar o fluxo do processo de negócio a ser aplicado automaticamente ao novo registro da entidade. Ao trabalhar em um aplicativo, os usuários podem acessar somente as entidades relevantes, fluxos do processo de negócios, exibições e forms aos quais eles têm acesso, em virtude das funções de segurança atribuídas ao aplicativo de negócios.
   • Se o aplicativo de negócios não contiver nenhum fluxo do processo empresarial, então o fluxo do processo empresarial é aplicado, conforme explicado até a etapa 3.
   • Se o aplicativo de negócios tiver um ou mais fluxos do processo empresarial, então somente serão aplicáveis os fluxos do processo empresarial presentes no aplicativo. Nesse caso, quando o usuário estiver trabalhando em um contexto do aplicativo de negócios, a lista de fluxos do processo empresarial desde a etapa 3 é filtrada, além daqueles que fazer parte do aplicativo de negócios que estão presente dentro do módulo do aplicativo e, em seguida, são classificados com base na ordem do processo.
   • Se nenhum fluxo de processo empresarial estiver disponível em um aplicativo de negócios da entidade ou naquele que o usuário tem acesso, então nenhum fluxo do processo de negócio é aplicado para o novo registro da entidade.

Você pode substituir a lógica padrão de fluxos de processo empresarial sendo aplicados automaticamente para novos registros de entidade. Para fazer isso, defina o atributo ProcessId da entidade para um dos valores a seguir ao criar um novo registro de entidade:

• Defina Guid.Empty para ignorar a configuração de um fluxo de processo empresarial para novos registros de entidade. Talvez você queira fazer isso se estiver criando registros da entidade em massa, mas não quer que o fluxo do processo empresarial seja aplicado a eles.
• Defina-o como uma entidade de fluxo do processo empresarial específico (como uma referência da entidade). Nesse caso, o sistema aplicará o fluxo do processo empresarial especificado, em vez da lógica padrão.

Se você não definir um valor para o atributo ProcessId ao criar um novo registro de entidade, o sistema aplicará a lógica padrão conforme explicado anteriormente.

Atributos herdados relacionados ao processo nas entidades

Os atributos herdados relacionados a processos (ProcessId, StageId e TraversedPath) nas entidades habilitadas para fluxos de processo empresarial, bem como a API cliente setProcess, já foram desativados. Manipular esses atributos relacionados ao processo legado para registros de entidade de destino ou usar a API do cliente setProcess legado não garante a consistência do estado do fluxo do processo de negócios e não são cenários suportados. A maneira recomendada é usar os atributos da entidade de fluxo de processo empresarial, conforme explicado anteriormente na seção Criar, recuperar, atualizar e excluir registros de entidade do fluxo de processo empresarial (instâncias do processo)

A única exceção a isso é modificar por meio de programação o atributo ProcessId durante a criação de um registro de entidade para substituir o aplicativo padrão do fluxo de processo empresarial para o novo registro, conforme explicado na seção anterior: Aplicar o fluxo do processo empresarial durante a criação de um registro de entidade.

Suporte de capacidade de programação do lado cliente para fluxos do processo empresarial.

Com o Dynamics 365, há um objeto do lado do cliente que você pode usar para interagir com os fluxos de processo empresarial em seus scripts de formulário. Os fluxos do processo empresarial disparam eventos do lado do servidor sempre que um processo é aplicado a um registro, o estágio é alterado ou seu status é alterado para Active, Finished ou Aborted. Mais informações: formContext.data.process (referência de API do cliente)

Número máximo de processos, estágios e etapas

Por entidade, o valor padrão para o número máximo de fluxos de processo empresarial ativados é 10. Você pode especificar um valor diferente usando o atributo de Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity. Entretanto, se o valor for maior que 10, você poderá ver uma redução no desempenho do sistema ao alternar os processos ou abrir um registro com um fluxo do processo empresarial atribuído. Isso poderá ser particularmente perceptível se os processos abrangem várias entidades.

As seguintes configurações não são personalizáveis:

• O número máximo de estágios por entidade do processo é 30.

• O número máximo de etapas em cada estágio é 30.

• O número máximo de entidades que podem participar do fluxo de processo é 5.

Consulte também

• Fluxos do processo empresarial