Compartilhar via

Criar suas próprias ações

  • Artigo

 

Publicado: janeiro de 2017

Aplicável a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

É 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 e uma ação de API da Web será gerada. 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 processo do Dynamics 365.

Embora as ações tenham suporte no Microsoft Dynamics 365 (online e local), a criação de uma ação no código (usando XAML) terá suporte somente em implantações locais 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 API da Web

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

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.

  • Pode ser diretamente invocado 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 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 365 (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 API da Web

Uma nova ação é criada no API da Web quando é ela é criada. Se a ação for criada no contexto de uma entidade, será associada à entidade. Caso contrário é uma ação desassociada.Para obter mais informações:Use ações API da Web.

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

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

Uma ação pode ser executada usando o API da Web assim como qualquer ação de sistema.Para obter mais informações:Use ações API da Web.

A biblioteca de exemplo do Sdk.Soap.js mostra como as mensagens podem ser usadas com os recursos da Web do JavaScript e o serviço da Organização (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. Selecione 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 no Dynamics 365 para processos guiados
Pipeline de execução do evento
Automatizar processos empresariais usando o processo do Dynamics 365
TechNet: Personalizar seu sistema

Microsoft Dynamics 365

© 2017 Microsoft. Todos os direitos reservados. Direitos autorais