Xrm.Utility (référence côté client)

Date de publication : janvier 2017

S’applique à : Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

L'objet Xrm.Utility fournit un conteneur pour les fonctions utiles qui ne sont pas associées directement à la page actuelle.

Ces fonctions sont disponibles dans chaque page d'application prenant en charge la création de scripts. Vous pouvez les utiliser dans des scripts de formulaire ou dans les commandes du ruban. Pour les ressources Web HTML, elles sont disponibles lorsque vous incluez la page ClientGlobalContext.js.aspx. Pour plus d'informations, voir Fonction GetGlobalContext et ClientGlobalContext.js.aspx (référence côté client).

Fonctions

• Boîtes de dialogue
  Utilisez les messages d'affichage alertDialog et confirmDialog pour les utilisateurs et définissez le code pour qu'il s'exécute en fonction de leur réponse. Ces fonctions doivent être utilisées avec les clients mobiles Dynamics 365 (téléphones et tablettes) à la place des méthodes window.alert et window.confirm.

• Fonctionnalités natives des appareils (clients mobiles Dynamics 365)
  Utilisez getBarcodeValue et getCurrentPosition pour utiliser les fonctionnalités natives des appareils mobiles pour récupérer la valeur de code-barres ou la position actuelle de l'appareil.

• isActivityType
  Déterminez si une entité est une entité d'activité.

• openEntityForm
  Ouvre un formulaire d’entité.

• openQuickCreate
  Pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure, utilisez cette fonction pour ouvrir un nouveau formulaire de création rapide. Vous pouvez utiliser cette fonction pour définir les valeurs par défaut à l'aide des mappages d'attributs ou d'attributs spécifiques. Si l'utilisateur enregistre l'enregistrement, vous pourrez recueillir une référence à l'enregistrement créé.

• openWebResource
  Ouvre une ressource web HTML.

Boîtes de dialogue

Il existe deux types de boîtes de dialogue : alertDialog et confirmDialog. Elles sont incluses pour être utilisées avec des scripts qui fonctionnent avec les clients mobiles Dynamics 365 (téléphones et tablettes). Les clients mobiles Dynamics 365 ne permettent pas l'utilisation de fonctions JavaScript qui bloquent le flux du code comme window.alert et window.confirm. Utilisez ces méthodes à la place de ces méthodes si vous devez afficher un message à l'utilisateur. La différence principale réside dans le fait que ces méthodes ne bloquent pas le code jusqu'à ce qu'un utilisateur les ferme. Elles contiennent un paramètre de fonction de rappel pour indiquer quel code doit être exécuté selon les réponses des utilisateurs.

alertDialog

Affiche la boîte de dialogue contenant un message défini par l'application.

Xrm.Utility.alertDialog(message,onCloseCallback)

• Paramètres

  Nom	Type	Obligatoire	Description
  message	Chaîne	Oui	Texte du message à afficher dans la boîte de dialogue.
  onCloseCallback	Fonction	Non	Fonction à exécuter lorsque le bouton OK est actionné.

• Remarques
  Cette méthode est uniquement disponible pour Entités mises à jour.

confirmDialog

Affiche la boîte de dialogue de confirmation qui contient un message facultatif, ainsi que les boutons OK et Annuler.

Xrm.Utility.confirmDialog(message,yesCloseCallback,noCloseCallback)

• Paramètres

  Nom	Type	Obligatoire	Description
  message	Chaîne	Oui	Texte du message à afficher dans la boîte de dialogue
  yesCloseCallback	Fonction	Non	Fonction à exécuter lorsque le bouton OK est actionné.
  noCloseCallback	Fonction	Non	Fonction à exécuter lorsque le bouton Annuler est actionné.

• Remarques
  Cette méthode est uniquement disponible pour Entités mises à jour.

Fonctionnalités natives des appareils (clients mobiles Dynamics 365)

Utilisez ces méthodes pour les clients Dynamics 365 pour téléphones et Dynamics 365 pour tablettes pour aider à enrichir l'expérience d'utilisateur des utilisateurs d'entreprise mobiles dans les domaines de la vente, du service après-vente, etc.

getBarcodeValue

Renvoie les informations de code-barres, telles qu'un numéro de produit, numérisées à l'aide de la caméra de l'appareil.

Xrm.Utility.getBarcodeValue().then(successCallback, errorCallback)

• Paramètres

  Nom	Type	Nécessaire	Description
  successCallback	Fonction	Oui	Fonction à appeler lorsque la valeur du code-barres est renvoyée.
  errorCallback	Fonction	Oui	Fonction à appeler lorsque l'opération échoue. Un objet d'erreur avec la propriété message est passé et décrit les détails de l'erreur.

• Remarques
  Pour que la méthode getBarcodeValue puisse fonctionner, les clients mobiles Dynamics 365 doivent avoir accès à la caméra de l'appareil, qui est activée par défaut.

• Exemple
  L'exemple de code suivant illustre l'utilisation de cette méthode.

  Xrm.Utility.getBarcodeValue().then(
      function (result) {
          Xrm.Utility.alertDialog("Barcode value: " + result);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

getCurrentPosition

Renvoie la position actuelle à l'aide de la fonctionnalité de géolocalisation de l'appareil.

Xrm.Utility.getCurrentPosition().then(successCallback, errorCallback)

• Paramètres

  Nom	Type	Nécessaire	Description
  successCallback	Fonction	Oui	Fonction à appeler lorsque les informations de géolocalisation actuelles sont renvoyées. Un objet de géolocalisation avec les attributs suivants est passé à la fonction. coords : contient un ensemble de coordonnées géographiques avec la précision associée, ainsi qu'un ensemble d'autres attributs facultatifs tels que l'altitude et la vitesse. timestamp : représente la date d'acquisition de l'objet qui est représentée en tant que DOMTimeStamp.
  errorCallback	Fonction	Oui	Fonction à appeler lorsque l'opération échoue. Un objet avec les propriétés suivantes est transmis : code : nombre. Code d’erreur. message : chaîne. Message localisé décrivant les détails de l'erreur. Si le paramètre d'emplacement de l'utilisateur n'est pas activé sur votre appareil mobile, le message d'erreur indique la même information. Si vous utilisez une version antérieure du client mobile Dynamics 365 ou si la fonctionnalité de géolocalisation n'est pas disponible sur votre appareil mobile, null est passé au rappel d'erreur.

• Remarques
  Pour que la méthode getCurrentPosition puisse fonctionner, la fonctionnalité de géolocalisation doit être activée sur votre appareil, et les clients mobiles Dynamics 365 doivent disposer d'autorisations pour accéder à l'emplacement de l'appareil, qui n'est pas activé par défaut.

• Exemple
  L'exemple de code suivant illustre l'utilisation de cette méthode.

  Xrm.Utility.getCurrentPosition().then
      (function (location) {
          Xrm.Utility.alertDialog("Latitude: " + location.coords.latitude +
             ", Longitude: " + location.coords.longitude);
      },
      function (error) {
          Xrm.Utility.alertDialog(error.message);
      })
  

isActivityType

Déterminez si une entité est une entité d'activité.

Xrm.Utility.isActivityType(entityName)

• Paramètre

  Nom	Type	Obligatoire	Description
  entityName	Chaîne	Oui	Nom logique d'une entité.

• Valeur renvoyée

  Type	Description
  Booléen	Vrai si l'entité est une entité d'activité, sinon faux.

openEntityForm

Ouvre un formulaire d'entité pour un nouvel enregistrement d'entité ou existant à l'aide des options définies en tant que paramètres.

Xrm.Utility.openEntityForm(name,id,parameters,windowOptions)

• Paramètres

  Nom	Type	Obligatoire	Description
  nom	Chaîne	Oui	Nom logique de l’entité.
  id	Chaîne	Non	La representation de la chaîne d'un identificateur unique ou de l'enregistrement à ouvrir dans le formulaire. Si elle n'est pas définie, un formulaire visant à créer un enregistrement est ouvert.
  parameters	Objet	Non	Objet de dictionnaire qui transmet des paramètres supplémentaires au formulaire. Des paramètres non valides provoquent une erreur. Les paramètres de chaîne de requête supplémentaires valides sont : ID de formulaire : Pour définir la valeur d'ID du formulaire principal à utiliser lorsque plusieurs formulaires sont disponibles. Le paramètre est formid. ID de champ par défaut : Pour définir les valeurs par défaut d'un nouveau formulaire de enregistrement. Pour plus d'informations, voir Définir les valeurs de champ utilisant les paramètres transmis à un formulaire. Les paramètres navbar et cmdbar décrits dans Paramètres de chaîne de requête pour la page Main.aspx. Paramètres de chaîne de requête personnalisés : Un formulaire peut être configuré afin d'accepter les paramètres de chaîne de requête personnalisés. Pour plus d'informations, voir Configurer un formulaire pour accepter les paramètres de chaîne de requête personnalisés.
  windowOptions	Objet	Non	Pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure, utilisez ce paramètre optionnel dans l'application Web pour contrôler le mode d'ouverture du formulaire. Vous pouvez ouvrir un formulaire dans une nouvelle fenêtre en passant un objet de dictionnaire avec une propriété openInNewWindow booléenne définie sur true. Ce paramètre est ignoré dans les clients mobiles Dynamics 365 (téléphones et tablettes).

• Remarques
  L'utilisation de cette fonction permet de s'assurer que les utilisateurs ne sont pas invités à ouvrir une nouvelle session dans certains cas.

• Exemples
  Ouvrir un nouvel enregistrement de compte à l'aide du formulaire par défaut

  Xrm.Utility.openEntityForm("account");
  

  Ouvrir un enregistrement de compte existant à l'aide du formulaire par défaut

  Xrm.Utility.openEntityForm("account","A85C0252-DF8B-E111-997C-00155D8A8410");
  

  Ouvrir un nouvel enregistrement de compte avec un formulaire spécifique et définir des valeurs par défaut

  var parameters = {};
  parameters["formid"] = "b053a39a-041a-4356-acef-ddf00182762b";
  parameters["name"] = "Test";
  parameters["telephone1"] = "(425) 555-1234";
  Xrm.Utility.openEntityForm("account", null, parameters);
  

  Ouvrir un nouvel enregistrement de compte à l'aide du formulaire par défaut dans une nouvelle fenêtre

  var windowOptions = {
   openInNewWindow: true
  };
  Xrm.Utility.openEntityForm("account",null,null,windowOptions);
  

openQuickCreate

Pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure, utilisez cette fonction pour ouvrir un nouveau formulaire de création rapide. Vous pouvez utiliser cette fonction pour définir les valeurs par défaut à l'aide des mappages d'attributs ou d'attributs spécifiques. Si l'utilisateur enregistre l'enregistrement, vous pourrez recueillir une référence à l'enregistrement créé.

Xrm.Utility.openQuickCreate(entityLogicalName,createFromEntity,parameters).then(successCallback, errorCallback);

• Paramètres

  Nom	Type	Obligatoire	Description
  entityLogicalName	Chaîne	Oui	Nom logique de l'entité à créer.
  createFromEntity	Recherche	Non	Désigne un enregistrement qui fournira des valeurs par défaut en fonction des valeurs d'attribut mappées. Un objet de recherche contient les propriétés String suivantes : entityType : Nom logique de l'entité. id : Représentation sous forme de chaîne d'une valeur GUID de l'enregistrement. name : Valeur d'attribut principal de l'enregistrement.
  parameters	Objet	Non	Objet de dictionnaire qui transmet des paramètres de chaîne de requête supplémentaires au formulaire. Des paramètres de chaîne de requête non valides provoquent une erreur. Les paramètres de chaîne de requête supplémentaires valides sont : ID de champ par défaut : Pour définir les valeurs par défaut d'un nouveau formulaire de enregistrement. Pour plus d'informations, voir Définir les valeurs de champ utilisant les paramètres transmis à un formulaire. Paramètres de chaîne de requête personnalisés : Un formulaire peut être configuré afin d'accepter les paramètres de chaîne de requête personnalisés. Pour plus d'informations, voir Configurer un formulaire pour accepter les paramètres de chaîne de requête personnalisés.
  successCallback	Fonction	Non	Fonction qui sera appelée lorsqu'un enregistrement est enregistré. Un objet est transmis à cette fonction en tant que paramètre. Cet objet a une propriété savedEntityReference avec les propriétés suivantes pour identifier l'enregistrement créé : entityType : Nom logique de l'entité. id : Représentation sous forme de chaîne d'une valeur GUID de l'enregistrement. name : Valeur d'attribut principal de l'enregistrement créé.
  errorCallback	Fonction	Non	Fonction à appeler lorsque l'opération échoue. Un objet avec les propriétés suivantes est transmis : errorCode : Number. Code d’erreur. message : String. Message d'erreur localisé.

• Remarques
  Cette fonction est uniquement disponible pour Mise à jour 1 de Microsoft Dynamics CRM Online 2015 ou version ultérieure.

  Il existe une limite de 10 formulaires de création rapide imbriqués dans l'application Web. Si cette limite est dépassée, cette fonction ouvrira le formulaire d'entité complet au lieu du formulaire de création rapide.

• Exemple
  Lorsque ce code est exécuté dans un formulaire d'entité de compte, un formulaire de création rapide pour créer un nouveau compte enfant avec un nom par défaut est défini pour inclure le nom du compte parent.

  var thisAccount = {
      entityType: "account",
      id: Xrm.Page.data.entity.getId()
  };
  var callback = function (obj) {
      console.log("Created new " + obj.savedEntityReference.entityType + " named '" + obj.savedEntityReference.name + "' with id:" + obj.savedEntityReference.id);
  }
  var setName = { name: "Child account of " + Xrm.Page.getAttribute("name").getValue() };
  Xrm.Utility.openQuickCreate("account", thisAccount, setName).then(callback, function (error) {
      console.log(error.message);
  });
  

  Si ce code est exécuté avec les outils de développement du navigateur (outils F12), la suite décrira la sortie sur la console lors de l'exécution dans le contexte d'un compte nommé « A. Datum Corporation (sample) » et l'utilisateur ne modifiera pas le nom par défaut défini pour le nouveau compte enfant.

  Created new account named 'Child account of A. Datum Corporation (sample)' with id:{1D4BFF87-E8C5-E411-80CF-00155DB58496}
  

openWebResource

Ouvre une ressource web HTML.

Xrm.Utility.openWebResource(webResourceName,webResourceData,width, height)

• Paramètres

  Nom	Type	Nécessaire	Description
  webResourceName	Chaîne	Oui	Nom de la ressource Web HTML à ouvrir.
  webResourceData	Chaîne	Non	Données à transmettre dans le paramètre de données.
  width	Numéro	Non	Largeur de la fenêtre à ouvrir en pixels.
  height	Numéro	Non	Hauteur de la fenêtre à ouvrir en pixels.

• Valeur renvoyée
  Objet de fenêtre.

• Remarques
  Une ressource Web HTML peut accepter les valeurs de paramètres décrites dans Transmettre les paramètres aux ressources Web HTML. Cette fonction assure uniquement le transfert du paramètre de données facultatif. Pour transmettre les valeurs des autres paramètres non valides, vous devez les ajouter au paramètre webResourceName.

• Exemples
  Ouvrir une ressource Web HTML nommée « new_webResource.htm »

  Xrm.Utility.openWebResource("new_webResource.htm");
  

  Ouvrir une ressource Web HTML, notamment un élément unique des données du paramètre de données

  Xrm.Utility.openWebResource("new_webResource.htm","dataItemValue");
  

  Ouvrir une ressource Web HTML en transmettant plusieurs valeurs via le paramètre de données

  var customParameters = encodeURIComponent("first=First Value&second=Second Value&third=Third Value");
  Xrm.Utility.openWebResource("new_webResource.htm",customParameters);
  

  Notes

  Ces valeurs doivent être extraites de la valeur du paramètre de données dans la ressource Web HTML. Pour plus d'informations, consultez la rubrique Exemple : Transmettre plusieurs valeurs à une ressource Web via le paramètre de données.

  Ouvrir une ressource Web HTML avec les paramètres prévus par les ressources Web HTML

  Xrm.Utility.openWebResource("new_webResource.htm?typename=account&userlcid=1033");
  

  Pour plus d'informations, voir Transmettre les paramètres aux ressources Web HTML.

  Ouvrir une ressource Web HTML, en définissant la hauteur et la largeur

  Xrm.Utility.openWebResource("new_webResource.htm", null, 300,300);
  

Voir aussi

Référence par programmation côté client
Ouvre les formulaires, vues, boîtes de dialogue et rapports avec une URL
Définir les valeurs de champ utilisant les paramètres transmis à un formulaire
Configurer un formulaire pour accepter les paramètres de chaîne de requête personnalisés
Référence rapide des scripts de formulaires
Écrire du code pour les formulaires Microsoft Dynamics 365
Utiliser le modèle d’objet Xrm.Page

Microsoft Dynamics 365

© 2017 Microsoft. Tous droits réservés. Copyright