Crie suas próprias ações

Você pode estender a funcionalidade do Dynamics 365 Customer Engagement (on-premises) criando mensagens personalizadas conhecidas como ações. Essas ações terão classes de solicitação/resposta associadas e uma ação de API Web será gerada. As ações são normalmente usadas para adicionar novas funcionalidades específicas de domínio ao serviço Web da organização ou para combinar várias solicitações de mensagens do serviço Web da organização em uma única solicitação. Por exemplo, em um call center de suporte, talvez você queira combinar as mensagens Create, Assign e Setstate em uma única nova mensagem Escalate.

A lógica de negócios de uma ação é implementada usando um fluxo de trabalho. Quando você cria uma ação, o fluxo de trabalho em tempo real associado é registrado automaticamente para ser executado no estágio 30 (operação principal) do pipeline de execução. Para obter mais informações sobre fluxos de trabalho em tempo real, consulte Tipos de fluxo de trabalho.

Embora as ações tenham suporte no Dynamics 365 for Customer Engagement, a criação de uma ação no código (usando XAML) só é compatível com implantações locais e IFD. Os clientes online devem criar ações interativamente no aplicativo Web.

Sobre as definições de ação

Uma ação é definida usando um Workflow registro de entidade, semelhante a um fluxo de trabalho em tempo real. Alguns pontos-chave do que é uma ação e como ela funciona estão na lista a seguir:

• Pode ser associado a uma única entidade ou ser global (não associado a nenhuma entidade específica).

• É executado no estágio de operação principal 30 do pipeline de execução do evento.

• Dá suporte à invocação de plug-ins registrados nos estágios de pré-operação e pós-operação do pipeline da execução do evento.

• Pode ter plug-ins registrados nos estágios de pré-operação ou pós-operação somente quando o status da ação é Ativado.

• Está disponível por meio da API Web ou pontos de extremidade organization.svc e organization.svc/web.

• Pode ser executado usando um recurso da web JavaScript. Para obter mais informações: Executar uma ação usando um recurso da Web JavaScript

• Sempre é executado no contexto de segurança do usuário que está chamando.

• O registro não pode ser excluído enquanto existirem etapas de plug-in registradas na ação.

• Opcionalmente, por meio de uma definição de configuração, pode participar da transação de banco de dados atual.

• Não dá suporte a um escopo em que a execução é restrita a um usuário, unidade de negócios ou organização. As ações sempre são executadas no escopo da organização.

• Suporta argumentos de entrada e saída.

• Suporta auditoria de alterações de dados.

• Não há suporte com clientes offline.

• Pode ser invocado por uma chamada de método do serviço Web.

• Pode ser invocado diretamente de um fluxo de trabalho.

Permissões necessárias

Um privilégio de segurança chamado Ativar processos em tempo real (prvActivateSynchronousWorkflow) é necessário para ativar o fluxo de trabalho em tempo real de uma ação para que ela possa ser executada. Isso é um acréscimo a quaisquer privilégios necessários para criar um fluxo de trabalho.

Criar uma ação usando código

Normalmente, uma ação seria implementada por um personalizador usando o designer de fluxo de trabalho interativo do aplicativo Web. No entanto, os desenvolvedores podem implementar ações usando chamadas do SDK e implantar em um servidor local ou IFD, se desejarem.

Os atributos de entidade de fluxo de trabalho usados para uma ação são descritos na tabela a seguir. O código de exemplo para um fluxo de trabalho em tempo real pode ser encontrado no tópico Criar um fluxo de trabalho em tempo real no código.

Adicionar argumentos de entrada e saída

As ações dão suporte a argumentos de entrada e saída que podem ser adicionados ao fluxo de trabalho usando um tipo DynamicActivityProperty . Quando você adiciona esses argumentos ao fluxo de trabalho de uma ação, eles se tornam propriedades nas classes de solicitação e resposta de mensagem associadas a essa ação. Por exemplo, o exemplo a seguir mostra o código C# e XAML para dois argumentos de entrada e um de saída.

DynamicActivityProperty inputProperty1 = new DynamicActivityProperty     { Name = "Subject", Type = typeof(InArgument<string>) };  
DynamicActivityProperty inputProperty2 = new DynamicActivityProperty     { Name = "EntityCollection", Type = typeof(InArgument<EntityCollection>) };  
DynamicActivityProperty outputProperty1 = new DynamicActivityProperty     { Name = "Output", Type = typeof(OutArgument<string>) };  
  
inputProperty1.Attributes.Add(new ArgumentRequiredAttribute(true));  
inputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The subject"));  
inputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));  
  
inputProperty2.Attributes.Add(new ArgumentRequiredAttribute(false));  
inputProperty2.Attributes.Add(new ArgumentDescriptionAttribute("The entity collection"));  
inputProperty2.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Input));  
  
outputProperty1.Attributes.Add(new ArgumentRequiredAttribute(false));  
outputProperty1.Attributes.Add(new ArgumentDescriptionAttribute("The output"));  
outputProperty1.Attributes.Add(new ArgumentDirectionAttribute(Microsoft.Xrm.Sdk.Workflow.ArgumentDirection.Output));  

<x:Property Name="Subject"  
            Type="InArgument(x:String)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="True" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The subject " />  
  <mxsw:ArgumentDirectionAttribute Value="Input" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  
<x:Property Name="EntityCollection"  
            Type="InArgument(mxs:EntityCollection)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="False" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The entity collection" />  
  <mxsw:ArgumentDirectionAttribute Value="Input" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  
<x:Property Name="Output"  
            Type="OutArgument(x:String)">  
 <x:Property.Attributes>  
  <mxsw:ArgumentRequiredAttribute Value="False" />  
  <mxsw:ArgumentTargetAttribute Value="False" />  
  <mxsw:ArgumentDescriptionAttribute Value="The output" />  
  <mxsw:ArgumentDirectionAttribute Value="Output" />  
  <mxsw:ArgumentEntityAttribute Value="" />  
 </x:Property.Attributes>  
</x:Property>  

Os nomes usados para as propriedades devem ser consistentes com os nomes de argumento, pois a geração de código definirá esses nomes como propriedades de solicitação ou resposta.

Os tipos de argumento com suporte para os argumentos de entrada e saída são mostrados na tabela a seguir.

Os atributos de argumento com suporte estão listados na tabela a seguir.

Empacotar uma ação para distribuição

Para distribuir sua ação para que ela possa ser importada para uma organização do Dynamics 365 Customer Engagement (on-premises), adicione sua ação a uma solução do Customer Engagement. Isso é feito facilmente usando o aplicativo Web navegando até Configurações>Personalizações>Soluções. Você também pode escrever código para criar a solução. Para obter mais informações sobre soluções, consulte Empacotar e distribuir extensões.

Gerar tipos vinculados antecipadamente para uma ação

Usando a ferramenta CrmSvcUtil, você pode gerar classes de solicitação e resposta para sua ação incluir no código do aplicativo. No entanto, antes de gerar essas classes, certifique-se de ativar a ação.

Para baixar o CrmSvcUtil.exe, consulte Ferramentas de desenvolvimento do Dataverse.

O exemplo a seguir mostra o formato para executar a ferramenta na linha de comando para uma instalação local do Customer Engagement. Você fornece os valores de parâmetro para sua instalação.

CrmSvcUtil.exe /url:https://<serverName>/<organizationName>/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /domain:<domainName> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions  

O exemplo a seguir mostra o formato para executar a ferramenta na linha de comando com o Dynamics 365 for Customer Engagement. Você fornece os valores de parâmetro apropriados para sua conta e servidor.

CrmSvcUtil.exe /url:https://<organizationUrlName>.api.crm.dynamics.com/XRMServices/2011/Organization.svc /out:<outputFilename>.cs /username:<username> /password:<password> /namespace:<outputNamespace> /serviceContextName:<serviceContextName> /generateActions  

Observe o uso do /generateActions parâmetro. Mais informações: Criar classes de entidade limitada antecipada com a ferramenta para geração de códigos (CrmSvcUtil.exe).

Você pode usar tipos limitados antecipa ou tardiamente com as classes de solicitação e resposta geradas para a ação.

Executar uma ação usando a API Web

Uma nova ação é criada na API Web quando ela é criada. Se a ação for criada no contexto de uma entidade, ela será vinculada a essa entidade. Caso contrário, é uma ação não vinculada. Mais informações: Usar ações da API Web.

Executar uma ação usando um recurso da Web JavaScript

Uma ação pode ser executada usando a API Web como qualquer ação do sistema. Mais informações: Xrm.WebApi.online.execute

Executar uma ação usando o serviço da organização

Para executar uma ação usando o serviço Web da organização usando código gerenciado, siga estas etapas.

1. Inclua o arquivo de tipos limitados antecipadamente que você gerou usando a ferramenta CrmSvcUtil no projeto do aplicativo.

2. No código do aplicativo, instancie a solicitação da ação e preencha todas as propriedades necessárias.

3. Invoque Execute, passando sua solicitação como um argumento.

   Antes de executar o código do aplicativo, verifique se a ação está ativada. Caso contrário, você receberá um erro em tempo de execução.

Executar uma ação usando um processo

Você pode executar uma ação a partir de fluxos de trabalho, caixas de diálogo ou outras ações de processo. As ações personalizadas ativadas estão disponíveis para processos selecionando o item Executar Ação na lista suspensa Adicionar Etapa do formulário de processo do aplicativo Web. Depois que a etapa for adicionada ao processo, você poderá selecionar sua nova ação personalizada (ou qualquer ação) na lista Ação fornecida na etapa. Selecione Definir Propriedades na etapa para especificar quaisquer parâmetros de entrada que sua ação personalizada exija.

As verificações de plataforma Depth existentes garantem que um loop infinito não ocorra. Para obter mais informações sobre limites de profundidade, consulte MaxDepth.

Cuidado com ações de execução prolongada

Se uma das etapas no fluxo de trabalho em tempo real da ação for uma atividade de fluxo de trabalho personalizada, essa atividade de fluxo de trabalho personalizada será executada dentro do ambiente isolado de execução em sandbox e estará sujeita ao limite de tempo de dois minutos, semelhante à forma como os plug-ins de sandbox são gerenciados. No entanto, não há restrições quanto à quantidade de tempo total que a ação em si pode levar. Além disso, se uma ação participar de uma transação com reversão habilitada, os tempos limite do SQL Server serão aplicados.

Consulte também

Crie fluxos de trabalho em tempo real
Usar caixas de diálogo para processos guiados
Pipeline de execução de eventos
Escreva fluxos de trabalho para automatizar processos de negócios
Personalize seu sistema