Créer vos propres actions

  • Article

Vous pouvez étendre la fonctionnalité de Dynamics 365 Customer Engagement (on-premises) en créant des messages personnalisés appelés actions. Ces actions auront associé des classes de demande/réponse et une action d’API web sera générée. Les actions sont généralement utilisées pour ajouter une nouvelle fonctionnalité spécifique au domaine au service web de l’organisation ou pour combiner plusieurs demandes de message de service web dans une seule demande. Par exemple, dans un centre d’appels technique, vous pouvez combiner les messages Create, Assign et Setstate en un nouveau message unique Escalate.

La logique métier d’une action est mise en œuvre à l’aide d’un workflow. Lorsque vous créez une action, le workflow en temps réel associé est automatiquement enregistré pour s’exécuter à la phase 30 (opération principale) du pipeline d’exécution. Pour plus d’informations sur les workflows en temps réel, voir Types de workflow.

Lorsque des actions sont prises en charge dans Dynamics 365 for Customer Engagement, la création d’une action dans le code (avec XAML) est uniquement prise en charge par les déploiements locaux et IFD. Les clients en ligne doivent créer des actions de façon interactive dans l’application web.

 

À propos des définitions d’action

Une action est définie à l’ aide d’un enregistrement d’entité Workflow, similaire à un workflow en temps réel. Certains points clés de la définition d’une action et de la manière dont elle fonctionne figurent dans la liste suivante :

  • Peut être associée à une entité unique ou être globale (non associée à toute entité particulière).

  • Est exécutée dans la phase 30 de l’opération principale du pipeline d’exécution de l’évènement.

  • Prend en charge l’invocation des plug-ins enregistrés dans les phases de pré-exploitation et de post-exploitation du pipeline d’exécution de l’évènement.

  • Peut posséder des plug-ins enregistrés dans les phases de pré-exploitation ou de post-exploitation uniquement lorsque l’état de l’action est Activée.

  • Est disponible via l’API web ou les points de terminaison organization.svc et organization.svc/web.

  • Peut être exécutée à l’aide d’une ressource Web JavaScript. Plus d’informations : Exécuter une action à l’aide d’une ressource web JavaScript

  • Est toujours exécutée dans le contexte de sécurité de l’utilisateur appelant.

  • L’enregistrement ne peut pas être supprimé tandis que plusieurs étapes de plug-in sont enregistrées sur l’action.

  • Peut éventuellement, via un paramètre de configuration, participer à la transaction actuelle de la base de données.

  • Ne prend pas en charge une étendue où l’exécution est restreinte à un utilisateur, une division ou une organisation. Les actions s’exécutent toujours dans l’étendue de l’organisation.

  • Prend en charge les arguments d’entrée et de sortie.

  • Prend en charge l’audit des modifications de données.

  • N’est pas prise en charge lorsque les clients sont hors ligne.

  • Peut être appelé par un appel de méthode de service web.

  • Peut être appelé directement à partir d’un workflow.

Autorisations requises

Un privilège de sécurité nommé Activer les processus en temps réel (prvActivateSynchronousWorkflow) est nécessaire pour activer un workflow d’action en temps réel, afin de pouvoir l’exécuter. Cela vient en complément de tout privilège requis pour créer un workflow.

Créer une action à l’aide d’un code

En règle générale, une action peut être mise en œuvre par un personnalisateur à l’aide d’un concepteur interactif de workflow de l’application web. Toutefois, les développeurs peuvent implémenter des actions avec les appels du kit de développement logiciel (SDK) et les déployer sur un serveur local ou IFD, le cas échéant.

Les attributs de l’entité workflow utilisés pour une action sont décrits dans le tableau suivant. Vous trouverez un exemple de code pour un workflow en temps réel dans la rubrique Créer un workflow en temps réel dans le code.

Attribut de workflow Description
Category Définir sur WorkflowCategory.CustomOperation.
SyncWorkflowLogOnError Lorsque true, les erreurs sont connectées aux enregistrements ProcessSession. Contrairement aux workflows asynchrones, l’exécution de workflow en temps réel n’est pas connectée aux enregistrements System Job.
Mode Pas utilisé.
IsTransacted Définir sur true si l’action doit participer à la transaction de la base de données ; sinon, false. La valeur par défaut est true.
UniqueName Un nom unique pour l’action. Le nom est composé d’un préfixe d’éditeur + « _ » + le nom unique.
Xaml Définir sur le code XAML qui définit le workflow en temps réel de votre action. Il n’existe pas de moyen de faire référence à un autre workflow existant en temps réel.

Ajouter les arguments d’entrée et de sortie

Les actions prennent en charge les arguments d’entrée et de sortie qui peuvent être ajoutés au workflow à l’aide d’un type DynamicActivityProperty. Lorsque vous ajoutez ces arguments à un workflow d’action, ils deviennent les propriétés dans la demande de message et les classes de réponse associées à cette action. Par exemple, l’exemple suivant indique C# et le code XAML pour deux arguments d’entrée et un de sortie.

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>

Les noms utilisés pour les propriétés doivent être cohérents avec les noms d’arguments puisque la génération du code définira ces noms comme propriétés de demande ou de réponse.

Les types d’arguments pris en charge pour les arguments d’entrée et de sortie sont affichés dans le tableau suivant.

Type .NET Type d’argument
System.Int32 Entier
System.String Chaîne
EntityReference EntityReference
Entity Entité
EntityCollection EntityCollection
System.DateTime Date/Heure
System.Double Flottant
System.Decimal Décimal
Money Devise
System.Boolean Booléen
OptionSetValue Liste déroulante

Les attributs d’argument pris en charge sont répertoriés dans le tableau suivant.

Attribut Argument Description
ArgumentRequiredAttribute Indique si l’argument est nécessaire.
ArgumentDirectionAttribute Indique si la direction de l’argument est une entrée ou une sortie.
ArgumentDescriptionAttribute Spécifie une description pour l’argument.
ArgumentEntityAttribute Utilisé si vous souhaitez passer dans une entité.
ArgumentTargetAttribute Cet attribut est généré ou ajouté automatiquement. Il pointe vers l’entité principale pour laquelle le workflow est exécuté. Cet attribut est facultatif pour les actions globales.

Englober une action pour la distribution

Pour distribuer votre action de sorte à l’importer dans une organisation Dynamics 365 Customer Engagement (on-premises), ajoutez votre action à une solution Customer Engagement. Cela se fait facilement à l’aide de l’application web en accédant à Paramètres>Personnalisations>Solutions. Vous pouvez également écrire du code pour créer la solution. Pour plus d’informations sur les solutions, voir Conditionner et distribuer des extensions.

Générer des types de liaison anticipée pour une action

En utilisant l’outil CrmSvcUtil, vous pouvez générer des classes de demande et de réponse pour votre action afin d’inclure votre code d’application. Toutefois, avant de générer ces classes, veillez à activer l’action.

Pour télécharger l’outil CrmSvcUtil.exe, voir Outils de développement Dataverse.

L’exemple suivant présente le format d’exécution de l’outil à partir de la ligne de commande pour une installation locale de Customer Engagement. Indiquez les valeurs des paramètres pour votre installation.

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

L’exemple suivant présente le format d’exécution de l’outil à partir de la ligne de commande avec Dynamics 365 for Customer Engagement. Indiquez les valeurs de paramètre appropriées pour vos compte et serveur.

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

Notez l’utilisation du paramètre /generateActions. En savoir plus : Créer des classes d’entité à liaison anticipée à l’aide de l’outil de génération de code (CrmSvcUtil.exe).

Vous pouvez utiliser les types de liaison anticipée ou tardive avec les classes de demande et de réponse générées pour votre action.

Exécuter une action à l’aide de l’API web

Une nouvelle action est créée dans l’API web lors de sa création. Si l'action est créée dans le contexte d'une entité, elle est liée à cette entité. Sinon il s'agit d'une action non liée. Pour plus d'informations, consultez Utiliser les actions de l'API Web.

Exécutez une action à l’aide d’une ressource web JavaScript

Une action peut être exécutée à l’aide de l’API web comme n’importe quelle action système. Plus d’informations : Xrm.WebApi.online.execute

Exécuter une action à l’aide du service de l’organisation

Pour exécuter une action à l’aide du service web de l’organisation via le code géré, suivez les étapes suivantes.

  1. Ajoutez le fichier de type liaison anticipée que vous avez généré à l’aide de l’outil CrmSvcUtil dans le projet de votre application.

  2. Dans votre code d’application, instanciez la demande de votre action et importez toutes les propriétés nécessaires.

  3. Invoquez Execute, en transmettant votre demande comme argument.

    Avant d’exécuter votre code d’application, assurez-vous que l’action est activée. Sinon, vous recevrez une erreur d’exécution.

Exécuter une action à l’aide d’un processus

Vous pouvez exécuter une action à partir de workflows, de boîtes de dialogue ou d’autres actions de processus. Les actions personnalisées activées sont disponibles pour les processus en sélectionnant l’élément Exécuter l’action du menu déroulant Ajouter une étape du formulaire processus d’application web. Une fois l’étape ajoutée à votre processus, vous pouvez sélectionner votre nouvelle action personnalisée (ou n’importe quelle action) dans la liste Action indiquée dans l’étape. Sélectionnez Définir les propriétés dans l’étape pour spécifier les paramètres d’entrée nécessaires pour votre action personnalisée.

Note

Si une action personnalisée contient des types de paramètres non pris en charge, par exemple Liste déroulante, Entité ou Collection d’entités, l’action personnalisée n’est pas répertoriée dans la liste Action.

La possibilité d’exécuter une action à partir d’un processus a été introduite dans Dynamics CRM Online 2015 Update 1.

Les vérifications de la plateforme Depth existantes garantissent l’absence d’une boucle infinie. Pour plus d’informations sur ces limites de profondeur, voir MaxDepth.

Rechercher les actions longues

Si l’une des étapes du workflow de l’action en temps réel est une activité de workflow personnalisée, cette activité de workflow personnalisée est exécutée au sein de l’environnement d’exécution bac à sable isolé et sera soumise à la limite de délai de deux minutes, de la même façon que les plug-ins bac à sable sont gérés. Toutefois, il n’y a aucune limite quant au temps total que peut prendre l’action en elle-même. En outre, si une action participe à une transaction, où la restauration activée, des délais d’expiration SQL Server s’appliqueront.

Pourboire

Il est recommandé que les opérations longues soient exécutées en dehors de Dynamics 365 Customer Engagement (on-premises) en utilisant les processus en arrière-plan ou asynchrone .NET.

Voir aussi

Créer des workflows en temps réel
Utiliser des dialogues pour les processus guidés
Pipeline d’exécution des événements
Écrire des workflows pour automatiser les processus d’entreprise
Personnaliser votre système