Merge pull request #743 from mittwald/how-to-create-an-instance

document creating an extension instance for testing purposes

Author: tdellmann

docs/contribution/40-how-to/5-local-development.mdx

@@ -10,6 +10,45 @@ This makes the local development of Extensions challenging if the Extension heav
 However, there are ways to assist the local Extension development besides mocking the mStudio API, which might be difficult without deep knowledge of the API.
 We will explore these in the rest of this page.
 
+## Creating an Extension Instance
+
+:::note
+A [Context](../30-overview/1-extensions.mdx#extension-context) must be defined in order to create an Extension Instance.
+:::
+
+When developing your Extension you can only completely test your Extension within the **mStudio**.\
+To do this, you must create an **Extension Instance**, which requires knowing the **Extension ID** of your Extension.\
+You can find the Extension ID in the "Entwicklung" tab of your Extension in the mStudio.
+
+:::note
+All Extension Instances within your contributor are free of charge.
+:::
+
+During development, your extension will **not** appear on the Marketplace.
+
+### ...via the mStudio (recommended) 
+
+1. Open the **mStudio**.
+2. Navigate to the **Marketplace**.
+3. Select any Extension.
+4. In the URL path, replace the Extension ID with the **Extension ID of your Extension**.
+
+### ...via the API
+
+You can create an Extension Instance programmatically by using the
+<OperationLink operation="extension-add-extension-to-context" /> operation.
+
+For every required scope of your Extension, add an entry to the `scopes` field in your request body using the format:\
+`"area:(read|write|delete)"`.\
+You can find the scopes in the "**Berechtigungen**" section of your Extension in the mStudio.
+
+![Extension permissions section](../../../resources/contributing/extensions/extension-berechtigungen.jpg)
+
+### after publishing your Extension
+
+After publishing your Extension the Extension Instances you created for testing purposes will be removed.
+You can always add your Extension to your Contextes free of charge.
+
 ## Authenticated Domain Actions
 
 The easiest way to effectively test the interaction of your business logic and the mStudio is to use the mStudio public API directly.

i18n/de/docusaurus-plugin-content-docs/current/contribution/40-how-to/5-local-development.mdx

@@ -11,6 +11,45 @@ Neben der Möglichkeit, die mStudio API zu mocken, was sich ohne Kenntnisse der
 existieren dennoch Mittel und Wege, um die lokale Entwicklung von Extensions zu erleichtern.
 Diese werden im Folgenden vorgestellt.
 
+## Erstellen einer Extension Instance
+
+:::note
+Es muss bereits ein [Context](../30-overview/1-extensions.mdx#extension-context) zugewiesen sein, bevor du eine Extension Instance erstellen kannst.
+:::
+
+Wenn du deine Extension entwickelst, kannst du sie nur innerhalb des **mStudio** vollständig testen.\
+Dazu musst du eine **Extension Instance** erstellen, wofür du die **Extension ID** deiner Extension kennen musst.\
+Die Extension ID kann unter dem "Entwicklung" Tab der Extension im mStudio eingesehen werden.
+
+:::note
+Alle Extension Instances innerhalb deines Contributors sind kostenlos.
+:::
+
+Während der Entwicklung wird deine Extension **nicht** im Marktplatz angezeigt.
+
+### ...über das mStudio (empfohlen)
+
+1. Öffne das **mStudio**.
+2. Navigiere zum **Marktplatz**.
+3. Wähle eine beliebige Extension aus.
+4. Ersetze in der URL-Pfad die Extension ID mit der **Extension ID deiner Extension**.
+
+### ...über die API
+
+Du kannst eine Extension Instance programmatisch mit der
+<OperationLink operation="extension-add-extension-to-context" /> Operation erstellen.
+
+Für jeden benötigten Scope musst du im `scopes`-Feld deines Request-Bodys einen Eintrag im folgenden Format hinzufügen:\
+`"bereich:(read|write|delete)"`.
+Die benötigten Scopes findest du in dem Bereich	"**Berechtigungen**" deiner Extension im mStudio.
+
+![Extension Berechtigungen Bereich](../../../../../../resources/contributing/extensions/extension-berechtigungen.jpg)
+
+### Nach der Veröffentlichung deiner Extension
+
+Nach der Veröffentlichung deiner Extension werden die Extension Instances, die du zu Testzwecken erstellt hast, **entfernt**.  
+Du kannst deine Extension jedoch jederzeit kostenlos zu deinen Contextes hinzufügen.
+
 ## Authentifizierte Domain Actions
 
 Um die Geschäftslogik im Zusammenspiel mit dem mStudio effektiv zu testen, ist es am einfachsten,