asyncapi: 3.0.0
info:
  title: Dashboard-App - Analytics Events
  version: 0.0.1
  description: |-
    This AsyncAPI document describes analytics and tracking events related to the Dashboard-App.
    These events are primarily used to analyze the usage and development of the Dashboard-App.
  contact:
    name: Team-PPD-Landing-Zone
    email: LandingZone@d-velop.de

servers:
  dap_cdp:
    host: cdp.prod.dap.d-velop.cloud
    protocol: https
    description: Server endpoint for publishing analytics events to the d.velop Analytics Platform (DAP)

channels:
  analytics:
    description: Channel used for emitting analytics events.
    messages:
      DashboardMetricsCollected:
        $ref: '#/components/messages/DashboardMetricsCollected'
      FavoritesUpdated:
        $ref: '#/components/messages/FavoritesUpdated'
      WidgetAdded:
        $ref: '#/components/messages/WidgetAdded'
      WidgetRemoved:
        $ref: '#/components/messages/WidgetRemoved'
      WidgetSettingsUpdated:
        $ref: '#/components/messages/WidgetSettingsUpdated'
      DashboardPublicAPIRequestReceived:
        $ref: '#/components/messages/DashboardPublicAPIRequestReceived'
      DashboardPublicAPIRequestSuccessful:
        $ref: '#/components/messages/DashboardPublicAPIRequestSuccessful'
      WidgetAPIV2Used:
        $ref: '#/components/messages/WidgetAPIV2Used'
      TenantDashboardCreated:
        $ref: '#/components/messages/TenantDashboardCreated'
      TenantDashboardDeleted:
        $ref: '#/components/messages/TenantDashboardDeleted'
      DisableDashboardV2Changed:
        $ref: '#/components/messages/DisableDashboardV2Changed'
      EnableHomeAppChanged:
        $ref: '#/components/messages/EnableHomeAppChanged'
      LegacyWidgetsConverted:
        $ref: '#/components/messages/LegacyWidgetsConverted'
      WidgetRegistered:
        $ref: '#/components/messages/WidgetRegistered'
      WidgetDeregistered:
        $ref: '#/components/messages/WidgetDeregistered'
      WidgetV2ReplacedOnDashboards:
        $ref: '#/components/messages/WidgetV2ReplacedOnDashboards'
      NavigatedViaAppsMenu:
        $ref: '#/components/messages/NavigatedViaAppsMenu'
      NavigatedViaWidget:
        $ref: '#/components/messages/NavigatedViaWidget'
      ResetUserDashboard:
        $ref: '#/components/messages/ResetUserDashboard'
      DashboardEdited:
        $ref: '#/components/messages/DashboardEdited'
      ResetAllCustomDashboards:
        $ref: '#/components/messages/ResetAllCustomDashboards'

operations:
  sendDashboardMetricsCollected:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/DashboardMetricsCollected'
    description: Publishes a 'DashboardMetricsCollected' event to the analytics channel once a day containing collected dashboard metrics from the database.
  sendFavoritesUpdated:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/FavoritesUpdated'
    description: Publishes a 'FavoritesUpdated' event to the analytics channel when a user updates their favorites in the apps menu.
  sendWidgetAdded:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetAdded'
    description: Publishes a 'WidgetAdded' event to the analytics channel when a user adds a widget to the v1 dashboard.
  sendWidgetRemoved:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetRemoved'
    description: Publishes a 'WidgetRemoved' event to the analytics channel when a user removes a widget from the v1 dashboard.
  sendWidgetSettingsUpdated:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetSettingsUpdated'
    description: Publishes a 'WidgetSettingsUpdated' event to the analytics channel when a user updates the settings of a widget in the v1 dashboard.
  sendDashboardPublicAPIRequestReceived:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/DashboardPublicAPIRequestReceived'
    description: Publishes a 'DashboardPublicAPIRequestReceived' event to the analytics channel when a request is made to the Dashboard Public API.
  sendDashboardPublicAPIRequestSuccessful:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/DashboardPublicAPIRequestSuccessful'
    description: Publishes a 'DashboardPublicAPIRequestSuccessful' event to the analytics channel when a request to the Dashboard Public API is successful.
  sendTenantDashboardCreated:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/TenantDashboardCreated'
    description: Publishes a 'TenantDashboardCreated' event to the analytics channel when a tenant dashboard is created.
  sendTenantDashboardDeleted:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/TenantDashboardDeleted'
    description: Publishes a 'TenantDashboardDeleted' event to the analytics channel when a tenant dashboard is deleted.
  sendDisableDashboardV2Changed:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/DisableDashboardV2Changed'
    description: Publishes a 'DisableDashboardV2Changed' event to the analytics channel when a tenant changes the feature preview to disable or enable Dashboard V2.
  sendEnableHomeAppChanged:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/EnableHomeAppChanged'
    description: Publishes an 'EnableHomeAppChanged' event to the analytics channel when a tenant changes the feature preview to enable or disable the Home App.
  sendLegacyWidgetsConverted:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/LegacyWidgetsConverted'
    description: Publishes a 'LegacyWidgetsConverted' event to the analytics channel when the widget converter has been executed.
  sendWidgetRegistered:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetRegistered'
    description: Publishes a 'WidgetRegistered' event to the analytics channel when a new v1 widget is registered.
  sendWidgetDeregistered:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetDeregistered'
    description: Publishes a 'WidgetDeregistered' event to the analytics channel when a v1 widget is deregistered.
  sendWidgetV2ReplacedOnDashboards:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetV2ReplacedOnDashboards'
    description: Publishes a 'WidgetV2ReplacedOnDashboards' event to the analytics channel when a v1 widget is replaced by a v2 widget on dashboards.
  sendWidgetAPIV2Used:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/WidgetAPIV2Used'
    description: Publishes a 'WidgetAPIV2Used' event to the analytics channel when the Widget API V2 is used.
  sendNavigatedViaAppsMenu:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/NavigatedViaAppsMenu'
    description: Publishes a 'NavigatedViaAppsMenu' event to the analytics channel when a user navigates to an app via the apps menu.
  sendNavigatedViaWidget:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/NavigatedViaWidget'
    description: Publishes a 'NavigatedViaWidget' event to the analytics channel when a user navigates to an app via a dashboard widget.
  sendResetUserDashboard:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/ResetUserDashboard'
    description: Publishes a 'ResetUserDashboard' event to the analytics channel when a user resets their dashboard to the default dashboard.
  sendDashboardEdited:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/DashboardEdited'
    description: Publishes a 'DashboardEdited' event to the analytics channel when a user edits their dashboard.
  sendResetAllCustomDashboards:
    action: send
    channel:
      $ref: '#/channels/analytics'
    messages:
      - $ref: '#/channels/analytics/messages/ResetAllCustomDashboards'
    description: Publishes a 'ResetAllCustomDashboards' event to the analytics channel when all custom user dashboards are reset.

components:
  messages:
    DashboardMetricsCollected:
      name: DashboardMetricsCollected
      title: Dashboard Metrics Collected Event
      summary: Event emitted once a day containing collected dashboard metrics from the database.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: DashboardMetricsCollected
              properties:
                type: object
                properties:
                  totalTenantDashboardsCount:
                    type: integer
                    description: Total number of tenant dashboards across all tenants that use dashboard V2.
                  totalDisabledV2TenantsCount:
                    type: integer
                    description: Total number of tenants that have disabled dashboard V2.
                  totalV2TenantsCount:
                    type: integer
                    description: Total number of tenants that use dashboard V2.
                  totalCustomizableTnBoardCount:
                    type: integer
                    description: Total number of customizable tenant dashboards across all tenants.
                  avgTenantDashboardsPerTenant:
                    type: number
                    format: float
                    description: Average number of tenant dashboards per tenant.
                  avgAssignedTnDashboardsPerTnNew:
                    type: number
                    format: float
                    description: Average number of assigned tenant dashboards per tenant.
                  tenantDashboardsPerTenantDistr:
                    type: object
                    description: Distribution of the number of tenant dashboards per tenant.
                    additionalProperties:
                      type: integer
                      description: Number of tenants with the corresponding number of tenant dashboards.
                    propertyNames:
                      enum: [ "50", "30", "20", "10", "8", "5", "3", "2", "1", "0" ]
                  assignedTnDashboardsPerTnDistr:
                    type: object
                    description: Distribution of the number of assigned tenant dashboards per tenant.
                    additionalProperties:
                      type: integer
                      description: Number of tenants with the corresponding number of assigned tenant dashboards.
                    propertyNames:
                      enum: [ "50", "30", "20", "10", "8", "5", "3", "2", "1", "0" ]
                  totalTenantsWithWidgetVisEnable:
                    type: integer
                    description: Total number of tenants that have enabled widget visibility settings.
                  avgConsumersPerWidgetVisConfig:
                    type: number
                    format: float
                    description: Average number of consumers per widget visibility configuration.
                  avgUsersPerWidgetVisConfig:
                    type: number
                    format: float
                    description: Average number of users per widget visibility configuration.
                  avgGroupsPerWidgetVisConfig:
                    type: number
                    format: float
                    description: Average number of groups per widget visibility configuration.
                  consumersPerWidgetVisConfigDist:
                    type: object
                    description: Distribution of the number of consumers per widget visibility configuration.
                    additionalProperties:
                      type: integer
                      description: Number of widget visibility configurations with the corresponding number of consumers.
                    propertyNames:
                      enum: [ "50", "30", "20", "15", "10", "5", "3", "2", "1", "0" ]
                  usersPerWidgetVisConfigDist:
                    type: object
                    description: Distribution of the number of users per widget visibility configuration.
                    additionalProperties:
                      type: integer
                      description: Number of widget visibility configurations with the corresponding number of users.
                    propertyNames:
                      enum: [ "50", "30", "20", "15", "10", "5", "3", "2", "1", "0" ]
                  groupsPerWidgetVisConfigDist:
                    type: object
                    description: Distribution of the number of groups per widget visibility configuration.
                    additionalProperties:
                      type: integer
                      description: Number of widget visibility configurations with the corresponding number of groups.
                    propertyNames:
                      enum: [ "50", "30", "20", "15", "10", "5", "3", "2", "1", "0" ]
                  totalTenantWidgetsCount:
                    type: integer
                    description: Total number of tenant widgets across all tenants.
                  tenantWidgetUsage:
                    type: integer
                    description: Total number of tenants that use tenant widgets.
                  totalListTenantWidgetsCount:
                    type: integer
                    description: Total number of tenant list widgets across all tenants.
                  listTenantWidgetUsage:
                    type: integer
                    description: Total number of tenants that use tenant list widgets.
                  totalIFrameTenantWidgetsCount:
                    type: integer
                    description: Total number of tenant iframe widgets across all tenants.
                  iFrameTenantWidgetUsage:
                    type: integer
                    description: Total number of tenants that use tenant iframe widgets.
    FavoritesUpdated:
      name: FavoritesUpdated
      title: Favorites Updated Event
      summary: Event emitted when a user updates their favorites in the apps menu.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: FavoritesUpdated
              properties:
                type: object
                properties:
                  favorites:
                    type: array
                    description: The list of favored apps.
                    items:
                      type: string
                  favoritesCount:
                    type: integer
                    description: The total number of favored apps.
    WidgetAdded:
      name: WidgetAdded
      title: Widget Added Event
      summary: Event emitted when a user adds a widget to the v1 dashboard.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetAdded
              properties:
                type: object
                properties:
                  widgetID:
                    type: string
                    description: Unique identifier of the added widget instance.
                  registrationID:
                    type: string
                    description: Registration ID of the added widget.
                  widgetType:
                    type: string
                    description: Type of the added widget.
                    enum: [ "shortcut", "list", "iframe" ]
    WidgetRemoved:
      name: WidgetRemoved
      title: Widget Removed Event
      summary: Event emitted when a user removes a widget from the v1 dashboard.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetRemoved
              properties:
                type: object
                properties:
                  widgetID:
                    type: string
                    description: Unique identifier of the removed widget instance.
    WidgetSettingsUpdated:
      name: WidgetSettingsUpdated
      title: Widget Settings Updated Event
      summary: Event emitted when a user updates the settings of a widget in the v1 dashboard.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetSettingsUpdated
              properties:
                type: object
                properties:
                  widgetID:
                    type: string
                    description: Unique identifier of the widget instance whose settings were updated.
    DashboardPublicAPIRequestReceived:
      name: DashboardPublicAPIRequestReceived
      title: Dashboard Public API Request Received Event
      summary: Event emitted when a request is made to the Dashboard Public API.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: DashboardPublicAPIRequestReceived
              properties:
                type: object
                properties:
                  httpMethod:
                    type: string
                    description: The HTTP method used for the request.
                    enum: [ "GET", "POST", "PUT", "DELETE" ]
                  routeType:
                    type: string
                    description: The type of route accessed in the Dashboard Public API.
                    enum: [ "collection", "singleton" ]
    DashboardPublicAPIRequestSuccessful:
      name: DashboardPublicAPIRequestSuccessful
      title: Dashboard Public API Request Successful Event
      summary: Event emitted when a request to the Dashboard Public API is successful.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: DashboardPublicAPIRequestSuccessful
              properties:
                type: object
                properties:
                  httpMethod:
                    type: string
                    description: The HTTP method used for the request.
                    enum: [ "GET", "POST", "PUT", "DELETE" ]
                  routeType:
                    type: string
                    description: The type of route accessed in the Dashboard Public API.
                    enum: [ "collection", "singleton" ]
    TenantDashboardCreated:
      name: TenantDashboardCreated
      title: Tenant Dashboard Created Event
      summary: Event emitted when a tenant dashboard is created.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: TenantDashboardCreated
              properties:
                type: object
                properties:
                  agent:
                    type: string
                    description: The agent that created the tenant dashboard.
                    enum: [ "service", "user" ]
    TenantDashboardDeleted:
      name: TenantDashboardDeleted
      title: Tenant Dashboard Deleted Event
      summary: Event emitted when a tenant dashboard is deleted.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: TenantDashboardDeleted
              properties:
                type: object
                properties:
                  agent:
                    type: string
                    description: The agent that deleted the tenant dashboard.
                    enum: [ "service", "user" ]
    DisableDashboardV2Changed:
      name: DisableDashboardV2Changed
      title: Disable Dashboard V2 Changed Event
      summary: Event emitted when a tenant changes the feature preview to disable or enable Dashboard V2.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: DisableDashboardV2Changed
              properties:
                type: object
                properties:
                  active:
                    type: boolean
                    description: Indicates whether Dashboard V2 has been disabled (true) or enabled (false) by the tenant.
    EnableHomeAppChanged:
      name: EnableHomeAppChanged
      title: Enable Home App Changed Event
      summary: Event emitted when a tenant changes the feature preview to enable or disable the Home App.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: EnableHomeAppChanged
              properties:
                type: object
                properties:
                  active:
                    type: boolean
                    description: Indicates whether the Home App has been enabled (true) or disabled (false) by the tenant.
    LegacyWidgetsConverted:
      name: LegacyWidgetsConverted
      title: Legacy Widgets Converted Event
      summary: Event emitted when the widget converter has been executed.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: LegacyWidgetsConverted
              properties:
                type: object
                properties:
                  homeWidgetCount:
                    type: integer
                    description: The number of home widgets that were converted.
                  v1WidgetCount:
                    type: integer
                    description: The number of v1 dashboard widgets that were converted.
                  convertedWidgetCount:
                    type: integer
                    description: The total number of converted widgets after merging.
    WidgetRegistered:
      name: WidgetRegistered
      title: Widget Registered Event
      summary: Event emitted when a new v1 widget is registered.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetRegistered
              properties:
                type: object
                properties:
                  widgetId:
                    type: string
                    description: Unique identifier of the newly registered widget.
                  widgetType:
                    type: string
                    description: Type of the newly registered widget.
                    enum: [ "shortcut", "list", "iframe" ]
    WidgetDeregistered:
      name: WidgetDeregistered
      title: Widget Deregistered Event
      summary: Event emitted when a v1 widget is deregistered.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetDeregistered
              properties:
                type: object
                properties:
                  widgetId:
                    type: string
                    description: Unique identifier of the deregistered widget.
    WidgetAPIV2Used:
      name: WidgetAPIV2Used
      title: Widget API V2 Used Event
      summary: Event emitted when the Widget API V2 is used.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetAPIV2Used
              properties:
                type: object
                properties:
                  id:
                    type: string
                    description: Unique identifier of the widget. If the collection route is used, this is just the app name.
                    examples:
                      - "app1/my-widget"
                      - "app1"
                  method:
                    type: string
                    description: The method of the Widget API V2 that was used.
                    enum:
                      - GetAllWidgetsForApp
                      - GetWidgetByID
                      - UpsertWidget
                      - DeleteWidget
    WidgetV2ReplacedOnDashboards:
      name: WidgetV2ReplacedOnDashboards
      title: Widget V2 Replaced On Dashboards Event
      summary: Event emitted when a v1 widget is replaced by a v2 widget on dashboards.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: WidgetV2ReplacedOnDashboards
              properties:
                type: object
                properties:
                  deletedWidget:
                    type: string
                    description: Unique identifier of the v1 widget that was deleted.
                  replacementWidget:
                    type: string
                    description: Unique identifier of the v2 widget that replaced the v1 widget.
    NavigatedViaAppsMenu:
      name: NavigatedViaAppsMenu
      title: Navigated Via Apps Menu Event
      summary: Event emitted when a user navigates to an app via the apps menu.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: NavigatedViaAppsMenu
              properties:
                type: object
                properties:
                  widgetID:
                    type: string
                    description: Unique identifier of the widget instance from which the navigation was initiated.
                  isFavorite:
                    type: boolean
                    description: Indicates whether the app navigated to is marked as a favorite by the user.
    NavigatedViaWidget:
      name: NavigatedViaWidget
      title: Navigated Via Widget Event
      summary: Event emitted when a user navigates to an app via a dashboard widget.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: NavigatedViaWidget
              properties:
                type: object
                properties:
                  type:
                    type: string
                    description: The type of the widget used for navigation.
                    enum: [ "shortcut", "list", "iframe" ]
                  widgetID:
                    type: string
                    description: Unique identifier of the widget instance from which the navigation was initiated.
    ResetUserDashboard:
      name: ResetUserDashboard
      title: Reset User Dashboard Event
      summary: Event emitted when a user resets their dashboard to the default dashboard.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: ResetUserDashboard
    DashboardEdited:
      name: DashboardEdited
      title: Dashboard Edited Event
      summary: Event emitted when a user edits their dashboard.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: DashboardEdited
              properties:
                type: object
                properties:
                  kind:
                    type: string
                    description: The kind of edit performed on the dashboard.
                    enum: [ "saved", "discarded" ]
                  transactionId:
                    type: string
                    description: Unique identifier of the edit transaction. This is set when the user opens the dashboard editor.
                  dashboardId:
                    type: string
                    description: Unique identifier of the dashboard that was edited.
    ResetAllCustomDashboards:
      name: ResetAllCustomDashboards
      title: Reset All Custom Dashboards Event
      summary: Event emitted when all custom user dashboards are reset.
      contentType: application/json
      payload:
        allOf:
          - $ref: '../../../base/base-event.yaml#/BaseEvent'
          - type: object
            properties:
              event:
                const: ResetAllCustomDashboards