Détails du schéma pour générer un modèle de mappage de métadonnées

S’applique à : Service Client Dynamics 365 et Centre de Contact Dynamics 365 — uniquement autonome

Cet article décrit les détails du schéma requis pour mapper les informations des fournisseurs de données externes aux entités de l’article de la base de connaissances, et comment vous pouvez préparer votre propre fichier JSON de mappage de schéma à l’aide de divers champs et attributs.

Champs

Le tableau suivant répertorie les champs et les détails de champ que vous devez utiliser dans votre schéma JSON.

Nom du champ Définition Obligatoire Valeur
Nom Nom de la définition de champ Non Chaîne indiquant le nom du champ.
UniqueTargetFieldName Identificateur unique ou autre clé de l’entité de l’article de la base de connaissances. En règle générale, ce champ est l’ID du côté du fournisseur de contenu. Oui Chaîne indiquant le nom du champ. Vous pouvez définir la valeur sur « msydn_externalreferenceid »
ContentTargetFieldName La valeur du champ ne doit pas être modifiée. Oui Définissez la valeur sur « contenu ».
ApiPathLeafName La valeur du champ ne doit pas être modifiée. Oui Réglez la valeur sur « knowledgearticles ».
List<FieldDefinitions> Est une liste de définitions de champs. Oui Un ensemble de définitions pour les champs. Consultez le tableau suivant pour obtenir la liste des champs pris en charge pour la définition des champs.

Définitions des champs

Le tableau suivant répertorie les attributs obligatoires et facultatifs que vous pouvez utiliser dans votre schéma de mappage de métadonnées.

Nom du champ Définition Obligatoire Valeur
TargetFieldName Nom de champ logique de l’attribut cible dans l’entité de l'article de la base de connaissances. Oui Toute chaîne indiquant le nom du champ cible
TargetFieldType Indique le type du champ cible. Oui Chaîne indiquant le type du champ.
DocFieldSource Indique comment la valeur du champ source est identifiée et résolue au moment de l’exécution Oui Définissez la valeur sur l’un des types de source suivants :
  • Regex
  • Meta
  • Constante
  • URL
  • Document
Pour en savoir plus sur ces types de données, reportez-vous à la section Types de sources de champs suivante.
DocFieldPattern Indique la nature du champ cible à récupérer. Non Définissez cette valeur en fonction de la valeur DocFieldSource. Consultez les exemples ci-dessous pour savoir comment définir DocFieldPatterns.
LongueurMaximale Longueur maximale de la chaîne qui peut être stockée dans le champ cible. Non. Peut être utilisé lorsque l’attribut TargetFieldType est de type String Int
UtiliserRegexCapture Stocke le modèle regex qui peut être appliqué à l’URL. Non. Peut être utilisé lorsque l’attribut TargetFieldType est de type String et que l’attribut DocFieldSource est de type Url. URL ou chaîne.

Types de source de champ

Les données des moteurs de recherche externes peuvent être définies sur l’un des types de source de champ suivants :

  • Regex : Permet d’indiquer un type d’expression régulière de données.
  • Méta : Indique que la valeur du champ cible est obtenue à partir d’une <balise méta> dans l’article source.
  • Constante : permet de définir une valeur statique pour le champ cible.
  • Url : Permet d’indiquer l’URL du document source externe.
  • Document : Permet d’indiquer le contenu HTML de l’article.

Considérations relatives à la création de votre propre modèle de mappage de métadonnées

Lorsque vous développez votre propre schéma de mappage, vous devez vous assurer de configurer quelques champs obligatoires et de définir des valeurs par défaut pour certaines définitions de champ.

Votre modèle de mappage doit inclure :

  • Les champs UniqueTargetFieldName, ContentTargetFieldName et ApiPathLeafName . Ces champs doivent être définis sur leurs valeurs obligatoires comme suit :

    • Définissez UniqueTargetFieldName sur le champ msdyn_externalreferenceid prêt à l’emploi ou sur un champ personnalisé. Si vous utilisez un champ personnalisé, assurez-vous d’ajouter le champ en tant que clé secondaire. Plus d’informations : Define des clés alternatives pour référencer des enregistrements Dynamics 365.
    • Incluez le champ ContentTargetFieldName et définissez sa valeur sur « content ».
    • Incluez le champ ApiPathLeafName et définissez sa valeur sur « knowledgearticles ».
    • Assurez-vous de fournir des mappages pour les champs UniqueTargetField et ContentTargetField dans la liste FieldDefinitions .

    Votre schéma de mappage se présente comme suit :

    
  {
    "Name": "{To be filled by you}",
    "UniqueTargetFieldName": "msdyn_externalreferenceid",
    "ContentTargetFieldName": "content",
    "ApiPathLeafName": "knowledgearticles"
    "FieldDefinitions": []
  }

  • Vous devez inclure la liste FieldDefinitions ci-dessous et renseigner ses attributs tels que FieldUse, DocFieldSource, TargetFieldName et TargetFieldType avec les valeurs par défaut. Veillez à inclure les champs et attributs suivants avec leurs valeurs, «as-is», dans votre modèle. Toutefois, vous pouvez définir les champs Docfieldsource et Docfieldpattern pour les champs de valeur de titre et de contenu sur Regex, Meta, Document, Constant ou Url.

    
  {
    "FieldUse": "Create",
    "DocFieldSource": "ArticlePublicNumber",
    "TargetFieldName": "articlepublicnumber",
    "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "Constant",
     "DocFieldPattern": "true",
     "TargetFieldName": "msdyn_isingestedarticle",
     "TargetFieldType": "Boolean"
  },
  {
     "DocFieldSource": "Url",
     "TargetFieldName": "msdyn_ingestedarticleurl",
     "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "DataProvider",
     "TargetFieldName": "msdyn_integratedsearchproviderid@odata.bind",
     "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "Regex",
     "DocFieldPattern": "<title>(.*?)</title>",
     "TargetFieldName": "title",
     "TargetFieldType": "String"
  },
  {
     "DocFieldSource": "Url",
     "TargetFieldName": "msdyn_externalreferenceid",
     "TargetFieldType": "String",
     "UseRegexCapture": "^https://.*?/(.*?)/.*/.*?([0-9A-F]{8}[-](?:[0-9A-F]{4}[-]){3}[0-9A-F]{12})$"
 }, 
  {
     "DocFieldSource": "Document",
     "TargetFieldName": "content",
     "TargetFieldType": "String"
  }

  • Une fois que vous avez répertorié les champs obligatoires et les informations d’attribut, vous pouvez inclure des mappages de métadonnées supplémentaires et définir vos propres valeurs personnalisées pour ceux-ci. Par exemple, vous pouvez inclure un type Meta de DocFieldSource et définir des valeurs personnalisées pour l’attribut, comme suit.

    
   {
     "DocFieldSource": "Meta",
     "DocFieldPattern": "description",
     "TargetFieldName": "description",
     "TargetFieldType": "String",
     "MaxLength": 155
    }

Exemple de modèle de mappage de métadonnées

Vous pouvez utiliser l’exemple JSON de mappage de métadonnées suivant comme modèle pour créer votre propre modèle de mappage personnalisé.


   {
     "Name": "Integrated Search Data Provider Name",
     "UniqueTargetFieldName": "msdyn_externalreferenceid",
     "ContentTargetFieldName": "content",
     "ApiPathLeafName": "knowledgearticles",
     "FieldDefinitions": [
     {
       "FieldUse": "Create",
       "DocFieldSource": "ArticlePublicNumber",
       "TargetFieldName": "articlepublicnumber",
       "TargetFieldType": "String"
      },
      {
        "DocFieldSource": "Constant",
        "DocFieldPattern": "true",
        "TargetFieldName": "msdyn_isingestedarticle",
        "TargetFieldType": "Boolean"
      },
      {
        "DocFieldSource": "Url",
        "TargetFieldName": "msdyn_ingestedarticleurl",
        "TargetFieldType": "String"  
      },
      {
        "DocFieldSource": "DataProvider",
        "TargetFieldName": "msdyn_integratedsearchproviderid@odata.bind",
        "TargetFieldType": "String"
      },
      {
        "DocFieldSource": "Regex",
        "DocFieldPattern": "<title>(.*?)</title>",
        "TargetFieldName": "title",
        "TargetFieldType": "String"
       },
       {
          "DocFieldSource": "Meta",
          "DocFieldPattern": "description",
          "TargetFieldName": "description",
          "TargetFieldType": "String",
          "MaxLength": 155
       },
       {
          "DocFieldSource": "Document",
          "TargetFieldName": "content",
          "TargetFieldType": "String"
        },
        {
          "DocFieldSource": "Url",
          "TargetFieldName": "msdyn_externalreferenceid",
          "TargetFieldType": "String",
          "UseRegexCapture": "^https://.*?/(.*?)/.*/.*?([0-9A-F]{8}[-](?:[0-9A-F]{4}[-]){3}[0-9A-F]{12})$"
        }
    ]
 }

Transformez et mappez des données sources externes à des champs de connaissances

Lorsque vous mappez des informations provenant de fournisseurs de données externes aux entités d’articles de connaissances, si la valeur source est d’un type de données différent, vous devez transformer la valeur avant de pouvoir la mapper à l’attribut de connaissances cible. Vous pouvez créer un plug-in et l’inscrire sur Create et Update les messages afin que les attributs de l’article de connaissances cible aient des valeurs qui sont inline avec les articles des fournisseurs externes.

Pour transformer et mapper les valeurs sources, procédez comme suit :

  1. Créez un champ personnalisé dans l’entité KnowledgeArticle . Apprenez-en davantage sur la création et la modification de colonnes.
  2. Mappez la valeur source externe requise au champ personnalisé nouvellement créé. Pour en savoir plus, consultez Configurer le mappage de schéma de l’article de connaissance (version préliminaire). Il s’agit d’un mappage temporaire à partir duquel votre plug-in récupère la valeur source.
  3. Créez un plug-in. Pour en savoir plus, consultez Créer un projet de plug-in.
  4. Vous pouvez écrire votre propre code pour convertir la valeur source externe et la mapper à l’attribut d’article de connaissances cible requis.
    Dans cet exemple, nous montrons comment mapper une valeur source de type String à un attribut de champ d’article de type OptionSet. Dans le plug-in que vous avez créé, remplacez la classe entière par l’exemple de code suivant.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.Remoting.Contexts;
using System.Runtime.Remoting.Services;
using System.ServiceModel;
using Microsoft.Xrm.Sdk;
using Microsoft.Xrm.Sdk.Messages;
using Microsoft.Xrm.Sdk.Metadata;

namespace PowerApps.Samples
{
   /// <summary>
   /// The plug-in shows the sample code to map the external source value to the target attribute, when they're of different types
   /// </summary>
   /// <remarks>
   /// To showcase the capabilities of the plugin, we have added 2 new attributes to the KnowledgeArticle entity.
   /// The first attribute new_documentationcentersourcevalue is a String attribute that is mapped to the external source value. This is a temporary mapping that stores the source value.
   /// The plugin picks up the source value from new_documentationcentersourcevalue. The source value can take the following values: Develop, Content, and Test.
   ///The second attribute, new_documentationcenter, is the target attribute of type OptionSet to which the source value must actually be mapped to.
   /// Develop with value 100000000, Content with value 100000001, and Test with value 100000002
   /// The goal of this plugin to read the value from the new_documentationcentersourcevalue, retrieve the option set metadata of the target attribute new_documentationcenter, and map it to the value in new_documentationcentersourcevalue.
   /// </remarks>
   public sealed class KnowledgePlugin : IPlugin
   {
       /// <summary>
       /// Execute method that is required by the IPlugin interface.
       /// </summary>
       /// <param name="serviceProvider">The service provider from which you can obtain the
       /// tracing service, plug-in execution context, organization service, and more.</param>
       public void Execute(IServiceProvider serviceProvider)
       {
           //Extract the tracing service for use in debugging sandboxed plug-ins.
           ITracingService tracingService =
               (ITracingService)serviceProvider.GetService(typeof(ITracingService));

           // Obtain the execution context from the service provider.
           IPluginExecutionContext context = (IPluginExecutionContext)
               serviceProvider.GetService(typeof(IPluginExecutionContext));

           // The InputParameters collection contains all the data passed in the message request.
           if (context.InputParameters.Contains("Target") &&
               context.InputParameters["Target"] is Entity)
           {
               // Obtain the target entity from the input parameters.
               Entity entity = (Entity)context.InputParameters["Target"];

               // Verify that the target entity represents knowledgearticle.
               if (entity.LogicalName != "knowledgearticle")
               {
                   tracingService.Trace("KnowledgePlugin: Plugin is incorrectly called for the entity: " + entity.LogicalName);
                   return;
               }

               //Skip the plugin for RootArticles
               const string isRootArticleAttributeName = "isrootarticle";
               bool isRootArticle = entity.GetAttributeValue<bool>(isRootArticleAttributeName);
               if (isRootArticle)
               {
                   tracingService.Trace("KnowledgePlugin: Returning for Root Article");
                   return;
               }

               try
               {
                   const string sourceValueAttributeName = "new_documentationcentersourcevalue";
                   const string targetValueAttributeName = "new_documentationcenter";

                   //Get the source value
                   string sourceValue = entity.GetAttributeValue<string>(sourceValueAttributeName);
                   if (string.IsNullOrEmpty(sourceValue))
                   {
                       tracingService.Trace("KnowledgePlugin: " + sourceValueAttributeName + " is not set");
                       return;
                   }

                   // Obtain the organization service reference.
                   IOrganizationServiceFactory serviceFactory = (IOrganizationServiceFactory)serviceProvider.GetService(typeof(IOrganizationServiceFactory));
                   IOrganizationService service = serviceFactory.CreateOrganizationService(context.UserId);

                   // Retrieve the option set metadata of the target field.
                   OptionSetMetadata retrievedOptionSetMetadata = RetrieveOptionSet(service, entity, targetValueAttributeName, tracingService);

                   // Check if the source data value is present in the retrieved target option set metadata.
                   OptionMetadata matchedOptionMetadata = retrievedOptionSetMetadata?.Options?.First(optionMetadata => optionMetadata.Label.UserLocalizedLabel.Label == sourceValue);
                   if (matchedOptionMetadata == null || matchedOptionMetadata.Value == null)
                   {
                       tracingService.Trace("KnowledgePlugin: Matching OptionMetadata is not found");
                       return;
                   }

                   // Map the option set value of the string new_documentationcentersourcevalue to the target option set new_documentationcenter.
                   int optionSetValue = (int)matchedOptionMetadata.Value;
                   entity[targetValueAttributeName] = new OptionSetValue(optionSetValue);
                   tracingService.Trace("KnowledgePlugin: Successfully set the value.");
               }
               catch (FaultException<OrganizationServiceFault> ex)
               {
                   throw new InvalidPluginExecutionException("An error occurred in the KnowledgePlugin plug-in." + ex + "\n InnerException: " + ex.InnerException);
               }

               catch (Exception ex)
               {
                   tracingService.Trace("Exception in KnowledgePlugin: {0}", ex);
                   throw ex;
               }
           }
       }

       /// <summary> 
       /// Fetch the optionset metadata from the entity metadata
       /// </summary>
       /// <param name="service">Organization Details</param>
       /// <param name="entity">Entity record</param>
       /// <param name="targetValueAttributeName">Optionset Attribute Name</param>
       /// <param name="tracingService">Tracing Service</param>
       private OptionSetMetadata RetrieveOptionSet(IOrganizationService service, Entity entity, string targetValueAttributeName, ITracingService tracingService)
       {
           RetrieveEntityRequest retrieveEntityRequest = new RetrieveEntityRequest
           {
               LogicalName = entity.LogicalName,
               EntityFilters = EntityFilters.Attributes,
               RetrieveAsIfPublished = true
           };
           RetrieveEntityResponse retrieveEntityResponse = (RetrieveEntityResponse)service.Execute(retrieveEntityRequest);
           EntityMetadata metadata = retrieveEntityResponse.EntityMetadata;
           PicklistAttributeMetadata picklistMetadata = metadata.Attributes.FirstOrDefault(attribute => string.Equals(attribute.LogicalName, targetValueAttributeName, StringComparison.OrdinalIgnoreCase)) as PicklistAttributeMetadata;
           return picklistMetadata.OptionSet;
       }
   }
}
  1. Enregistrez le plug-in sur Create et les messages du kit de développement logiciel (SDK) Update de l’entité KnowledgeArticle à l’étape PreOperation. Plus d’informations : Inscrire un plug-in

Gérer les fournisseurs de recherche intégrés
Afficher et utiliser les statistiques des fournisseurs de recherche

  • Last updated on