Visier Plan Events API

openapi: 3.2.0
info:
  title: Visier Planning Public Plan Events API
  description: Visier APIs for managing your plans through API.
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 22222222.99201.3040
security:
- ApiKeyAuth: []
  BearerAuth: []
- ApiKeyAuth: []
  CookieAuth: []
- ApiKeyAuth: []
  OAuth2Auth: []
tags:
- name: PlanEvents
  x-displayName: Plan Events
  description: Retrieve details about planning events such as member promotions and row changes.
paths:
  /v1/planning/data/events:
    get:
      tags:
      - PlanEvents
      summary: Retrieve planning events
      description: "Retrieve planning events in bulk. Specify one of `planId` or `mainPlanId`. Use `planId` to retrieve events for a single plan, or `mainPlanId` to retrieve events for a main plan and all its subplans. If both are provided, `planId` takes precedence. If neither are provided, the response includes events for all plans you have access to. Results are sorted oldest first for stable forward pagination.\n\n To retrieve the full details of a single event, including promoted member paths, see `GET /v1/planning/data/events/{eventId}`."
      operationId: PlanEvents_GetEvents
      parameters:
      - name: planId
        in: query
        description: Optionally, specify the unique identifier of the plan to retrieve events for. Specify one of `planId` or `mainPlanId`. If both are provided, `planId` takes precedence and `mainPlanId` is ignored. If both are omitted, the response includes events for all plans you have access to.
        schema:
          type: string
      - name: mainPlanId
        in: query
        description: Optionally, specify the unique identifier of the main plan. When provided, the response includes events for the main plan and all its subplans. Specify one of `planId` or `mainPlanId`. If both are provided, `planId` takes precedence and `mainPlanId` is ignored. If both are omitted, the response includes events for all plans you have access to.
        schema:
          type: string
      - name: fromDate
        in: query
        description: Optionally, specify a start date to filter by and return only the events created after it. The format is the number of milliseconds since midnight 01 January, 1970 UTC as a string.
        schema:
          type: string
      - name: toDate
        in: query
        description: Optionally, specify an end date to filter by and return only the events created before it. The format is the number of milliseconds since midnight 01 January, 1970 UTC as a string.
        schema:
          type: string
      - name: eventTypes
        in: query
        description: Optionally, specify one or more event types to filter by. If omitted, the response includes all event types.
        schema:
          type: array
          items:
            type: string
      - name: userFilter
        in: query
        description: Optionally, specify the username of the user who triggered the events. If omitted, the response includes events triggered by all users.
        schema:
          type: string
      - name: limit
        in: query
        description: The maximum number of events to return. Default and maximum is 50.
        schema:
          type: integer
          format: int32
      - name: start
        in: query
        description: The index to start retrieving events from, also known as offset. The index begins at 0.
        schema:
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/planning.GetEventsResponse'
        '404':
          description: plan not found or not accessible
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/planning.ErrorSummary'
        '500':
          description: default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1/planning/data/events/{eventId}:
    get:
      tags:
      - PlanEvents
      summary: Retrieve a planning event
      description: Retrieve a single planning event by its unique identifier. The response includes event metadata and, for promotion events, the full member path for every promoted row. One entry per plan segment. To retrieve event IDs, create a webhook for the `planRowPromotionNotification` event. When the webhook triggers, its payload returns the `eventID`. For more information, see `POST /v1/op/webhooks`.
      operationId: PlanEvents_GetEvent
      parameters:
      - name: eventId
        in: path
        description: The unique identifier of the event.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/planning.PlanningEventResponse'
        '404':
          description: event not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/planning.ErrorSummary'
        '500':
          description: default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    planning.EventSummaryDTO:
      type: object
      properties:
        eventId:
          type: string
          description: The unique identifier of the event.
        planId:
          type: string
          description: The unique identifier of the plan the event belongs to.
        scenarioId:
          type: string
          description: The unique identifier of the scenario in which the event occurred. Only present for scenario-scoped events.
        mainPlanId:
          type: string
          description: The unique identifier of the main plan this plan belongs to. Only present when the plan is a subplan.
        eventType:
          enum:
          - unknownPlanEventType
          - memberPromoted
          - autoPromotion
          - bulkPromotionDemotionEvent
          - planCreationEvent
          - planDeletionEvent
          - planTreeAutoDeletionEvent
          - orphanedSubplanDeletionEvent
          - planRenameEvent
          - planContextAndParameterRenameEvent
          - planClonedEvent
          - planPublishedEvent
          - planOpeningEvent
          - planSubmissionEvent
          - planAcceptedEvent
          - planForceAcceptedEvent
          - dataLoadEvent
          - subPlanCreationEvent
          - subPlanDeletionEvent
          - subPlanReassignEvent
          - subPlanPushedEvent
          - subPlanReopenedEvent
          - subPlanMergedEvent
          - planSharingEvent
          - planUnsharingEvent
          - sharedUserEditAccessGrantedEvent
          - sharedUserEditAccessRevokedEvent
          - collaborationStarted
          - collaborationEnded
          - metaDataModifiedEvent
          - metaDataDimensionsModifiedEvent
          - metaDataDimensionsAddedEvent
          - MetaDataDimensionsRemovedEvent
          - metaDataTimelineModifiedEvent
          - metaDataVisibleHistoricalPeriodsModifiedEvent
          - metaDataSeedDateModifiedEvent
          - metaDataCostsAddedModifiedEvent
          - metaDataCostsRemovedModifiedEvent
          - metaDataCostsModifiedEvent
          - metaDataPlanUsingActualsEvent
          - metaDataPlanUsingBudgetedEvent
          - metaDataListPlanInAnalysisEvent
          - metaDataDontListPlanInAnalysisEvent
          - addMeasureToMetricBindingEvent
          - removeMeasureToMetricBindingEvent
          - modifyMeasureToMetricBindingEvent
          - scenarioCreationEvent
          - scenarioResetEvent
          - scenarioCloneEvent
          - scenarioRevertEvent
          - scenarioRevertToSnapshotEvent
          - scenarioUpdateEvent
          - scenarioDeletionEvent
          - scenarioDataChangeEvent
          - scenarioCostChangeEvent
          - scenarioSubmissionEvent
          - scenarioRejectionEvent
          - scenarioAddedToSubPlan
          - scenarioDataFixedByPreviousVersionEvent
          - scenarioDataFitToHeadcountEvent
          - scenarioDataFitToCostEvent
          - scenarioDataFitToFTEEvent
          - scenarioDataFitToCostAndHeadcountEvent
          - scenarioDataRevenueOptimizationEvent
          - scenarioDataCostOptimizationEvent
          - scenarioDataFreezeHiresEvent
          - attachAssumptionEvent
          - detachAssumptionEvent
          - automaticDetachAssumptionEvent
          - reloadAssumptionEvent
          - memberAdded
          - memberRenamed
          - memberResolvedAsMapped
          - memberResolvedAsPreserved
          - memberResolvedAsRemoved
          - memberResolvedAsAdded
          - memberRemoved
          - planCostBudgetChangeEvent
          - planHeadcountBudgetChangeEvent
          - scenarioDrillThroughExportEvent
          - planExportHeadcountEvent
          - planExportHirecountEvent
          - planExportTCOWEvent
          - planExportEvent
          - planActivityExportEvent
          - planConsolidationCurrencyUpdateEvent
          - planDisplayCurrencyUpdateEvent
          - snapshotCreationEvent
          - snapshotDeletionEvent
          - snapshotRenameEvent
          - explorationSnapshotRenameEvent
          - updateBaselineEvent
          - planOfRecordAddEvent
          - planOfRecordRemoveEvent
          - copyScenarioDataToCollaborationEvent
          - backupScenarioCreationEvent
          - lostSyncedLimitsEvent
          - planComment
          - cellComment
          - cellDeleteComment
          - cellEditComment
          type: string
          description: The type of event.
          format: enum
        createdDate:
          type: string
          description: The date that the event was created. The format is the number of milliseconds since midnight 01 January, 1970 UTC as a string.
        user:
          type: string
          description: The username of the user who triggered the event.
      description: Summary of a single planning event without type-specific payload.
    planning.ErrorSummary:
      type: object
      properties:
        rci:
          type: string
          description: A root cause identifier that allows Visier to determine the source of the problem.
        message:
          type: string
          description: The details of the error and actions you can take to load the data correctly.
      description: The error details of the unsuccessful action.
    planning.MemberDTO:
      type: object
      properties:
        dimensionId:
          type: string
          description: The unique identifier of the dimension. For example, `Location`.
        levelId:
          type: string
          description: The dimension level this member belongs to. For example, `Location_2`.
        memberId:
          type: string
          description: The unique identifier of the member. For example, `[Location].[Canada].[BC]`.
        displayName:
          type: string
          description: The display name of the member. For example, `BC`.
        namePath:
          type: array
          items:
            type: string
          description: The path of member names from the root member down to the current member. For example, `[Canada, BC]`.
      description: A single member at a specific dimension level within the plan's context path.
    planning.BulkPromotionDemotionEventData:
      type: object
      properties:
        promotedRows:
          type: array
          items:
            $ref: '#/components/schemas/planning.PromotedRowDTO'
          description: The rows that were promoted. Each entry represents one promoted row with its dimension members.
        demotedRows:
          type: array
          items:
            $ref: '#/components/schemas/planning.PromotedRowDTO'
          description: The rows that were demoted. Each entry represents one demoted row with its dimension members.
      description: Event data for bulkPromotionDemotionEvent events.
    planning.PromotedRowDTO:
      type: object
      properties:
        memberPath:
          type: array
          items:
            $ref: '#/components/schemas/planning.MemberDTO'
          description: One entry per hierarchy level and dimension included in the plan's analysis context.
      description: The member path for a single promoted row.
    planning.GetEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/planning.EventSummaryDTO'
          description: The list of events matching the query filters.
        limit:
          type: integer
          description: The maximum number of events returned. Maximum is 50.
          format: int32
        start:
          type: integer
          description: The index to start retrieving events from, also known as offset. The index begins at 0.
          format: int32
      description: Response for the bulk events listing endpoint.
    planning.PlanningEventResponse:
      type: object
      properties:
        eventId:
          type: string
          description: The unique identifier of the event.
        planId:
          type: string
          description: The unique identifier of the plan the event belongs to.
        scenarioId:
          type: string
          description: The unique identifier of the scenario in which the event occurred. Only present for scenario-scoped events.
        mainPlanId:
          type: string
          description: The unique identifier of the main plan this plan belongs to. Only present when the plan is a subplan.
        eventType:
          enum:
          - unknownPlanEventType
          - memberPromoted
          - autoPromotion
          - bulkPromotionDemotionEvent
          - planCreationEvent
          - planDeletionEvent
          - planTreeAutoDeletionEvent
          - orphanedSubplanDeletionEvent
          - planRenameEvent
          - planContextAndParameterRenameEvent
          - planClonedEvent
          - planPublishedEvent
          - planOpeningEvent
          - planSubmissionEvent
          - planAcceptedEvent
          - planForceAcceptedEvent
          - dataLoadEvent
          - subPlanCreationEvent
          - subPlanDeletionEvent
          - subPlanReassignEvent
          - subPlanPushedEvent
          - subPlanReopenedEvent
          - subPlanMergedEvent
          - planSharingEvent
          - planUnsharingEvent
          - sharedUserEditAccessGrantedEvent
          - sharedUserEditAccessRevokedEvent
          - collaborationStarted
          - collaborationEnded
          - metaDataModifiedEvent
          - metaDataDimensionsModifiedEvent
          - metaDataDimensionsAddedEvent
          - MetaDataDimensionsRemovedEvent
          - metaDataTimelineModifiedEvent
          - metaDataVisibleHistoricalPeriodsModifiedEvent
          - metaDataSeedDateModifiedEvent
          - metaDataCostsAddedModifiedEvent
          - metaDataCostsRemovedModifiedEvent
          - metaDataCostsModifiedEvent
          - metaDataPlanUsingActualsEvent
          - metaDataPlanUsingBudgetedEvent
          - metaDataListPlanInAnalysisEvent
          - metaDataDontListPlanInAnalysisEvent
          - addMeasureToMetricBindingEvent
          - removeMeasureToMetricBindingEvent
          - modifyMeasureToMetricBindingEvent
          - scenarioCreationEvent
          - scenarioResetEvent
          - scenarioCloneEvent
          - scenarioRevertEvent
          - scenarioRevertToSnapshotEvent
          - scenarioUpdateEvent
          - scenarioDeletionEvent
          - scenarioDataChangeEvent
          - scenarioCostChangeEvent
          - scenarioSubmissionEvent
          - scenarioRejectionEvent
          - scenarioAddedToSubPlan
          - scenarioDataFixedByPreviousVersionEvent
          - scenarioDataFitToHeadcountEvent
          - scenarioDataFitToCostEvent
          - scenarioDataFitToFTEEvent
          - scenarioDataFitToCostAndHeadcountEvent
          - scenarioDataRevenueOptimizationEvent
          - scenarioDataCostOptimizationEvent
          - scenarioDataFreezeHiresEvent
          - attachAssumptionEvent
          - detachAssumptionEvent
          - automaticDetachAssumptionEvent
          - reloadAssumptionEvent
          - memberAdded
          - memberRenamed
          - memberResolvedAsMapped
          - memberResolvedAsPreserved
          - memberResolvedAsRemoved
          - memberResolvedAsAdded
          - memberRemoved
          - planCostBudgetChangeEvent
          - planHeadcountBudgetChangeEvent
          - scenarioDrillThroughExportEvent
          - planExportHeadcountEvent
          - planExportHirecountEvent
          - planExportTCOWEvent
          - planExportEvent
          - planActivityExportEvent
          - planConsolidationCurrencyUpdateEvent
          - planDisplayCurrencyUpdateEvent
          - snapshotCreationEvent
          - snapshotDeletionEvent
          - snapshotRenameEvent
          - explorationSnapshotRenameEvent
          - updateBaselineEvent
          - planOfRecordAddEvent
          - planOfRecordRemoveEvent
          - copyScenarioDataToCollaborationEvent
          - backupScenarioCreationEvent
          - lostSyncedLimitsEvent
          - planComment
          - cellComment
          - cellDeleteComment
          - cellEditComment
          type: string
          description: The type of event.
          format: enum
        createdDate:
          type: string
          description: The date that the event was created. The format is the number of milliseconds since midnight 01 January, 1970 UTC as a string.
        user:
          type: string
          description: The username of the user who triggered the event.
        promotionData:
          $ref: '#/components/schemas/planning.PromotionEventData'
        bulkPromotionDemotionData:
          $ref: '#/components/schemas/planning.BulkPromotionDemotionEventData'
      description: Response for a single planning event.
    planning.PromotionEventData:
      type: object
      properties:
        promotedRows:
          type: array
          items:
            $ref: '#/components/schemas/planning.PromotedRowDTO'
          description: The rows that were promoted. Each entry represents one promoted row with its dimension members.
      description: Event data for memberPromoted and autoPromotion events.
    Status:
      type: object
      properties:
        localizedMessage:
          type: string
          description: Localized error message describing the root cause of the error.
        code:
          type: string
          description: Error classification.
        message:
          type: string
          description: Not used.
        rci:
          type: string
          description: Optional root cause identifier.
        userError:
          type: boolean
          description: Indicates whether the error is a user error.
      description: The response structure for errors.
  securitySchemes:
    CookieAuth:
      type: apiKey
      name: VisierASIDToken
      in: cookie
    ApiKeyAuth:
      type: apiKey
      name: apikey
      in: header
    BearerAuth:
      type: http
      scheme: bearer
    OAuth2Auth:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: /v1/auth/oauth2/authorize
          tokenUrl: /v1/auth/oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
        password:
          tokenUrl: /v1/auth/oauth2/token
          scopes:
            read: Grants read access
            write: Grants write access
x-tagGroups:
- name: planning
  tags:
  - PlanAdministration
  - PlanDataLoad
  - PlanEvents