Créer et gérer des applications d’entreprise personnalisées dans Customer Engagement à l’aide de code

Article
03/22/2023

Les applications d’entreprise Dynamics 365 Customer Engagement sont des applications modulaires conçues pour un but spécifique qui fournissent des fonctionnalités basées sur un rôle appropriées à un domaine de travail particulier. Ces applications permettent aux utilisateurs de trouver facilement et rapidement les tâches quotidiennes à effectuer grâce à une interface simple et intuitive. Par exemple, l’application d’entreprise Sales fournit un plan de site plus simple et petit avec uniquement l’ensemble approprié de formulaires, vues, tableaux de bord et flux de processus qui sont utiles pour les commerciaux.

Les administrateurs et personnalisateurs de système peuvent fournir aux utilisateurs un accès à ces applications d’entreprise à l’aide de rôles de sécurité ; les utilisateurs ne peuvent accéder qu’aux applications qui leur sont autorisées.

Note

Les applications personnalisées métiers dans Dynamics 365 Customer Engagement sont identiques aux applications basées sur des modèles dans Power Apps ; les deux sont générées sur la même plateforme sous-jacente. Pour plus d’informations, consultez Que sont les applications pilotées par modèle ?

Outre la création d’applications métier personnalisées à l’aide du concepteur d’application, vous pouvez créer et gérer par programme des applications métier personnalisées dans Dynamics 365 Customer Engagement (on-premises).

Important

Il n’est pas nécessaire d’écrire du code pour créer des applications d’entreprise personnalisées si vous n’en avez pas besoin ! Le concepteur d’application offre une expérience plus simple et intuitive pour créer des applications d’entreprise personnalisées sans écrire de code grâce à une structure d’informations basée sur une vignette et une interface simplifiée. Pour en savoir plus, voir Créer des applications d’entreprise personnalisées à l’aide du concepteur d’application

La création d’une application d’entreprise personnalisée implique les étapes suivantes :

Créer une instance de l’entité AppModule pour définir votre application et ses propriétés.
Ajouter ou supprimer des composants de votre application, comme une entité, un plan de site et d’autres composants pour votre application personnalisée à l’aide des actions AddAppComponents et RemoveAppComponents.
Rechercher dans votre application les composants requis manquants à l’aide de la fonction ValidateApp.
Publier votre application.
Associer les rôles de sécurité appropriés à votre application d’entreprise personnalisée pour fournir un accès aux utilisateurs.

Créer votre application d’entreprise et définir ses propriétés

Vous devez disposer du rôle de sécurité Administrateur système ou Personnalisateur de système ou d’autorisations équivalentes pour pouvoir créer une application.

Vous devez spécifier les propriétés suivantes au minimum pour créer une application :

name : unique pour votre application
uniquename : peut être différent du nom de votre application, et ne peut contenir que des nombres et des caractères anglais. Lors de la création de cette application, le préfixe de l’éditeur de solutions est automatiquement ajouté au nom (par exemple « new_ »).
webresourceid : ID de la ressource web que vous souhaitez définir comme icône d’image pour votre application. Le système fournit une ressource web par défaut (ID : 953b9fac-1e5e-e611-80d6-00155ded156f) que vous pouvez utiliser comme icône pour votre application.

La requête suivante de l’API web crée un type Unified Interface pour une application :

POST [Organization URI]/api/data/v9.1/appmodules HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
    "name": "SDKTestApp",
    "uniquename":"SDKTestApp",
    "webresourceid":"953b9fac-1e5e-e611-80d6-00155ded156f"    
}

L’en-tête OData-EntityId de la réponse contient l’URI de l’application créée.

HTTP/1.1 204 No Content
OData-Version: 4.0
OData-EntityId: [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)

Ajouter ou supprimer des composants de votre application d’entreprise

Vous pouvez ajouter des composants dans une application comme un plan de site, une entité, un tableau de bord, des flux de processus d’entreprise, des vues et des formulaires que vous souhaitez inclure dans votre application d’entreprise, ou les supprimer. Pour plus d’informations sur les composants pouvant être ajoutés à une application d’entreprise, voir Ajouter ou modifier des composants d’application dans le concepteur d’application.

Utilisez l’action AddAppComponents ou le message AddAppComponentsRequest pour ajouter des composants à votre application d’entreprise. L’action requiert que vous spécifiez les éléments suivants :

AppId : ID de l’application où vous souhaitez ajouter des composants
Composants : collection de composants à ajouter. Vous devez spécifier l’ID et le type d’entité du composant à ajouter. Pour obtenir la liste des types d’entités dans l’API web Customer Engagement, voir Web API Entity Type Reference.

La demande suivante de l’API web ajoute une vue (savedquery) et un formulaire (systemform) à votre application :

POST [Organization URI]/api/data/v9.1/AddAppComponents HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
	"AppId":"dd621d4a-d898-e711-80e7-00155db763be",
	"Components":[
		{
			"savedqueryid":"00000000-0000-0000-00aa-000000666000",
			"@odata.type":"Microsoft.Dynamics.CRM.savedquery"
		},
		{
			"formid":"c9e7ec2d-efca-4e4c-b3e3-f63c4bba5e4b",
			"@odata.type":"Microsoft.Dynamics.CRM.systemform"
		}
	]
}

Pour supprimer un composant d’une application, utilisez l’action RemoveAppComponents ou le message RemoveAppComponentsRequest. Cette action utilise le même ensemble de paramètres que l’action AddAppComponents.

La demande suivante de l’API web supprime une vue (savedquery) de votre application :

POST [Organization URI]/api/data/v9.1/RemoveAppComponents HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{
	"AppId":"dd621d4a-d898-e711-80e7-00155db763be",
	"Components":[
		{
			"savedqueryid":"00000000-0000-0000-00aa-000000666000",
			"@odata.type":"Microsoft.Dynamics.CRM.savedquery"
		}
	]
}

Valider votre application d’entreprise

La validation d’une application consiste à rechercher des dépendances pour les composants que vous avez ajoutés dans votre application d’entreprise pour vérifier son bon fonctionnement. Cela revient au même que de cliquer sur Valider dans le concepteur d’application. Pour plus d’informations, voir Valider votre application

Utilisez la fonction ValidateApp ou le message ValidateAppRequest pour valider votre application. La demande suivante de l’API web montre comment valider votre application d’entreprise portant l’ID : dd621d4a-d898-e711-80e7-00155db763be :

GET [Organization URI]/api/data/v9.1/ValidateApp(AppModuleId=dd621d4a-d898-e711-80e7-00155db763be)

Si aucune erreur de validation ne se produit, la réponse se présente comme suit :

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ValidateAppResponse",
    "AppValidationResponse": {
        "ValidationSuccess": true,
        "ValidationIssueList": []
    }
}

Si des problèmes de validation se produisent dans votre application, la réponse affiche des erreurs/avertissements dans la collection ValidationIssueList :

HTTP/1.1 200 OK
OData-Version: 4.0

{
    "@odata.context": "[Organization URI]/api/data/v9.1/$metadata#Microsoft.Dynamics.CRM.ValidateAppResponse",
    "AppValidationResponse": {
        "ValidationSuccess": false,
        "ValidationIssueList": [
            {
                "ErrorType": "Error",
                "Message": "App does not contain Site Map",
                "DisplayName": null,
                "ComponentId": "00000000-0000-0000-0000-000000000000",
                "ComponentType": 0,
                "ComponentSubType": 0,
                "ParentEntityId": "00000000-0000-0000-0000-000000000000",
                "ParentEntityName": null,
                "CRMErrorCode": -2147155684,
                "RequiredComponents": []
            },
            {
                "ErrorType": "Warning",
                "Message": "Account doesn’t reference a form or view. App users will see all forms and views.",
                "DisplayName": null,
                "ComponentId": "00000000-0000-0000-0000-000000000000",
                "ComponentType": 0,
                "ComponentSubType": 0,
                "ParentEntityId": "00000000-0000-0000-0000-000000000000",
                "ParentEntityName": null,
                "CRMErrorCode": -2147155691,
                "RequiredComponents": []
            }
        ]
    }
}

Publier votre application d’entreprise

Après avoir ajouté les composants nécessaires à votre application d’entreprise personnalisée et l’avoir validé, vous devez la publier pour qu’elle soit accessible aux utilisateurs.

Utilisez l’action PublishXml ou le message PublishXmlRequest pour publier votre application d’entreprise personnalisée. La demande suivante montre comment publier votre application d’entreprise basée sur un modèle portant l’ID : dd621d4a-d898-e711-80e7-00155db763be :

POST [Organization URI]/api/data/v9.1/PublishXml HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{  
  "ParameterXml":"<importexportxml><appmodules><appmodule>dd621d4a-d898-e711-80e7-00155db763be</appmodule></appmodules></importexportxml>"
}

Gérer l’accès aux applications d’entreprise à l’aide des rôles de sécurité

Pour fournir aux utilisateurs un accès à vos applications afin qu’ils puissent y accéder à partir de la zone Paramètres>Mes applications ou de la page d’accueil de Dynamics 365 Customer Engagement (on-premises), vous pouvez associer des rôles de sécurité à vos applications d’entreprise. Les utilisateurs affectés aux rôles de sécurité associés peuvent visualiser et utiliser vos applications d’entreprise dans Customer Engagement.

Utilisez la propriété de navigation appmoduleroles_association de l’entité AppModule pour associer une application d’entreprise à un rôle de sécurité. La demande suivante montre comment associer une application d’entreprise à un rôle de sécurité :

POST [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)appmoduleroles_association/$ref HTTP/1.1
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

{  
  "@odata.id":"[Organization URI]/api/data/v9.1/roles(<roleId>)"
}

Pour dissocier un rôle de sécurité d’une application d’entreprise, utilisez la demande DELETE avec la même propriété de navigation. Par exemple :

DELETE [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)/appmoduleroles_association/$ref?$id=[Organization URI]/api/data/v9.1/roles(<roleId)

Gérer vos applications d’entreprise et leurs composants

Cette section donne des informations sur la récupération de vos applications, la mise à jour des propriétés d’application, la récupération des composants d’application et la suppression des applications.

Récupérer des applications publiées

Pour récupérer des applications publiées, utilisez la demande suivante :

GET [Organization URI]/api/data/v9.1/appmodules?$select=name

Récupérer des applications non publiées

Pour récupérer des applications non publiées, utilisez la fonction RetrieveUnpublishedMultiple. Par exemple :

GET [Organization URI]/api/data/v9.1/appmodules/Microsoft.Dynamics.CRM.RetrieveUnpublishedMultiple()?$select=name

Récupérer les composants d’une application d’entreprise publiée

Pour récupérer les composants d’une application d’entreprise, utilisez la fonction RetrieveAppComponents ou le message RetrieveAppComponentsRequest. Par exemple :

GET [Organization URI]/api/data/v9.1/RetrieveAppComponents(AppModuleId=dd621d4a-d898-e711-80e7-00155db763be)

Récupérer les rôles de sécurité associés à une application d’entreprise publiée

Pour récupérer les rôles de sécurité associés à votre application d’entreprise, utilisez l’option de requête système $expand avec la propriété de navigation appmoduleroles_association. Par exemple, voici la demande de récupération de tous les rôles de sécurité associés à une application d’entreprise basée sur un modèle portant l’ID : dd621d4a-d898-e711-80e7-00155db763be :

GET [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)?$expand=appmoduleroles_association&$select=name,appmoduleroles_association

Supprimer des applications d’entreprise

Utilisez la demande DELETE pour supprimer une application d’entreprise. Par exemple :

DELETE [Organization URI]/api/data/v9.1/appmodules(dd621d4a-d898-e711-80e7-00155db763be)

Prise en charge de l’API client pour les applications d’entreprise

Vous pouvez utiliser les API client suivantes avec les applications d’entreprise :

Voir aussi

Créer des applications d’entreprise personnalisées à l’aide du concepteur d’application