Extensions

Extensions werden derzeit über statische YAML-Dokumente definiert. Die benötigten und erlaubten Attribute sind in folgendem Schema beschrieben. Für weitere Informationen zu den einzelnen Attributen siehe Aus welchen Informationen besteht eine Extension?

Schema-Dokumentation

• idstring (uuid)

  required

  Global einheitlicher Identifier der Extension

• contributorIdstring (uuid)

  required

  Identifier des Contributors. Entspricht dem identifier des Customers/der Organisation im mStudio

• namestring

  required

  Name der Extension

• descriptionstring

  required

  Kurzbeschreibung der Extension. Sollte möglichst kurz, prägnant und in weniger als 300 Zeichen die Extension erklären

• detailedDescriptionsobject

  Ausführliche Beschreibungen der Extension in unterschiedlichen Sprachen

  • deobject

    required

    Ausführliche Beschreibung der Extension in Deutsch

    • markdownstring (≥ 1 characters)

      required

      Ein Beschreibungstext mit Markdown-Formatierungen

    • plainstring (≥ 1 characters)

      Ein Beschreibungstext ohne Formatierungen

  • enobject

    Ausführliche Beschreibung der Extension in Englisch

    • markdownstring (≥ 1 characters)

      required

      Ein Beschreibungstext mit Markdown-Formatierungen

    • plainstring (≥ 1 characters)

      Ein Beschreibungstext ohne Formatierungen

• extensionContextstring (one of: project, customer)

  required

  Gibt an, ob die Extension zu einem Projekt oder zu einer Organisation hinzugefügt werden kann

• requiredScopesarray of string

  required

  Berechtigungen, die die Extension benötigt

  • Array[
  • *string
  ]

externalComponentsobject

required

• backendobject

  required
  • extensionAddedToContextobject

    required
    • urlstring (uri)

      required

      URL, die aufgerufen wird, wenn die Extension zu einem Extension Context hinzugefügt wird. Kann Platzhalter enthalten

  • extensionInstanceUpdatedobject

    required
    • urlstring (uri)

      required

      URL, die aufgerufen wird, wenn eine Extension Instance aktualisiert wird. Kann Platzhalter enthalten

  • extensionInstanceSecretRotatedobject

    required
    • urlstring (uri)

      required

      URL, die aufgerufen wird, wenn das Secret einer Extension Instance rotiert wird. Kann Platzhalter enthalten

  • extensionInstanceRemovedFromContextobject

    required
    • urlstring (uri)

      required

      URL, die aufgerufen wird, wenn die Extension aus einem Extension Context entfernt wird. Kann Platzhalter enthalten

• frontendsobject
  • indexobject
    • urlstring (uri)

      required

      URL, die aufgerufen wird, wenn die Extension im mStudio aufgerufen wird. Kann Platzhalter enthalten

supportobject

required

• emailstring (email)

  required

  E-Mail-Adresse, die für Supportanfragen genutzt werden kann

• phonestring (phone)

  Telefonnummer, die für Supportanfragen genutzt werden kann

tagsarray of string

Tags, die die Extension beschreiben

• Array[
• *string
]

stateobject

required

• hiddenboolean

  Gibt an, ob die Extension im mStudio sichtbar ist

• disabledboolean

  Gibt an, ob Extension Instances für diese Extension existieren dürfen

• blockedboolean

  Gibt an, ob die Extension zu einem Extension Context hinzugefügt werden kann

Beispiel

id: f0f86186-0a5a-45b2-aa33-502777496347
contributorId: f0f86186-0a5a-45b2-aa33-502777496347
name: Example Extension
description: Eine Beispiel Extension, die zeigen soll, welche Informationen
  benötigt werden, um eine Extension einzureichen
detailedDescriptions:
  de:
    markdown: |-
      # Ein Beispiel
      Dies ist eine Beispiel Extension-Beschreibung.
      ## Weitere Informationen
      Hier könnten **weitere** Informationen stehen.
    plain: Eine ausführliche Besipiel Extension-Beschreibung. Diese enthält keine
      Formatierungen.
  en:
    markdown: |-
      # An example
      This is an example extension description.
      ## Further informations
      Here could be **further** informations.
    plain: string
extensionContext: project
requiredScopes:
  - project:read
externalComponents:
  backend:
    extensionAddedToContext:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/added
    extensionInstanceUpdated:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/updated
    extensionInstanceSecretRotated:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/secret-rotated
    extensionInstanceRemovedFromContext:
      url: https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/removed
  frontends:
    index:
      url: https://example.org/:extensionInstanceId
support:
  email: email@mittwald.example
  phone: +49 170 123456
tags:
  - mail
state:
  hidden: true
  disabled: true
  blocked: true

JSON Schema

{
  "type": "object",
  "required": [
    "id",
    "contributorId",
    "name",
    "description",
    "support",
    "state",
    "extensionContext",
    "requiredScopes",
    "externalComponents"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Global einheitlicher Identifier der Extension"
    },
    "contributorId": {
      "type": "string",
      "format": "uuid",
      "description": "Identifier des Contributors. Entspricht dem identifier des Customers/der Organisation im mStudio"
    },
    "name": {
      "type": "string",
      "description": "Name der Extension",
      "example": "Example Extension"
    },
    "description": {
      "type": "string",
      "description": "Kurzbeschreibung der Extension. Sollte möglichst kurz, prägnant und in weniger als 300 Zeichen die Extension erklären",
      "example": "Eine Beispiel Extension, die zeigen soll, welche Informationen benötigt werden, um eine Extension einzureichen"
    },
    "detailedDescriptions": {
      "type": "object",
      "description": "Ausführliche Beschreibungen der Extension in unterschiedlichen Sprachen",
      "required": [
        "de"
      ],
      "properties": {
        "de": {
          "type": "object",
          "description": "Ausführliche Beschreibung der Extension in Deutsch",
          "required": [
            "markdown"
          ],
          "properties": {
            "markdown": {
              "type": "string",
              "description": "Ein Beschreibungstext mit Markdown-Formatierungen",
              "minLength": 1,
              "example": "# Ein Beispiel\nDies ist eine Beispiel Extension-Beschreibung.\n## Weitere Informationen\nHier könnten **weitere** Informationen stehen."
            },
            "plain": {
              "type": "string",
              "description": "Ein Beschreibungstext ohne Formatierungen",
              "minLength": 1,
              "example": "Eine ausführliche Besipiel Extension-Beschreibung. Diese enthält keine Formatierungen."
            }
          }
        },
        "en": {
          "type": "object",
          "description": "Ausführliche Beschreibung der Extension in Englisch",
          "required": [
            "markdown"
          ],
          "properties": {
            "markdown": {
              "type": "string",
              "description": "Ein Beschreibungstext mit Markdown-Formatierungen",
              "minLength": 1,
              "example": "# An example\nThis is an example extension description.\n## Further informations\nHere could be **further** informations."
            },
            "plain": {
              "type": "string",
              "description": "Ein Beschreibungstext ohne Formatierungen",
              "minLength": 1,
              "exmple": "A detailed example extension description. This does not contain any formatting."
            }
          }
        }
      }
    },
    "extensionContext": {
      "type": "string",
      "enum": [
        "project",
        "customer"
      ],
      "description": "Gibt an, ob die Extension zu einem Projekt oder zu einer Organisation hinzugefügt werden kann"
    },
    "requiredScopes": {
      "type": "array",
      "items": {
        "type": "string",
        "example": "project:read"
      },
      "description": "Berechtigungen, die die Extension benötigt"
    },
    "externalComponents": {
      "type": "object",
      "required": [
        "backend"
      ],
      "properties": {
        "backend": {
          "type": "object",
          "required": [
            "extensionAddedToContext",
            "extensionInstanceUpdated",
            "extensionInstanceSecretRotated",
            "extensionInstanceRemovedFromContext"
          ],
          "properties": {
            "extensionAddedToContext": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL, die aufgerufen wird, wenn die Extension zu einem Extension Context hinzugefügt wird. Kann Platzhalter enthalten",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/added"
                }
              }
            },
            "extensionInstanceUpdated": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL, die aufgerufen wird, wenn eine Extension Instance aktualisiert wird. Kann Platzhalter enthalten",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/updated"
                }
              }
            },
            "extensionInstanceSecretRotated": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL, die aufgerufen wird, wenn das Secret einer Extension Instance rotiert wird. Kann Platzhalter enthalten",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/secret-rotated"
                }
              }
            },
            "extensionInstanceRemovedFromContext": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL, die aufgerufen wird, wenn die Extension aus einem Extension Context entfernt wird. Kann Platzhalter enthalten",
                  "example": "https://example.org/api/v1/extensions/:contextId/:extensionInstanceId/removed"
                }
              }
            }
          }
        },
        "frontends": {
          "type": "object",
          "properties": {
            "index": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "format": "uri",
                  "description": "URL, die aufgerufen wird, wenn die Extension im mStudio aufgerufen wird. Kann Platzhalter enthalten",
                  "example": "https://example.org/:extensionInstanceId"
                }
              }
            }
          }
        }
      }
    },
    "support": {
      "type": "object",
      "required": [
        "email"
      ],
      "properties": {
        "email": {
          "type": "string",
          "format": "email",
          "description": "E-Mail-Adresse, die für Supportanfragen genutzt werden kann"
        },
        "phone": {
          "type": "string",
          "format": "phone",
          "description": "Telefonnummer, die für Supportanfragen genutzt werden kann",
          "example": "+49 170 123456"
        }
      }
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string",
        "example": "mail"
      },
      "description": "Tags, die die Extension beschreiben"
    },
    "state": {
      "type": "object",
      "properties": {
        "hidden": {
          "type": "boolean",
          "description": "Gibt an, ob die Extension im mStudio sichtbar ist"
        },
        "disabled": {
          "type": "boolean",
          "description": "Gibt an, ob Extension Instances für diese Extension existieren dürfen"
        },
        "blocked": {
          "type": "boolean",
          "description": "Gibt an, ob die Extension zu einem Extension Context hinzugefügt werden kann"
        }
      }
    }
  }
}