Trabalhar com fluxos do processo de negócio através de código

Os fluxo de processo empresarial permitem criar vendas, serviços e outros processos de negócio mais eficientes e otimizados. Criam uma visualização do seu processo empresarial ao colocar controlos especiais na parte superior dos formulários de entidade. Os utilizadores são orientados ao longo de várias fases dos processos de vendas, marketing ou serviço até os concluírem. Cada processo suporta múltiplas fases e passos. Pode adicionar ou remover passos, alterar a ordem das fases ou adicionar novas entidades ao fluxo de processo empresarial.

É possível executar simultaneamente diferentes instâncias de fluxo de processo empresarial no mesmo registo de entidade. Os utilizadores podem alternar entre instâncias paralelas do processo empresarial e retomar o trabalho numa fase atual do processo.

Este tópico fornece informações sobre a forma como pode trabalhar programaticamente com fluxos de processo empresarial.

Pré-requisitos dos fluxos de processo empresarial

As entidades personalizadas e as entidades com formulários de IU atualizados podem participar no fluxo de processo empresarial. As entidades de IU atualizadas têm a propriedade IsAIRUpdated definida para true.

Para ativar uma entidade para o fluxo de processo empresarial, defina a propriedade IsBusinessProcessEnabled para true.

Definir fluxos de processo empresarial

Utilize o estruturador de fluxo de processo empresarial visual para definir um fluxo de processo empresarial. Mais informações: Criar um fluxo do processo de negócio

Por predefinição, é criado um registo de fluxo de processo empresarial no estado Draft.

É armazenada uma definição de fluxo de processo empresarial na entidade workflow, ao passo que as informações da fase do fluxo de processo empresarial são armazenadas na entidade processstage.

Ativar fluxo de processo empresarial

Antes de poder utilizar o fluxo do processo, tem de o ativar. Para o ativar, tem de ter o privilégio prvActivateBusinessProcessFlow para a entidade Workflow. Utilize a mensagem UpdateRequest para definir o estado do registo de entidade Workflow para Activated. Mais informações: Realizar operações especializadas com Atualização

Entidade de fluxo de processo empresarial

Depois de ativar uma definição de fluxo de processo empresarial através da alteração do estado do registo de entidade Workflow correspondente ou com recurso ao estruturador de fluxo do processo de negócio, é automaticamente criada uma entidade personalizada com o seguinte nome, para armazenar as instâncias de fluxo de processo de negócio ativadas: "<activesolutionprefix>_<uniquename>", em que uniquename deriva do nome que especificar.

Por exemplo, se tiver atribuído o nome "O Meu BPF Personalizado" à definição de fluxo de processo empresarial e estiver a utilizar o publicador predefinido (novo) para a sua solução ativa, o nome da entidade personalizada criada para armazenar instâncias do processo será "novo_mycustombpf".

Se o valor uniquename não estiver disponível para uma definição de fluxo do processo de negócio (por exemplo, caso o fluxo do processo de negócio tenha sido importado como parte da solução a partir de uma versão anterior), o nome predefinido da entidade personalizada será "<activesolutionprefix>_bpf_<GUID_BPF_Definition>:

Pode obter o nome da sua entidade de fluxo de processo empresarial de qualquer uma das seguintes formas:

• Através da IU: utilize a IU de personalização para navegar para a sua entidade de fluxo de processo de negócio:

  

• Através da API Web: utilize o seguinte pedido:

  Pedido

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

• Através do serviço de Organização: utilize 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

Gerir a segurança de fluxos de processo empresarial

A entidade personalizada criada automaticamente ao ativar um fluxo de processo de negócio para armazenar instâncias de fluxos de processo de negócio cumpre o modelo de segurança standard, assim como qualquer outra entidade personalizada no Customer Engagement. Isto significa que as permissões concedidas nestas entidades definem as permissões de runtime para os utilizadores dos fluxos de processo empresarial.

A entidade personalizada do fluxo de processo empresarial possui um âmbito organizacional. Os privilégios regulares de criação, obtenção, atualização e eliminação desta entidade definem a permissão que o utilizador teria com base nas funções que lhe foram atribuídas. Por predefinição, quando a entidade personalizada do fluxo de processo empresarial é criada, apenas as funções de segurança Administrador de Sistema e Personalizador de Sistemas possuem acesso. Deve conceder explicitamente permissões à nova entidade do fluxo de processo empresarial (por exemplo, My Custom BPF) para outras funções de segurança conforme necessário.

Criar, obter, atualizar e eliminar registos da entidade do fluxo de processo empresarial (instâncias do processo)

A entidade personalizada, criada automaticamente ao ativar uma definição de fluxo de processo empresarial, armazena todas as instâncias do processo na definição de fluxo de processo empresarial. A entidade personalizada suporta a criação através de programação e gestão de registos padrão (instâncias do processo) ao utilizar a API Web e o ponto final do CRM 2011.

Consideremos o seguinte exemplo onde temos um fluxo de processo empresarial entre entidades, “O Meu BPF Personalizado”, com 3 fases: F1:Conta, F2:Conta e F3:Contacto.

Obtenha todos os registos (instâncias) de uma entidade de fluxo de processo empresarial

Se o nome da sua entidade de fluxo de processo empresarial for "new_mycustombpf", utilize a seguinte consulta para obter todos os registos (instâncias do processo) da sua entidade de fluxo de processo empresarial:

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

Neste momento, poderá não obter nenhuma instância na sua resposta devido à inexistência de instâncias. Execute este pedido depois de criar uma instância da sua definição de fluxo de processo empresarial mais à frente neste tópico.

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

Se quiser mudar para outro fluxo de processo empresarial para um registo de entidade sem recorrer à IU, crie programaticamente um registo de entidade de fluxo de processo empresarial (instância do processo).

(!NOTA) Quando cria um registo na Interface Unificada e não pretende ter um fluxo de processo de negócio associado ao registo, crie um script onload que invoque setActiveProcess e aprove um processID (GUID) vazio. Exemplo de Código formcontext.data.process.setActiveProcess('00000000-0000-0000-0000-000000000000', (a)=>{​​alert("changed -- " + a)}​​)

Para criar um registo de entidade de fluxo de processo empresarial, tem de especificar os seguintes valores:

• Associe o registo de entidade de fluxo de processo empresarial a um registo de entidade primária ao definir a propriedade de navegação de valor único através da anotação @odata.bind. Para ficar a saber o nome da propriedade de navegação que aponta para o registo de entidade primária da sua definição de fluxo de processo empresarial, utilize o documento de metadados CSDL.

• Associe o registo de entidade de fluxo de processo empresarial a uma fase válida especificada na definição de fluxo de processo empresarial ao definir a propriedade de navegação de valor único através da anotação @odata.bind. Para ficar a saber o nome da propriedade de navegação (normalmente, activestageid) que aponta para o registo da fase da sua definição de fluxo de processo empresarial, utilize o documento de metadados CSDL.

  Além disso, pode obter informações sobre todas as fases de uma definição de fluxo do processo de negócio através do pedido da API Web que se segue, partindo do princípio de que o ID da sua definição de fluxo do processo de negócio é 2669927e-8ad6-4f95-8a9a-f1008af6956f:

  Pedido

  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, utilize o seguinte pedido para criar uma instância da sua definição de fluxo do processo de negócio para um registo de conta (ID=a176be9e-9a68-e711-80e7-00155d41e206) e a fase ativa definida como a primeira fase da instância do processo, S1 (ID=9a9185f5-b75b-4bbb-9c2b-a6626683b99bb):

Pedido

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)

Tenha em atenção que, se quiser criar uma instância da sua definição de fluxo de processo de negócio com a fase ativa definida como outra fase que não a primeira, também deve fornecer traversedpath no seu pedido. O caminho percorrido é a cadeia de carateres delimitada por vírgulas de IDs de fases do processo que representam as fases visitadas da instância do fluxo de processo empresarial. O seguinte pedido cria uma instância para um registo de conta (ID=679b2464-71b5-e711-80f5-00155d513100) e a fase ativa definida como a segunda fase, 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 registo de entidade de fluxo de processo empresarial (instância do processo)

Pode atualizar uma instância do processo para navegar para a fase anterior ou seguinte, bem como para abandonar, reativar ou concluir uma instância do processo.

Navegação pelas fases

Para navegar para uma fase diferente, terá de atualizar um registo de instância do processo para alterar o respetivo ID da fase ativa e atualizar o caminho percorrido. Tenha em atenção que tem de navegar para a fase anterior ou seguinte apenas durante a atualização de uma instância de fluxo de processo empresarial.

Para navegar pelas fases, necessitará do ID da instância de fluxo de processo empresarial que pretende atualizar. Para obter todas as instâncias do seu fluxo de processo empresarial, veja a secção acima Obter todos os registos (instâncias) para uma entidade de fluxo de processo empresarial.

Partindo do princípio de que o ID da instância do processo que pretende atualizar é dc2ab599-306d-e811-80ff-00155d513100, utilize o seguinte pedido para atualizar a fase ativa 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: abortar, reativar ou concluir

Uma instância do processo pode ter um dos seguintes estados: Ativa, Concluída ou Abortada. O estado é determinado pelos seguintes atributos no registo de instância do processo:

• statecode: apresenta o estado da instância do processo.

  valor	Etiqueta
  0	Active
  1	Inativos

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

  valor	Etiqueta
  1	Active
  2	Concluído
  3	Abortada

Portanto, para Abortar uma instância do processo, utilize o seguinte pedido para definir adequadamente os valores statecode e 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" 
}

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

Por fim, para definir um estado de instância do processo para Concluída, o que só é possível na última fase de uma instância do processo, substitua os valores statecode e statuscode no código acima por 0 e 2, respetivamente.

Navegação entre entidades

No caso da navegação entre entidades deste exemplo, tem de definir a fase ativa da instância do processo para a última fase, S3 (ID=a107e2fd-7543-4c1a-b6b4-b8060ecb1a1a), atualizar o caminho percorrido e definir um registo de contacto como registo de entidade primária de acordo com a definição de fluxo do processo de negócio.

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

Eliminar um registo de entidade de fluxo de processo empresarial (instância do processo)

Utilize o seguinte pedido da API Web:

Pedido

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

Resposta

Se o registo existir, receberá uma resposta normal com o estado 204 para indicar que a eliminação foi bem-sucedida. Se a entidade não for encontrada, receberá uma resposta com o estado 404.

Utilizar as mensagens RetrieveProcessInstances e RetrieveActivePath

Utilize a mensagem RetrieveProcessInstances (Função RetrieveActivePath ou RetrieveProcessInstancesRequest) para obter todas as instâncias de fluxo de processo de negócio de um registo de entidade em todas as definições de processo de negócio. As instâncias de fluxo de processo empresarial devolvidas para uma entidade são ordenadas com base no atributo modifiedon da instância. Por exemplo, a instância de fluxo de processo de negócio modificada mais recentemente será o primeiro registo da coleção devolvida. A instância de fluxo de processo empresarial modificada mais recentemente é a que está ativada na IU de um registo de entidade.

Cada registo de instância de fluxo de processo empresarial devolvido para um registo de entidade devido à utilização da mensagem RetrieveProcessInstances armazena o ID da fase ativa no atributo processstageid, que pode ser utilizado para localizar a fase ativa, e navega para a fase anterior ou seguinte. Para tal, primeiro tem de localizar o caminho ativo de uma instância de fluxo de processo empresarial e as fases disponíveis na instância de fluxo do processo através da mensagem RetrieveActivePath (Função RetrieveActivePath ou RetrieveActivePathRequest).

Quando tiver a fase ativa e as informações do caminho ativo de uma instância de fluxo de processo empresarial, poderá utilizar as informações para navegar para uma fase anterior ou seguinte no caminho ativo. A navegação de avanço entre fases deve ser realizada sequencialmente, ou seja, só deve avançar para a próxima fase do caminho ativo.

Para ver o exemplo completo que demonstra a utilização desses dois métodos e da navegação entre fases com recurso ao Serviço de organização, veja Sample: Work with business process flows (Exemplo: trabalhar com fluxos do processo empresarial).

Aplicar um fluxo de processo empresarial durante a criação de um registo de entidade

Esta secção fornece informações sobre o comportamento predefinido para aplicar automaticamente fluxos do processo de negócios em novos registos de entidade criados no Customer Engagement, bem como sobre a forma como pode substituí-lo para aplicar um fluxo do processo de negócio da sua preferência a novos registos de entidade.

Por predefinição, no caso das entidades que têm múltiplos fluxos do processo empresarial definidos para as mesmas, o sistema aplica um fluxo de processo empresarial ao novo registo de entidade com recurso à seguinte lógica de vários passos:

1. Identifique todos os fluxos do processo de negócio aplicáveis ao novo registo de entidade com base no atributo Workflow.PrimaryEntity dos registos de definição de fluxo de processo de negócio.
2. Identifique as definições de fluxo de processo empresarial às quais o utilizador atual tem acesso. Para obter informações sobre como o acesso a um fluxo de processo empresarial é determinado e gerido, veja a secção acima, Gerir segurança para fluxos do processo empresarial.
   
3. Todas as definições de fluxo de processo empresarial no 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 fluxo de processo empresarial de uma entidade são ordenadas com base nesta ordem. É escolhida a que tem o menor valor de ordem.
4. Por fim, se o registo de entidade for criado a partir de uma aplicação empresarial (módulo de aplicação), é aplicado um nível de filtragem adicional com vista à escolha do fluxo de processo empresarial que vai ser aplicado automaticamente ao novo registo de entidade. Quando trabalharem numa aplicação, os utilizadores só poderão aceder às entidades, aos fluxos do processo empresarial, às vistas e aos formulários relevantes aos quais têm acesso devido às funções de segurança atribuídas à aplicação empresarial.
   • Se a aplicação empresarial não contiver nenhum fluxo de processo empresarial, o fluxo de processo empresarial será aplicado conforme explicado até ao passo 3.
   • Se a aplicação empresarial tivesse um ou mais fluxos do processo empresarial, apenas os fluxos do processo empresarial presentes na aplicação seriam aplicáveis. Neste caso, quando o utilizador está a trabalhar no contexto de uma aplicação empresarial, a lista de fluxos do processo empresarial do passo 3 é filtrada para os fluxos que fazem parte da aplicação empresarial e que estão presentes no módulo de aplicação. Além disso, a lista é ordenada com base na ordem do processo.
   • Se não estiver disponível nenhum fluxo de processo empresarial numa aplicação empresarial para a entidade ou nenhum fluxo ao qual o utilizador tem acesso, não será aplicado nenhum fluxo de processo empresarial ao novo registo de entidade.

Pode substituir a lógica predefinida de fluxos do processo empresarial que são aplicados automaticamente aos novos registos de entidade. Para tal, defina o atributo ProcessId da entidade para um dos seguintes valores quando criar um novo registo de entidade:

• Defina para Guid.Empty para ignorar a definição de um fluxo de processo empresarial para novos registos de entidade. É recomendado que o faça se estiver a criar registos de entidade em massa, mas não quiser que o fluxo de processo de negócio seja aplicado aos mesmos.
• Defina-o para uma entidade de fluxo de processo empresarial específica (como uma referência de entidade). Neste caso, o sistema aplicará o fluxo de processo empresarial especificado em vez da lógica predefinida.

Se não definir um valor para o atributo ProcessId quando criar um novo registo de entidade, o sistema aplicará a lógica predefinida, conforme explicado anteriormente.

Atributos herdados relacionados com processos em entidades

Os atributos relacionados com processos legados (ProcessId, StageId e TraversedPath) em entidades ativadas para fluxos do processo de negócio, juntamente com a API cliente setProcess já foram preteridos. A manipulação destes atributos relacionados com os processos legados nos registos da entidade de destino ou a utilização da API cliente setProcess legada não garante a consistência do estado do fluxo do processo de negócio e não são cenários suportados. É recomendado utilizar os atributos da entidade de fluxo de processo empresarial conforme explicado anteriormente na secção Criar, obter, atualizar e eliminar registos de entidade de fluxo de processo empresarial (instâncias do processo)

A única exceção consiste em modificar programaticamente o atributo ProcessId quando criar um registo de entidade para substituir a aplicação predefinida do fluxo de processo empresarial no novo registo conforme explicado na secção anterior, Aplicar um fluxo de processo empresarial durante a criação de um registo de entidade.

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

Com o Dynamics 365 há um objeto do lado do cliente que pode utilizar para interagir com fluxos do processo de negócio nos seus scripts de formulário. Os fluxos do processo empresarial acionam eventos do lado do cliente sempre que um processo é aplicado a um registo, que uma fase do mesmo é alterada ou que o respetivo estado é alterado para Active, Finished ou Aborted. Mais informações: formContext.data.process (referência da API de Cliente)

Número máximo de processos, e de fases de passos

O valor predefinido para o número máximo de fluxos do processo empresarial ativados por entidade é 10. Pode especificar um valor diferente através do atributo Organization.MaximumActiveBusinessProcessFlowsAllowedPerEntity. No entanto, se o valor for superior a 10, o desempenho do seu sistema poderá diminuir quando mudar de processos ou abrir um registo que tem um fluxo de processo empresarial atribuído. Isto poderá ser especialmente percetível se os processos abrangerem múltiplas entidades.

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

• O número máximo de fases por entidade no processo é 30.

• O número máximo de passos em cada fase é 30.

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

Consulte também

• Fluxos de processo empresarial