Crear acciones propias

  • Artículo

 

Publicado: enero de 2017

Se aplica a: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Para ampliar la funcionalidad de Microsoft Dynamics 365, 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 Create, Assigny Setstate en un único mensaje nuevo Escalate.

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 Categorías de proceso de Dynamics 365.

Si bien las acciones se admiten en Microsoft Dynamics 365 (en línea y local), 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.

En este tema

Acerca de las definiciones de acción

Permisos requeridos

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

Empaquetar una acción para la distribución

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

Ejecutar una acción con la API web

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

Ejecute una acción mediante un proceso

Observar las acciones de ejecución prolongada

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 con los extremos organization.svc y organization.svc/web, pero no con el extremo organizationdata.svc (OData).

  • 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. Para obtener más información sobre estos privilegios, consulte la asignación de la interfaz de usuario de privilegio en Personalización.

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 el código de ejemplo para un flujo de trabajo en tiempo real en el tema Crear un flujo de trabajo en tiempo real en el 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

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

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 Microsoft Dynamics 365, agregue la acción a una solución de Dynamics 365. 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 acerca de las soluciones, consulte Empaquetar y distribuir las extensiones con soluciones.

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

Con la herramienta CrmSvcUtil que se entrega en el paquete de SDK, 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.

Descargue el paquete de SDK de Microsoft Dynamics CRM.

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

    CrmSvcUtil.exe /url:http://<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 Microsoft Dynamics 365 (online). 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 las 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 información:Usar acciones de la API web.

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.

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:Usar acciones de la API web.

La biblioteca de ejemplo de Sdk.Soap.js muestra cómo se pueden usar los mensajes con los recursos web de JavaScript y el servicio de organización (organization.svc/web). Use el ejemplo complementario Generador de mensaje de acción de Sdk.Soap.js para generar bibliotecas de JavaScript que se pueden usar con Sdk.Soap.js de la misma forma en que puede usar las bibliotecas para los mensajes del sistema proporcionados en dicho ejemplo. Los archivos generados con el Generador de mensaje de acción de Sdk.Soap.js son bibliotecas de JavaScript independientes para cada acción. Cada biblioteca contiene una clase de solicitud y respuesta que se corresponde con las clases generadas por la herramienta CrmSvcUtil.

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 Actualización 1 de Microsoft Dynamics CRM Online 2015.

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.

Sugerencia

Una de las prácticas recomendadas consiste en ejecutar las operaciones de ejecución prolongada fuera de Microsoft Dynamics 365 con procesos asincrónicos .NET o en segundo plano.

Ver también

Crear flujos de trabajo en tiempo real
Usar diálogos en Dynamics 365 para procesos guiados
Canalización de ejecución del evento
Automatizar procesos de negocio mediante proceso de Dynamics 365
TechNet: Personalizar el sistema

Microsoft Dynamics 365

© 2017 Microsoft. Todos los derechos reservados. Copyright