openapi: 3.2.0
info:
title: Visier Analytic Model Personalized Alerts API
description: Visier APIs for retrieving and configuring your analytic model in Visier.
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: PersonalizedAlerts
x-displayName: Personalized Alerts
description: 'Manage your personalized alerts in Visier. Alerts notify you if a metric exceeds your defined threshold.
<br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.
If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>'
paths:
/v1alpha/alerts:
get:
tags:
- PersonalizedAlerts
summary: Retrieve personalized alerts
description: "Get all personalized alerts you have access to. The response returns each alert’s ID, creator, and whether the alert is enabled or disabled.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_GetAlerts
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.GetEventAlertsResponseDTO'
post:
tags:
- PersonalizedAlerts
summary: Create a personalized alert
description: "Create a new personalized alert. In the request body, define the alert’s display name and its trigger criteria, including the metric, filters, time periods, and threshold value.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_CreateAlert
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/platform.CreateEventAlertRequestDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.EventAlertDTO'
/v1alpha/alerts/{alertId}:
get:
tags:
- PersonalizedAlerts
summary: Retrieve a personalized alert
description: "Get the details of a specific personalized alert. You must know the ID of the alert to retrieve its details. To retrieve all alert IDs, see `GET /v1alpha/alerts`.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_GetAlert
parameters:
- name: alertId
in: path
required: true
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.EventAlertDTO'
put:
tags:
- PersonalizedAlerts
summary: Update a personalized alert
description: "Make changes to an existing personalized alert. You can only update alerts that you created. You must know the ID of the alert to update it. To retrieve all alert IDs, see `GET /v1alpha/alerts`.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_UpdateAlert
parameters:
- name: alertId
in: path
description: The unique identifier of the alert.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/platform.EventAlertDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.EventAlertDTO'
delete:
tags:
- PersonalizedAlerts
summary: Delete a personalized alert
description: "Delete a personalized alert. You can only delete alerts that you created. Alternatively, to disable an alert, see `PUT /v1alpha/alerts/{alertId}/recipient-status`. You must know the ID of the alert to delete it. To retrieve all alert IDs, see `GET /v1alpha/alerts`.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_DeleteAlert
parameters:
- name: alertId
in: path
description: The unique identifier of the alert.
required: true
schema:
type: string
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.EventAlertDeleteSuccessDTO'
/v1alpha/alerts/{alertId}/recipient-status:
put:
tags:
- PersonalizedAlerts
summary: Enable or disable a personalized alert
description: "Enable or disable a personalized alert. Disabling an alert removes it from your Home room and future email digests. You can re-enable an alert at any time.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_UpdateRecipientStatus
parameters:
- name: alertId
in: path
description: The unique identifier of the alert.
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/platform.UpdateEventAlertRecipientStatusDTO'
required: true
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.UpdateEventAlertRecipientStatusDTO'
/v1alpha/notifications:
get:
tags:
- PersonalizedAlerts
summary: Retrieve personalized alerts notifications
description: "Get all the notifications for your active personalized alerts from the last 30 days. For all active alerts, the response returns the date that the alert was triggered and the alert’s trigger criteria.\n\n <br>**Note:** <em>This API is in **alpha**. While in alpha, APIs may change in a breaking way without notice; functionality may be removed, and no deprecation notices will be issued.\n If you are interested in using this API, please contact your Customer Success Manager (CSM).</em>"
operationId: PersonalizedAlerts_GetNotifications
responses:
default:
description: Default error response
content:
application/json:
schema:
$ref: '#/components/schemas/Status'
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/platform.EventAlertNotificationResultsDTO'
components:
schemas:
platform.EventAlertRelatedContentDTO:
type: object
properties:
analysis:
allOf:
- $ref: '#/components/schemas/platform.EventAlertRelatedAnalysisDTO'
description: The analysis related to the alert.
platform.ComparedMetricDTO:
type: object
properties:
noComparison:
allOf:
- $ref: '#/components/schemas/platform.SameMetricDTO'
description: Do not compare the metric value to anything but its own value.
sameMetricOtherContext:
allOf:
- $ref: '#/components/schemas/platform.SameMetricOtherContextDTO'
description: Compare the metric against a group; for example, High Performers.
sameMetricOtherTime:
allOf:
- $ref: '#/components/schemas/platform.SameMetricOtherTimeDTO'
description: Compare the metric against a time period; for example, the previous period or the same period of the previous year.
otherMetric:
allOf:
- $ref: '#/components/schemas/platform.OtherMetricDTO'
description: Compare the metric against a different metric; for example, a Visier Benchmarks metric.
description: Whether to trigger the alert when the metric value is compared to a time period, another metric, or a group.
platform.MemberValuesDTO:
type: object
properties:
included:
type: array
items:
$ref: '#/components/schemas/platform.DimensionMemberReferenceDTO'
description: The unique IDs of members to include when evaluating the metric.
excluded:
type: array
items:
$ref: '#/components/schemas/platform.DimensionMemberReferenceDTO'
description: The unique IDs of members to exclude when evaluating the metric.
description: "Member filter values are discrete member references in a dimension filter. You can define\n included and excluded members simultaneously. This is typically done with filtering applied on\n dimensions with multiple levels. For example, a Location parameter may include \"South\n America\" and exclude \"Brazil\" which results in the metric being evaluated for all South American\n countries except Brazil."
platform.CreateEventAlertRequestDTO:
type: object
properties:
triggerCriteria:
allOf:
- $ref: '#/components/schemas/platform.EventAlertTriggerCriteriaDTO'
description: The conditions on which to trigger the personalized alert.
displayName:
type: string
description: The display name of the alert.
description:
type: string
description: optional, The user provided description of the alert.
description: The details of the personalized alert to create.
platform.RelativeTimeShiftDTO:
type: object
properties:
periodType:
type: string
timeShift:
type: integer
format: int32
platform.EventAlertRelatedAnalysisDTO:
type: object
properties:
analysisId:
type: string
description: The unique identifier of the related analysis.
businessQuestionId:
type: string
description: The unique identifier of the analysis's heading (or business question).
platform.EventAlertTriggerCriteriaDTO:
type: object
properties:
groupedMetricValueThreshold:
allOf:
- $ref: '#/components/schemas/platform.GroupedMetricValueThresholdCriteriaDTO'
description: The metric value threshold and additional conditions that trigger the alert.
description: The conditions on which to trigger the personalized alert.
platform.SameMetricOtherTimeDTO:
type: object
properties:
timePeriod:
$ref: '#/components/schemas/platform.TimePeriodMetadataDTO'
description: Compare the metric against a time period; for example, the previous period or the same period of the previous year.
platform.DimensionReferenceDTO:
type: object
properties:
id:
type: string
description: The unique identifier of the dimension.
qualifyingPath:
type: string
description: "The qualifying path to the dimension in Visier, such as the analytic object or event the dimension is\n associated with. If the path has multiple objects, each object is separated by a period."
description: The name and qualifying path of a dimension to query.
platform.TriggerCriteriaResultInfoDTO:
type: object
properties:
overallResult:
allOf:
- $ref: '#/components/schemas/platform.TriggerCriteriaOverallResultInfoDTO'
description: The metric value.
memberResult:
allOf:
- $ref: '#/components/schemas/platform.TriggerCriteriaMemberResultInfoDTO'
description: The metric value by member ID, display name, and value.
description: Information about the evaluated metric value.
platform.UpdateEventAlertRecipientStatusDTO:
type: object
properties:
status:
enum:
- UNSUPPORTED_EVENT_ALERT_STATUS
- SUBSCRIBED
- PAUSED
type: string
description: "Whether the alert is enabled for the user. Valid values:\n * `SUBSCRIBED`: The alert is enabled and the user will receive notifications for the alert.\n * `PAUSED`: The alert is disabled and the user will not receive notifications for the alert."
format: enum
platform.BetweenRuleDTO:
type: object
properties:
lower:
type: number
description: The lower bound of the range.
format: double
upper:
type: number
description: The upper bound of the range.
format: double
description: The alert triggers if the metric value is between two defined values.
platform.EventAlertNotificationResultsDTO:
type: object
properties:
notifications:
type: array
items:
$ref: '#/components/schemas/platform.EventAlertNotificationResultDTO'
description: The alert notifications that have triggered for the user.
description: The notifications that have triggered for the user.
platform.TimeHandlingDTO:
type: object
properties:
perPeriod:
type: boolean
description: The metric is evaluated per period, such as per month or per quarter.
trailingPeriods:
allOf:
- $ref: '#/components/schemas/platform.PeriodsBackDTO'
description: The metric is evaluated over a trailing period, such as the last 12 months.
description: The time handling settings for a metric, which can be either per period or trailing periods.
platform.FixedTimeTypeDTO:
type: object
properties:
periodType:
enum:
- MONTH
- DAY
- WEEK
- QUARTER
- YEAR
type: string
description: The time period type for each interval. Default is `MONTH`.
format: enum
end:
type: string
description: The end time of the fixed time period.
periodCount:
type: integer
description: The number of time periods per interval.
format: int32
description: Compare against a fixed time period.
platform.EventAlertNotificationResultDTO:
type: object
properties:
alertNotificationId:
type: string
description: The unique identifier of the alert notification.
alertId:
type: string
description: The unique identifier the alert that triggered the notification
createdDate:
type: string
description: The date that the notification generated.
alertDetails:
allOf:
- $ref: '#/components/schemas/platform.EventAlertNotificationResultAlertDetailsDTO'
description: Information about the triggered alert.
resultInfo:
type: array
items:
$ref: '#/components/schemas/platform.TriggerCriteriaResultInfoDTO'
description: Information about the evaluated metric value.
resultType:
enum:
- NOMINAL
- TRIGGERED
type: string
description: "Whether the metric value was nominal (did not trigger the alert) or triggered the alert. Valid values:\n * `TRIGGERED`: The alert was triggered.\n * `NOMINAL`: The alert was nominal (not triggered)."
format: enum
description: A notification that has triggered for the user.
platform.MetricFilterParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique identifier of the member parameter qualified by the object.
filters:
type: array
items:
$ref: '#/components/schemas/platform.FilterDTO'
description: The filters on the primary metric input parameter.
description: The filter values of a metric parameter, including the parameter ID and the filters on the parameter
platform.NumericRangeFilterDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/platform.DimensionReferenceDTO'
description: The unique identifier of the dimension.
numericRange:
allOf:
- $ref: '#/components/schemas/platform.NumericRangeDTO'
description: The numeric range to filter by
isExcluded:
type: boolean
description: If `true`, filter by values outside this numeric range.
description: A filter that uses a numeric range.
platform.TriggerCriteriaMemberResultInfoDTO:
type: object
properties:
memberId:
type: string
description: The unique identifier of the member.
displayName:
type: string
description: The user-friendly display name of the member.
value:
type: number
description: The value as a number.
format: double
formattedValue:
type: string
description: The value as a string.
description: The metric value by member ID, display name, and value.
platform.RelativeTimeSelectionDTO:
type: object
properties:
periodType:
type: string
forward:
type: integer
format: int32
back:
type: integer
format: int32
platform.PreviousPeriodTimeTypeDTO:
type: object
properties: {}
description: Compare against the previous period.
platform.EventAlertNotificationResultAlertDetailsDTO:
type: object
properties:
triggerType:
enum:
- UNSPECIFIED
- DV_UPDATE
type: string
description: "The event type that triggered the alert.\n * `UNSPECIFIED`: An unspecified event triggers the alert. Throws an exception if used.\n * `DV_UPDATE`: A data version update triggers the alert."
format: enum
triggerCriteria:
allOf:
- $ref: '#/components/schemas/platform.EventAlertTriggerCriteriaDTO'
description: The conditions on which to trigger the personalized alert.
description: Information about the alert notification that triggered.
platform.KeyGroupFilterDTO:
type: object
properties:
id:
type: string
description: The unique identifier of the key group.
qualifyingPath:
type: string
description: "The qualifying path to the key group in Visier, such as the analytic object or event the selection\n concept is associated with. If the path has multiple objects, each object is separated by a period."
description: A filter that uses a key group in Visier.
platform.EventAlertDeleteSuccessDTO:
type: object
properties:
alertId:
type: string
description: The unique identifier of the deleted alert.
description: The alert that was successfully deleted.
platform.VersionedPlanParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique identifier of the versioned plan parameter qualified by the object.
versionedPlanId:
type: string
description: The unique identifier of the versioned plan the parameter is based on.
versionedScenarioId:
type: string
description: The unique identifier of the versioned scenario the parameter is based on.
description: The value for a parameter on a planning metric, including the parameter ID and the versioned plan the parameter is based on.
platform.FilterDTO:
type: object
properties:
selectionConcept:
allOf:
- $ref: '#/components/schemas/platform.SelectionConceptReferenceDTO'
description: A filter that uses an existing selection concept in Visier.
memberSet:
allOf:
- $ref: '#/components/schemas/platform.MemberFilterDTO'
description: A filter that includes or excludes dimension members.
conceptReference:
allOf:
- $ref: '#/components/schemas/platform.ConceptReferenceFilterDTO'
description: A filter that uses a reference to a concept in Visier.
keyGroup:
allOf:
- $ref: '#/components/schemas/platform.KeyGroupFilterDTO'
description: A filter that uses a key group in Visier.
persistedCohort:
allOf:
- $ref: '#/components/schemas/platform.PersistedCohortFilterDTO'
description: A filter that uses a persisted cohort in Visier.
timePeriod:
allOf:
- $ref: '#/components/schemas/platform.TimePeriodFilterDTO'
description: A filter that uses a time period.
numericRange:
allOf:
- $ref: '#/components/schemas/platform.NumericRangeFilterDTO'
description: A filter that uses a numeric range.
description: A filter selects specific data points within a population.
platform.SameMetricOtherContextDTO:
type: object
properties:
filters:
type: array
items:
$ref: '#/components/schemas/platform.FilterDTO'
description: The filters on the comparison metric.
description: Compare the metric against a group; for example, High Performers.
platform.GetEventAlertsResponseDTO:
type: object
properties:
ownedAlerts:
type: array
items:
$ref: '#/components/schemas/platform.EventAlertDTO'
description: The personalized alerts created by the user.
sharedAlerts:
type: array
items:
$ref: '#/components/schemas/platform.EventAlertDTO'
description: The personalized alerts shared with the user by someone else.
description: The personalized alerts the user has access to.
platform.RuleSetDTO:
type: object
properties:
compareTo:
allOf:
- $ref: '#/components/schemas/platform.ComparedMetricDTO'
description: Whether to trigger the alert when the metric value is compared to a time period, another metric, or a group.
rules:
type: array
items:
$ref: '#/components/schemas/platform.RuleDTO'
description: The rules used to evaluate the values. Currently only a single rule is supported to trigger an alert.
platform.ConceptReferenceFilterDTO:
type: object
properties:
id:
type: string
description: The unique identifier of the concept reference.
qualifyingPath:
type: string
description: "The qualifying path to the concept reference in Visier, such as the analytic object or event the selection\n concept is associated with. If the path has multiple objects, each object is separated by a period."
description: A filter that uses a reference to a concept in Visier.
platform.SameMetricDTO:
type: object
properties: {}
description: Do not compare the metric value to anything but its own value.
platform.NumericRangeDTO:
type: object
properties:
rangeStart:
type: string
description: The start of the numeric range.
rangeEnd:
type: string
description: The end of the numeric range.
rangeType:
enum:
- EXCLUSIVE_INCLUSIVE
- INCLUSIVE_EXCLUSIVE
- BOTH_EXCLUSIVE
- BOTH_INCLUSIVE
type: string
description: The type of numeric range, determining whether start and end of the range are inclusive or exclusive.
format: enum
description: A numeric range.
platform.TimePeriodDTO:
type: object
properties:
end:
type: string
description: The end of the time period.
periodType:
enum:
- MONTH
- DAY
- WEEK
- QUARTER
- YEAR
type: string
description: The period type for this interval. Default is `MONTH`.
format: enum
periodCount:
type: integer
description: The number of periods per interval. Default is 1.
format: int32
timeType:
enum:
- FIXED
- PREVIOUS_PERIOD
- PREVIOUS_YEAR
- LAST_PERIOD_PREVIOUS_YEAR
- CUSTOM
- DYNAMIC_TIME
- LAST_PERIODS
type: string
description: The type of time period.
format: enum
expression:
allOf:
- $ref: '#/components/schemas/platform.RelativeTimeExpressionDTO'
description: The expression that defines the relative time period.
description: A time period can define a specific interval of time or relative time period.
platform.MetricDTO:
type: object
properties:
id:
type: string
description: The unique identifier of the metric.
parameterValues:
type: array
items:
$ref: '#/components/schemas/platform.ParameterDefinitionDTO'
description: The values associated with the metric's parameters, if defined.
timeHandling:
allOf:
- $ref: '#/components/schemas/platform.TimeHandlingDTO'
description: The time handling settings for the metric.
description: The information of a metric.
platform.SubjectMemberSetParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique identifier of the metric subject member set parameter.
customSelection:
allOf:
- $ref: '#/components/schemas/platform.CustomMemberSetSelectionDTO'
description: A list of dimension members in the parameter.
presetSelection:
allOf:
- $ref: '#/components/schemas/platform.PresetMemberSetSelectionDTO'
description: A subject member to select in the parameter. For example, if the preset subject is Employee, `presetSelection` determines the specific employee to create a `customSelection` from.
description: The value for a metric subject member set parameter.
platform.DimensionMemberReferenceDTO:
type: object
properties:
path:
type: array
items:
type: string
description: "A list of strings representing the members within a dimension path. For example, a dimension for Location\n may have the paths \"Canada, BC, Vancouver\" and \"US, California, San Francisco\"."
memberId:
type: string
description: The unique identifier of the dimension member. Use `memberId` if the dimension member doesn't have a path, such as SD groups.
description: The members of a dimension.
platform.PersistedCohortFilterDTO:
type: object
properties:
id:
type: string
description: The unique identifier of the concept reference.
qualifyingPath:
type: string
description: "The qualifying path to the persisted cohort in Visier, such as the analytic object or event the selection\n concept is associated with. If the path has multiple objects, each object is separated by a period."
description: A filter that uses a persisted cohort in Visier.
platform.AggregationTypeParameterValueDTO:
type: object
properties:
parameterId:
type: string
description: The unique identifier of the aggregation parameter.
aggregationOptionId:
type: string
description: The unique identifier of the aggregation option.
description: The value for an aggregation parameter.
platform.RuleDTO:
type: object
properties:
relativeToValueRule:
allOf:
- $ref: '#/components/schemas/platform.RelativeToRuleDTO'
description: The alert triggers if the metric value meets the defined value threshold.
betweenValuesRule:
allOf:
- $ref: '#/components/schemas/platform.BetweenRuleDTO'
description: The alert triggers if the metric value is between two defined values.
description: The value to evaluate the metric value against.
platform.SamePeriodPreviousYearTimeTypeDTO:
type: object
properties: {}
description: Compare against the same period in the previous year.
platform.RelativeToRuleDTO:
type: object
properties:
rulePredicate:
enum:
- LESS_THAN
- LESS_THAN_OR_EQUAL
- EQUAL
- GREATER_THAN_OR_EQUAL
- GREATER_THAN
type: string
description: The alert operator, such as greater than, equal to, or less than. Default is `GREATER_THAN`.
format: enum
comparand:
type: number
description: The value that triggers the alert.
format: double
description: The alert triggers if the metric value meets the defined value threshold.
platform.MemberSetParameterSelectionsDTO:
type: object
properties:
dimensionMember:
type: array
items:
$ref: '#/components/schemas/platform.MemberSetParameterSelectionDTO'
description: The dimensions member's ID and whether or not the member ID exists.
platform.TimePeriodFilterDTO:
type: object
properties:
dimension:
allOf:
- $ref: '#/components/schemas/platform.DimensionReferenceDTO'
description: The dimension to filter by.
timePeriod:
allOf:
- $ref: '#/components/schemas/platform.TimePeriodDTO'
description: The time period to filter by.
calendarId:
type: string
description: The unique identifier of the calendar to use when
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-personalizedalerts-api-openapi.yml