Crear acciones propias

  • Artículo

Para ampliar la funcionalidad de Dynamics 365 Customer Engagement (on-premises), puede crear mensajes personalizados denominados acciones. Estas acciones tendrán clases de solicitud/de respuesta asociadas y se generará una acción API web. Por lo general, las acciones se utilizan para agregar una nueva funcionalidad específica del dominio al servicio web de la organización o para combinar varias solicitudes de mensaje de servicio web de la organización en una sola solicitud. Por ejemplo, en un centro de atención telefónica de soporte técnico, es posible que desee combinar los mensajes Crear, Asignar y Setstate en un único mensaje nuevo Escalar.

La lógica de negocios de una acción se implementa mediante un flujo de trabajo. Cuando crea una acción, el flujo de trabajo asociado en tiempo real se registra automáticamente para ejecutarse en la fase 30 (operación principal) de la canalización de ejecuciones. Para obtener más información sobre flujos de trabajo en tiempo real, consulte Tipos de flujo de trabajo.

Si bien las acciones se admiten en Dynamics 365 for Customer Engagement, la creación de una acción en código (mediante XAML) se admite únicamente para las implementaciones locales y con conexión a Internet (IFD). Los clientes de Online deben crear acciones interactivamente en la aplicación web.

 

Acerca de las definiciones de acción

Para definir una acción se utiliza un registro de entidad Workflow, similar a un flujo de trabajo en tiempo real. En la lista siguiente se detallan algunos puntos clave acerca de qué es y cómo funciona una acción:

  • Se puede asociar con una sola entidad o ser global (no asociada con ninguna entidad determinada).

  • Se ejecuta en la fase 30 de la operación principal de la canalización de ejecuciones de eventos.

  • Admite la invocación de complementos registrados en las fases de operación previa y posterior de la canalización de ejecuciones de eventos.

  • Puede tener complementos registrados en las fases de operación previa y posterior solo cuando el estado de la acción es Activado.

  • Está disponible a través de la API web o los extremos organization.svc y organization.svc/web.

  • Se puede ejecutar mediante un recurso web de JavaScript. Más información: Ejecutar una acción con un recurso web de JavaScript

  • Siempre se ejecuta en el contexto de seguridad del usuario que llama.

  • El registro no se puede eliminar mientras hay pasos de complementos registrados en la acción.

  • De manera opcional, mediante una opción de configuración, puede participar en la transacción de la base de datos actual.

  • No admite un ámbito cuando la ejecución está limitada a un usuario, una unidad de negocio o una organización. Las acciones siempre se ejecutan en el ámbito de la organización.

  • Admite argumentos de entrada y salida.

  • Admite la auditoría de cambios de datos.

  • No es compatible con clientes sin conexión.

  • Puede ser invocado por una llamada a un método de servicio web.

  • Puede ser invocado directamente desde un flujo de trabajo.

Permisos requeridos

Se requiere un privilegio de seguridad denominado Activar procesos en tiempo real (prvActivateSynchronousWorkflow) para activar el flujo de trabajo en tiempo real de una acción para que pueda ejecutarse. Esto es además de los privilegios necesarios para crear un flujo de trabajo.

Crear una acción mediante el uso de código

Normalmente, un personalizador implementaría una acción mediante el diseñador de flujo de trabajo interactivo de la aplicación web. Sin embargo, los desarrolladores pueden implementar acciones mediante llamadas de SDK e implementarlas en un servidor local o con conexión a Internet (IFD) si lo desean.

Los atributos de la entidad de flujo de trabajo que se usan para una acción se describen en la tabla siguiente. Puede encontrar código de ejemplo de un flujo de trabajo en tiempo real en el tema Crear un flujo de trabajo en tiempo real en código.

Atributo de flujo de trabajo Descripción
Category Establecido en WorkflowCategory.CustomOperation.
SyncWorkflowLogOnError Si es true, los errores se registran en registros ProcessSession. A diferencia de los flujos de trabajo asincrónicos, la ejecución de los flujos de trabajo en tiempo real no se registra en registros System Job.
Mode No se utiliza.
IsTransacted Se establece en true si la acción debe participar en la transacción de la base de datos; de lo contrario, false. El valor predeterminado es true.
UniqueName Un nombre único para la acción. El nombre se compone de un prefijo del editor + "_" + el nombre único.
Xaml Se establece en el código XAML que define el flujo de trabajo en tiempo real de la acción. No hay ninguna forma de hacer referencia a otro flujo de trabajo en tiempo real existente.

Agregar argumentos de entrada y salida

Las acciones admiten argumentos de entrada y salida que se pueden agregar al flujo de trabajo mediante el uso de un tipo DynamicActivityProperty. Cuando se agregan estos argumentos al flujo de trabajo de una acción, se convierten en propiedades en las clases de solicitud de mensaje y respuesta asociadas con dicha acción. Por ejemplo, el siguiente ejemplo muestra el código C# y XAML para dos argumentos de entrada y uno de salida.

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>

Los nombres usados para las propiedades deben ser coherentes con los nombres de argumentos ya que la generación de código definirá estos nombres como propiedades de solicitud o respuesta.

Los tipos de argumentos admitidos para los argumentos de entrada y salida se muestran en la tabla siguiente.

Tipo .NET Tipo de argumento
System.Int32 Entero
System.String String
EntityReference EntityReference
Entity Entity
EntityCollection EntityCollection
System.DateTime DateTime
System.Double Flotante
System.Decimal Decimal
Money Dinero
System.Boolean Boolean
OptionSetValue Picklist

Los atributos de argumentos admitidos se muestran en la tabla siguiente.

Atributo de argumento Descripción
ArgumentRequiredAttribute Indica si se requiere el argumento.
ArgumentDirectionAttribute Indica si la dirección del argumento es de entrada o salida.
ArgumentDescriptionAttribute Especifica una descripción para el argumento.
ArgumentEntityAttribute Se utiliza si desea transmitir una entidad.
ArgumentTargetAttribute Este atributo se genera o agrega automáticamente. Señala la entidad principal para la que se ejecuta el flujo de trabajo. Este atributo es opcional para las acciones globales.

Empaquetar una acción para la distribución

Para distribuir la acción de modo que se pueda importar a una organización de aplicaciones Dynamics 365 Customer Engagement (on-premises), agregue la acción a una solución de Customer Engagement. Esto se realiza fácilmente usando la aplicación web y desplazándose a Configuración>Personalizaciones>Soluciones. También puede escribir código para crear la solución. Para obtener más información sobre cómo usar soluciones, consulte Empaquetar y distribuir las extensiones.

Generar tipos de enlace en tiempo de compilación para una acción

Con la herramienta CrmSvcUtil puede generar clases de solicitud y respuesta para la acción para incluirlas en el código de aplicación. Sin embargo, antes de generar estas clases, asegúrese de activar la acción.

Para descargar CrmSvcUtil.exe, consulte las herramientas de desarrollo de Dataverse.

El siguiente ejemplo muestra el formato para ejecutar la herramienta desde la línea de comandos para una instalación local de aplicaciones Customer Engagement. Se suministran los valores de los parámetros para la instalación.

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

El siguiente ejemplo muestra el formato para ejecutar la herramienta desde la línea de comandos con Dynamics 365 for Customer Engagement. Se suministran los valores de los parámetros adecuados para su cuenta y 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

Tenga en cuenta el uso del parámetro /generateActions. Más información: Crear clases de entidad con enlace en tiempo de compilación con la herramienta de generación de código (CrmSvcUtil.exe)

Puede usar tipos de enlace en tiempo de compilación y en tiempo de ejecución con las clases generadas de solicitud y respuesta para la acción.

Ejecutar una acción con la API web

Una nueva acción se crea en la API web cuando se crea. Si la acción se crea en el contexto de una entidad, está enlazada a esa entidad. Si no, es una acción sin enlazar. Más infomación: Usar acciones web API.

Ejecutar una acción con un recurso web de JavaScript

Una acción puede ejecutarse con la API web igual que cualquier acción del sistema. Más información: Xrm.WebApi.online.execute

Ejecutar una acción con el servicio de organización

Para ejecutar una acción con el servicio web de la organización por medio de código administrado, siga estos pasos.

  1. Incluya el archivo de tipos de enlace en tiempo de compilación que generó con la herramienta CrmSvcUtil en el proyecto de la aplicación.

  2. En el código de aplicación, cree una instancia de la solicitud de la acción y complete las propiedades necesarias.

  3. Invoque Execute, pasando la solicitud como un argumento.

    Antes de ejecutar el código de aplicación, asegúrese de que la acción esté activada. De lo contrario, recibirá un error de tiempo de ejecución.

Ejecute una acción mediante un proceso

Puede ejecutar una acción desde flujos de trabajo, diálogos u otras acciones del proceso. Hay acciones personalizadas activadas disponibles para los procesos seleccionando el elemento Realizar acción en el desplegable Agregar paso del formulario del proceso de aplicación web. Cuando el paso se agrega al proceso, puede seleccionar la nueva acción personalizada (o cualquier acción) desde la lista Acción proporcionado en el paso. Elija Establecer propiedades en el paso para especificar parámetros de entrada que la acción personalizada requiera.

Nota

Si una acción personalizada tiene tipos de parámetros no compatibles, por ejemplo, Lista desplegable, Entidad o Colección de entidades, la acción personalizada no se muestra en la lista Acción.

La capacidad de ejecutar una acción desde un proceso se introdujo con Dynamics CRM Online 2015 Update 1.

Las plataforma de Depth existentes comprueba para asegurarse que no se produce un bucle infinito. Para obtener más información sobre límites de profundidad, vea MaxDepth.

Observar las acciones de ejecución prolongada

Si uno de los pasos del flujo de trabajo en tiempo real de la acción es una actividad de flujo de trabajo personalizada, dicha actividad de flujo de trabajo personalizada se ejecuta dentro del entorno aislado de tiempo de ejecución en el espacio aislado y estará sujeta al límite de tiempo de espera de dos minutos, similar al modo en que se administran los complementos en el espacio aislado. Sin embargo, no hay restricciones en cuanto a la cantidad de tiempo total que la acción en sí puede tardar. Además, si la acción participa en una transacción en la que está habilitada la reversión, se aplicarán los tiempos de espera de SQL Server.

Propina

Una de las prácticas recomendadas consiste en ejecutar las operaciones de ejecución prolongada fuera de Dynamics 365 Customer Engagement (on-premises) con procesos asincrónicos .NET o en segundo plano.

Vea también

Crear flujos de trabajo en tiempo real
Usar diálogos para procesos guiados
Canalización de ejecución del evento
Escribir flujos de trabajo para automatizar los procesos de negocio
Personalizar el sistema