Erstellen und Verwalten benutzerdefinierter Unternehmens-Apps in Customer Engagement mit Code

  • Artikel

Unternehmens-Apps in Dynamics 365 Customer Engagement sind modulare, speziell gebaute Apps, die rollenbasierte Funktionen bieten, die für einen bestimmten Arbeitsbereich relevant sind. Diese Apps erleichtern es Benutzern, ihre alltäglichen Aufgaben schnell zu finden durch eine einfache und intuitiv bedienbare Benutzeroberfläche. Beispielsweise enthält die Vertrieb-Unternehmens-App eine einfachere kleinere Siteübersicht nur mit dem entsprechenden Satz der Formulare, Ansichten, Prozessflüsse und Dashboards, die für Vertriebsmitarbeiter relevant sind.

Systemadministratoren und -anpasser können Zugriff auf diese Unternehmens-Apps mit Sicherheitsrollen gewähren; Benutzer können nur auf jene Apps zugreifen, für die sie über die Berechtigung verfügen.

Notiz

Benutzerdefinierte Unternehmens-Apps in Dynamics 365 Customer Engagement sind identisch mit modellgesteuerten Apps in Power Apps. Beide basieren auf derselben Plattform. Weitere Informationen: Was sind modellgesteuerte Apps?

Zusätzlich zum Erstellen benutzerdefinierter Unternehmens-Apps mithilfe des Anwendungs-Designers können Sie benutzerdefinierte Unternehmens-Apps in Dynamics 365 Customer Engagement (on-premises) jetzt programmgesteuert erstellen und verwalten.

Wichtig

Sie müssen jedoch keinen Code schreiben, um benutzerdefinierte Unternehmens-Apps zu erstellen, wenn Sie dies nicht benötigen! Der App-Designer bietet eine viel einfachere und intuitive Erfahrung zum Erstellen benutzerdefinierter Unternehmens-Apps, ohne dass man Code schreiben muss, indem eine Kachel-basierte Informationsstruktur und eine vereinfachte Schnittstelle bereitgestellt wird. Finden Sie es hier: Gestalten Sie benutzerdefinierte Unternehmens-Apps mit dem App-Designer

Das Erstellen einer benutzerdefinierten Unternehmens-App umfasst die folgenden Schritte:

  1. Erstellen einer AppModule-Entität-Instanz, um die App und ihre Eigenschaften zu definieren.
  2. Hinzufügen oder Entfernen von Komponenten zur App, wie Entität, Siteübersicht und andere Komponenten für die benutzerdefinierte App mit AddAppComponents und RemoveAppComponents-Aktionen.
  3. Überprüfen Sie die App auf alle fehlenden erforderlichen Komponenten mithilfe der Funktion ValidateApp.
  4. Veröffentlichen der App.
  5. Ordnen Sie die entsprechenden Sicherheitsrollen der benutzerdefinierten Unternehmens-App zu, um Zugriff für Benutzer bereitzustellen.

Erstellen Sie die Unternehmens-App und definieren Sie deren Eigenschaften

Sie müssen über die Sicherheitsrolle „Systemadministrator“ oder „Systemanpasser“ bzw. entsprechende Berechtigungen verfügen, um eine App zu erstellen.

Sie müssen mindestens die folgenden Eigenschaften angeben, um eine App zu erstellen:

  • Name: Eindeutig für die App
  • uniquename: Dies kann anders als Name der App sein und darf nur englische Zeichen und nur Zahlen enthalten. Bei Erstellung dieser App wird automatisch der Name mit dem Lösungsherausgeberpräfix verwendet (beispielsweise 'new_').
  • webresourceid: ID der Webressource, die als Bildsymbol für die App festgelegt werden soll. Das System bietet eine Standardwebressource (ID: 953b9fac-1e5e-e611-80d6-00155ded156f), die Sie als Symbol für die App verwenden können.

Die folgende Internet-API-Anforderung erstellt einen einheitlichen Oberflächen-Typ einer App:

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"    
}

Der OData-EntityId-Antwortheader enthält die URI der erstellten App.

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

Hinzufügen oder Entfernen von Komponenten der Unternehmens-App

Sie können Komponenten in einer App hinzufügen oder entfernen, wie Siteübersicht, Entität, Dashboard, Geschäftsprozessflüsse, Ansichten und Formulare, die in die Unternehmens-App eingeschlossen werden sollen. Ausführliche Informationen zu Komponenten, die einer Unternehmens-App hinzugefügt werden können, finden Sie unter Hinzufügen oder Bearbeiten von App-Komponenten im App-Designer Sie unter.

Verwenden Sie die AddAppComponents-Aktion oder die AddAppComponentsRequest-Meldung, um Komponenten der Unternehmens-App hinzuzufügen. Für die Aktion müssen Sie Folgendes angeben:

  • AppId: ID der App, der Sie Komponenten hinzufügen möchten
  • Komponenten Eine Sammlung von Komponenten, die hinzugefügt werden sollen. Sie müssen die ID sowie den Entitätstyp der Komponente angeben, die Sie hinzufügen möchten. Eine Liste der Entitäten in der Customer Engagement-Internet API finden Sie unter Web API Entity Type Reference.

Die folgende Internet-API-Anforderung fügt der App eine Ansicht (savedquery) und ein Formular (systemform) hinzu:

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"
		}
	]
}

Um eine Komponente einer App zu entfernen, können Sie die Aktion RemoveAppComponents oder die RemoveAppComponentsRequest-Nachricht verwenden. Diese Aktion verwendet denselben Satz von Parametern wie die Aktion AddAppComponents.

Die folgende Internet-API-Anforderung entfernt eine Ansicht (savedquery) von der App:

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"
		}
	]
}

Überprüfen der Unternehmens-App

Das Überprüfen einer App umfasst das Überprüfen der Abhängigkeiten für die Komponenten, die Sie in der Unternehmens-App hinzugefügt haben, um sicherzustellen, dass die App adäquat funktioniert. Dies ist das Gleiche wie Überprüfen im App-Designer. Weitere Informationen: Überprüfen der App

Verwenden Sie die ValidateApp-Funktionen oder die ValidateAppRequest-Meldung, um die App zu überprüfen. Die folgende Web-API-Anforderung zeigt, wie die modellgesteuerte Geschäfts-App mit der ID: dd621d4a-d898-e711-80e7-00155db763be überprüft wird:

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

Wenn es keine Überprüfungsfehler gibt, ist die Antwort wie folgt:

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": []
    }
}

Falls es Überprüfungsprobleme in der App gibt, werden in der Antwort Fehler/Warnungen in der ValidationIssueList angezeigt:

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": []
            }
        ]
    }
}

Veröffentlichen der Unternehmens-App

Nachdem Sie erforderlichen Komponenten zu Ihrer benutzerdefinierten Unternehmens-App hinzugefügt bzw. sie überprüft haben, müssen Sie diese veröffentlichen, um sie Benutzern zur Verfügung zu stellen.

Mithilfe der PublishXml-Aktion, oder der PublishXmlRequest-Mitteilung veröffentlichen Sie die benutzerdefinierte Unternehmens-App. Die folgende Anforderung zeigt, wie die modellgesteuerte Geschäfts-App mit der ID: dd621d4a-d898-e711-80e7-00155db763be veröffentlicht wird:

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>"
}

Verwalten von Sicherheitsrollen mit Sicherheitsrollen

Um Benutzern Zugriff auf Ihre Apps bereitzustellen, damit diese darauf aus ihrem Bereich Einstellungen>Meine Apps oder der Dynamics 365 Customer Engagement (on-premises) Startseite zugreifen können, können Sie den Unternehmens-Apps Sicherheitsrollen hinzufügen. Benutzer, die den zugeordneten Sicherheitsrollen zugewiesen sind, können Ihre Unternehmens-Apps in Customer Engagement anzeigen und verwenden.

Verwenden Sie die appmoduleroles_association-Navigationseigenschaft der AppModule-Entität-Entität, um eine Unternehmens-App zu einer Sicherheitsrolle zuzuordnen. Die folgende Anforderung veranschaulicht, wie Sie eine Unternehmens-App einer Sicherheitsrolle zuordnen:

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>)"
}

Um eine Sicherheitsrolle aus einer Unternehmens-App die Zuordnung zu entfernen, verwenden Sie die DELETE-Anforderung mit derselben Navigationseigenschaft. Beispiel:

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)

Verwalten Ihrer Unternehmens-Apps und deren Komponenten

Dieser Abschnitt bietet Informationen zum Abrufen der Apps, Aktualisieren von App-Eigenschaften, das Abrufen von Apps-Komponenten und zum Löschvorgang von Apps.

Veröffentlichte Apps abrufen

Um veröffentlichte Apps abzurufen, können Sie die folgenden Anforderungen verwenden:

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

Unveröffentlichte Apps abrufen

Zum Abrufen unveröffentlichter Apps verwenden Sie die RetrieveUnpublishedMultiple-Funktion. Beispiel:

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

Abrufen von Komponenten in einer veröffentlichten Unternehmens-App

Um App-Komponenten für eine Unternehmens-App abzurufen, verwenden Sie die RetrieveAppComponents-Funktion oder die RetrieveAppComponentsRequest-Nachricht. Beispiel:

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

Rufen Sie Sicherheitsrollen ab, die einer veröffentlichten Unternehmens-App zugeordnet sind

Um die Sicherheitsrollen abzurufen, die der Unternehmens-App zugeordnet sind, können die $expand Systemabfrageoption mit der appmoduleroles_association-Navigationseigenschaft verwenden. Beispielsweise ist hier die Anforderung, alle Sicherheitsrollen anzuzeigen, die der modellgesteuerten Geschäfts-App mit der ID: dd621d4a-d898-e711-80e7-00155db763be zugeordnet sind:

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

Unternehmens-Apps löschen

Verwenden Sie die DELETE-Anforderung, um eine Unternehmens-App zu löschen. Beispiel:

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

Client-API-Unterstützung für Unternehmens-Apps

Sie können die folgenden Client-APIs verwenden, um mit Unternehmens-Apps zu arbeiten:

Siehe auch

Gestalten Sie benutzerdefinierte Unternehmens-Apps mit dem App Designer