Criar suas próprias ações

  • Artigo

 

Publicado: novembro de 2016

Aplicável a: Dynamics CRM 2015

É possível estender a funcionalidade do Microsoft Dynamics 365 criando mensagens personalizadas conhecidas como ações. Essas ações terão classes de solicitação/resposta associadas. Atualmente, as ações estão disponíveis para os aplicativos de negócios e extensões somente por meio das chamadas do serviço Web da organização. Geralmente, as ações são usadas para adicionar uma nova funcionalidade específica para o 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, você pode desejar combinar as mensagens Create, Assign e Setstate em uma única mensagem nova Escalate.

A lógica de negócios de uma ação é implementada com um fluxo de trabalho. Ao criar 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 Categorias de fluxos de trabalho.

Embora as ações tenham suporte no Atualização do Microsoft Dynamics CRM 2015 e Microsoft Dynamics CRM Online 2015, a criação de uma ação no código (usando XAML) terá suporte somente no Microsoft Dynamics CRM 2015 local e IFD. Os clientes online devem criar ações interativamente no aplicativo Web.

Neste tópico

Sobre definições de ação

Permissões necessárias

Criar uma ação usando o código

Empacotar uma ação para distribuição

Gerar tipos early bound para uma ação

Execute uma ação usando o serviço Web

Executar uma ação usando um processo

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

Sobre definições de ação

Uma ação é definida com um registro da entidade Workflow, que é semelhante a um fluxo de trabalho em tempo real. Alguns pontos-chave da definição de ação e como ela funciona são mostrados na lista a seguir:

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

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

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

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

  • Estão disponíveis em organization.svc e organization.svc/pontos de extremidade da Web, mas não o ponto de extremidade organizationdata.svc (OData).

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

  • Sempre é executada no contexto de segurança do usuário autor da chamada.

  • O registro não poderá ser excluído enquanto existirem etapas de plug-ins registrados na ação.

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

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

  • Oferece suporte a argumentos de entrada e saída.

  • Oferece suporte à auditoria de alterações dos dados.

  • Não tem suporte com clientes offline.

  • Pode ser invocado pela chamada a um método de serviço Web.

Observação

Pode ser diretamente invocado de um fluxo de trabalho.

Para organizações do Microsoft Dynamics CRM Online, esse recurso só estará disponível se a sua organização tiver atualizado para a Atualização 1 do Dynamics CRM Online 2015. Tem interesse em obter esse recurso? Encontre seu administrador ou contato de suporte do CRM. Este recurso não está disponível para o Dynamics CRM (local).

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 fator adicional aos privilégios necessários para criar um fluxo de trabalho. Para obter mais informações sobre esses privilégios leia o privilégio na interface do usuário no guia Personalização.

Criar uma ação usando o código

Geralmente, uma ação seria implementada por um personalizador com o uso do designer de fluxos de trabalho interativo do aplicativo Web. Entretanto, os desenvolvedores podem implementar ações usando chamadas do SDK e implantá-las no servidor local ou IFD, se desejado.

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

Atributo de fluxo de trabalho

Descrição

Category

Definido para WorkflowCategory.CustomOperation.

SyncWorkflowLogOnError

Quando true, os erros são registrados em log nos registros da ProcessSession. Diferentemente dos fluxos de trabalho assíncronos, a execução do fluxo de trabalho em tempo real não é registrado em log nos registros do System Job.

Mode

Não usado.

IsTransacted

Defina para true se a ação deve participar da transação do banco de dados; caso contrário, false. O padrão é true.

UniqueName

Um nome exclusivo para a ação. O nome é composto de um prefixo do fornecedor + “_” + o nome exclusivo.

Xaml

Defina o código do XAML que define o fluxo de trabalho em tempo real da ação. Não existe uma maneira de fazer referência a outro fluxo de trabalho em tempo real existente.

Adicionar argumentos de entrada e saída

As ações oferecem suporte para argumentos de entrada e saída, que podem ser adicionados ao fluxo de trabalho usando o tipo DynamicActivityProperty. Ao adicionar esses argumentos ao fluxo de trabalho de uma ação, eles se tornarão propriedades das classes de resposta e solicitação de mensagens associadas a essa ação. Por exemplo, o exemplo a seguir mostra o código C# e do 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 nas propriedades devem ser consistentes com os nomes dos argumentos, já que a geração de código definirá esses nomes como propriedades de solicitação ou resposta.

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

Tipo .NET

Argument Type

System.Int32

Integer

System.String

String

EntityReference

EntityReference

Entity

Entity

EntityCollection

EntityCollection

System.DateTime

DateTime

System.Double

Float

System.Decimal

Decimal

Money

Money

System.Boolean

Boolean

OptionSetValue

Picklist

Os atributos de argumentos com suporte são listados na tabela a seguir.

Atributo do argumento

Descrição

ArgumentRequiredAttribute

Indica se o argumento é necessário.

ArgumentDirectionAttribute

Indica se a direção do argumento é de entrada ou saída.

ArgumentDescriptionAttribute

Especifica uma descrição para o argumento.

ArgumentEntityAttribute

Usado se você deseja transmitir uma entidade.

ArgumentTargetAttribute

Este atributo é gerado ou adicionado automaticamente. Ele aponta para a entidade principal para a qual o fluxo de trabalho é executado. Este atributo é opcional para as ações globais.

Empacotar uma ação para distribuição

Para distribuir a ação para que seja possível importá-la para uma organização do Microsoft Dynamics 365, adicione a ação a uma solução do Dynamics 365. Isso é feito de forma fácil com o aplicativo Web, acessando Configurações> Personalizações > Soluções. Também é possível escrever o código para criar a solução. Para obter mais informações sobre soluções, consulte Embalar e distribuir extensões usando soluções.

Gerar tipos early bound para uma ação

Com a ferramenta CrmSvcUtil fornecida no pacote do SDK, é possível gerar classes de solicitação e resposta para que as ações incluam-nas no código do aplicativo. No entanto, antes de gerar estas classes, lembre-se de ativar a ação.

Baixe o pacote do SDK do Microsoft Dynamics CRM.

O exemplo a seguir mostra o formato para executar a ferramenta a partir da linha de comando para uma instalação local do Dynamics 365. Forneça os valores de parâmetro da instalação.

CrmSvcUtil.exe /url:http://<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 a partir da linha de comando com o Microsoft Dynamics CRM Online. Forneça os valores de parâmetros adequados para a 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 parâmetro /generateActions.Para obter mais informações:Criar classes de entidade associadas precocemente com a ferramenta de geração de código (CrmSvcUtil.exe).

É possível usar os tipos early bound ou late bound com as classes de solicitação e resposta geradas para a ação.

Execute uma ação usando o serviço Web

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

  1. Inclua o arquivo dos tipos early bound gerados com a ferramenta CrmSvcUtil no projeto do aplicativo.

  2. No código do aplicativo, crie uma instância da solicitação da ação e preencha as propriedades necessárias.

  3. Invoque Execute, transmitindo a 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á uma mensagem de erro de tempo de execução.

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

A biblioteca de exemplo do Sdk.Soap.js mostra como as mensagens podem ser usadas com os recursos da Web do JavaScript e o ponto de extremidade Modern App do SOAP (organization.svc/web). Use o exemplo complementar do Gerador de mensagens de ação do Sdk.Soap.js para gerar as bibliotecas do JavaScript que podem ser usadas com o Sdk.Soap.js da mesma forma que você pode usar as bibliotecas de mensagens do sistema fornecidas nesse exemplo. Os arquivos gerados com o Gerador de mensagens de ação do Sdk.Soap.js são separados das bibliotecas do JavaScript para cada ação. Cada biblioteca contém uma classe de solicitação e resposta que corresponde às classes geradas pela CrmSvcUtil.

Executar uma ação usando um processo

Você pode executar uma ação de fluxos de trabalho, de diálogos ou de outras ações de processo. As ações personalizadas ativadas estão disponíveis para processos por meio da seleção do item Executar Ação na lista suspensa Adicionar Etapa do formulário de processo do aplicativo Web. Após a adição da etapa ao seu processo, você poderá selecionar sua nova ação personalizada (ou qualquer ação) na lista Ação fornecida na etapa. Escolha Definir Propriedades na etapa para especificar todos os parâmetros de entrada exigidos por sua ação personalizada.

Observação

Se uma ação personalizada tiver tipos de parâmetro sem suporte, por exemplo, Lista de Seleção, Entidade ou Conjunto de Entidades, a ação personalizada não constará na lista Ação.

A capacidade de executar uma ação de um processo foi introduzida no Atualização 1 do Microsoft Dynamics CRM Online 2015.

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

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

Se uma das etapas do 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 no ambiente isolado do tempo de execução da área restrita e estará sujeita ao limite de dois minutos do tempo limite, de forma semelhante a como os plug-ins da área restrita são gerenciados. No entanto, não existem restrições quanto à quantidade de tempo total que a ação pode levar. Além disso, se uma ação participar de uma transação, na qual uma reversão esteja habilitada, os tempos limite do SQL Server serão aplicados.

Dica

A recomendação de uma boa prática é que as operações de longa execução sejam executadas fora do Microsoft Dynamics 365 com processos assíncronos do .NET ou de segundo plano.

Confira Também

Criar fluxos de trabalho em tempo real
Use diálogos para processos guiados
Pipeline de execução do evento
Gravar fluxos de trabalho para automatizar processos empresariais
TechNet: Personalizar seu sistema

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais