Notification API Contracts

Last Update: 4/7/2017

ArtifactFilter

Extends: BaseSubscriptionFilter

Field Type
artifactId string
artifactType string
artifactUri string
type string

BaseSubscriptionFilter

Field Type
eventType string
type string

BatchNotificationOperation

Field Type
notificationOperation NotificationOperation
notificationQueryConditions array (NotificationQueryCondition)

EvaluationOperationStatus

Enum Value Notes
notSet The operation object does not have the status set.
queued The operation has been queued.
inProgress The operation is in progress.
cancelled The operation was cancelled by the user.
succeeded The operation completed successfully.
failed The operation completed with a failure.
timedOut The operation timed out.
notFound The operation could not be found.

EventActor

Defines an "actor" for an event.

Field Type Notes
id GUID Required: This is the identity of the user for the specified role.
role string Required: The event specific name of a role.

EventScope

Defines a scope for an event.

Field Type Notes
id GUID Required: This is the identity of the scope for the type.
type string Required: The event specific type of a scope.

EventsEvaluationResult

Encapsulates events result properties. It defines the total number of events used and the number of matched events.

Field Type Notes
count int32 Count of events evaluated.
matchedCount int32 Count of matched events.

ExpressionFilterClause

Subscription Filter Clause represents a single clause in a subscription filter e.g. If the subscription has the following criteria "Project Name = [Current Project] AND Assigned To = [Me] it will be represented as two Filter Clauses Clause 1: Index = 1, Logical Operator: NULL , FieldName = 'Project Name', Operator = '=', Value = '[Current Project]' Clause 2: Index = 2, Logical Operator: 'AND' , FieldName = 'Assigned To' , Operator = '=', Value = '[Me]'

Field Type Notes
fieldName string
index int32 The order in which this clause appeared in the filter query
logicalOperator string Logical Operator 'AND', 'OR' or NULL (only for the first clause in the filter)
operator string
value string

ExpressionFilterGroup

Represents a hierarchy of SubscritionFilterClauses that have been grouped together through either adding a group in the WebUI or using parethesis in the Subscription condition string

Field Type Notes
end int32 The index of the last FilterClause in this group
level int32 Level of the group, since groups can be nested for each nested group the level will increase by 1
start int32 The index of the first FilterClause in this group

ExpressionFilterModel

Field Type Notes
clauses array (ExpressionFilterClause) Flat list of clauses in this subscription
groups array (ExpressionFilterGroup) Grouping of clauses in the subscription
maxGroupLevel int32 Max depth of the Subscription tree

FieldInputValues

Extends: InputValues

Field Type
operators array (byte)

FieldValuesQuery

Extends: InputValuesQuery

Field Type
inputValues array (FieldInputValues)
scope string

IdentityRef

Field Type
displayName string
id string
imageUrl string
inactive boolean
isAadIdentity boolean
isContainer boolean
profileUrl string
uniqueName string
url string

InputValue

Information about a single value for an input

Field Type Notes
data dictionary (string, object) Any other data about this input
displayValue string The text to show for the display of this value
value string The value to store for this input

InputValues

Information about the possible/allowed values for a given subscription input

Field Type Notes
defaultValue string The default value to use for this input
error InputValuesError Errors encountered while computing dynamic values.
inputId string The id of the input
isDisabled boolean Should this input be disabled
isLimitedToPossibleValues boolean Should the value be restricted to one of the values in the PossibleValues (True) or are the values in PossibleValues just a suggestion (False)
isReadOnly boolean Should this input be made read-only
possibleValues array (InputValue) Possible values that this input can take

InputValuesError

Error information related to a subscription input value.

Field Type Notes
message string The error message.

InputValuesQuery

Field Type Notes
currentValues dictionary (string, string)
inputValues array (InputValues) The input values to return on input, and the result from the consumer on output.
resource object Subscription containing information about the publisher/consumer and the current input values

ISubscriptionChannel

Field Type
type string

ISubscriptionFilter

Field Type
eventType string
type string

NotificationEventField

Encapsulates the properties of a filterable field. A filterable field is a field in an event that can used to filter notifications for a certain event type.

Field Type Notes
fieldType NotificationEventFieldType Gets or sets the type of this field.
id string Gets or sets the unique identifier of this field.
name string Gets or sets the name of this field.
path string Gets or sets the path to the field in the event object. This path can be either Json Path or XPath, depending on if the event will be serialized into Json or XML
supportedScopes array (string) Gets or sets the scopes that this field supports. If not specified then the event type scopes apply.

NotificationEventFieldType

Encapsulates the properties of a field type. It describes the data type of a field, the operators it support and how to populate it in the UI

Field Type Notes
id string Gets or sets the unique identifier of this field type.
operatorConstraints array (OperatorConstraint)
operators array (string) Gets or sets the list of operators that this type supports.
value ValueDefinition Gets or sets the value definition of this field like the getValuesMethod and template to display in the UI

NotificationEventPublisher

Encapsulates the properties of a notification event publisher.

Field Type
id string
subscriptionManagementInfo SubscriptionManagement
url string

NotificationEventRole

Encapsulates the properties of an event role. An event Role is used for role based subscription for example for a buildCompletedEvent, one role is request by field

Field Type Notes
id string Gets or sets an Id for that role, this id is used by the event.
name string Gets or sets the Name for that role, this name is used for UI display.

NotificationEventType

Encapsulates the properties of an event type. It defines the fields, that can be used for filtering, for that event type.

Field Type Notes
category NotificationEventTypeCategory
color string Gets or sets the color representing this event type. Example: rgb(128,245,211) or #fafafa
customSubscriptionsAllowed boolean
eventPublisher NotificationEventPublisher
fields dictionary (string, NotificationEventField)
hasInitiator boolean
icon string Gets or sets the icon representing this event type. Can be a URL or a CSS class. Example: css://some-css-class
id string Gets or sets the unique identifier of this event definition.
name string Gets or sets the name of this event definition.
roles array (NotificationEventRole)
supportedScopes array (string) Gets or sets the scopes that this event type supports
url string Gets or sets the rest end point to get this event type details (fields, fields types)

NotificationEventTypeCategory

Encapsulates the properties of a category. A category will be used by the UI to group event types

Field Type Notes
id string Gets or sets the unique identifier of this category.
name string Gets or sets the friendly name of this category.

NotificationOperation

Enum Value Notes
none
suspendUnprocessed

NotificationQueryCondition

Field Type
eventInitiator GUID
eventType string
subscriber GUID
subscriptionId string

NotificationsEvaluationResult

Encapsulates notifications result properties. It defines the number of notifications and the recipients of notifications.

Field Type Notes
count int32 Count of generated notifications

NotificationStatistic

Field Type
date date-time
hitCount int32
path string
type NotificationStatisticType
user IdentityRef

NotificationStatisticsQuery

Field Type
conditions array (NotificationStatisticsQueryConditions)

NotificationStatisticsQueryConditions

Field Type
date date-time
hitCountMinimum int32
path string
type NotificationStatisticType
user IdentityRef

NotificationStatisticType

Enum Value Notes
notificationBySubscription
eventsByEventType
notificationByEventType
eventsByEventTypePerUser
notificationByEventTypePerUser
events
notifications
hourlyRangeStart
hourlyNotificationBySubscription
hourlyEventsByEventTypePerUser
hourlyEvents
hourlyNotifications

NotificationSubscription

A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.

Field Type Notes
_links ReferenceLinks Links to related resources, APIs, and views for the subscription.
adminSettings SubscriptionAdminSettings Admin-managed settings for the subscription. Only applies when the subscriber is a group.
channel ISubscriptionChannel Channel for delivering notifications triggered by the subscription.
description string Description of the subscription. Typically describes filter criteria which helps identity the subscription.
filter ISubscriptionFilter Matching criteria for the subscription.
flags SubscriptionFlags Read-only indicators that further describe the subscription.
id string Subscription identifier.
lastModifiedBy IdentityRef User that last modified (or created) the subscription.
modifiedDate date-time Date when the subscription was last modified. If the subscription has not been updated since it was created, this value will indicate when the subscription was created.
permissions SubscriptionPermissions The permissions the user have for this subscriptions.
scope SubscriptionScope The container in which events must be published from in order to be matched by the subscription. If empty, the scope is the current host (typically an account or project collection). For example, a subscription scoped to project A will not produce notifications for events published from project B.
status SubscriptionStatus Status of the subscription. Typically indicates whether the subscription is enabled or not.
statusMessage string Message that provides more details about the status of the subscription.
subscriber IdentityRef User or group that will receive notifications for events matching the subscription's filter criteria.
subscriptionUserSettings SubscriptionUserSettings User-managed settings for the subscription. Only applies when the subscriber is a group. Typically used to indicate whether the calling user is opted in or out of a group subscription.
url string REST API URL of the subscriotion.

NotificationSubscriptionCreateParameters

Parameters for creating a new subscription. A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events.

Field Type Notes
channel ISubscriptionChannel Channel for delivering notifications triggered by the new subscription.
description string Brief description for the new subscription. Typically describes filter criteria which helps identity the subscription.
filter ISubscriptionFilter Matching criteria for the new subscription.
scope SubscriptionScope The container in which events must be published from in order to be matched by the new subscription. If not specified, defaults to the current host (typically an account or project collection). For example, a subscription scoped to project A will not produce notifications for events published from project B.
subscriber IdentityRef User or group that will receive notifications for events matching the subscription's filter criteria. If not specified, defaults to the calling user.

NotificationSubscriptionTemplate

Field Type
description string
filter ISubscriptionFilter
id string
notificationEventInformation NotificationEventType
type SubscriptionTemplateType

NotificationSubscriptionUpdateParameters

Parameters for updating an existing subscription. A subscription defines criteria for matching events and how the subscription's subscriber should be notified about those events. Note: only the fields to be updated should be set.

Field Type Notes
adminSettings SubscriptionAdminSettings Admin-managed settings for the subscription. Only applies to subscriptions where the subscriber is a group.
channel ISubscriptionChannel Channel for delivering notifications triggered by the subscription.
description string Updated description for the subscription. Typically describes filter criteria which helps identity the subscription.
filter ISubscriptionFilter Matching criteria for the subscription.
scope SubscriptionScope The container in which events must be published from in order to be matched by the new subscription. If not specified, defaults to the current host (typically the current account or project collection). For example, a subscription scoped to project A will not produce notifications for events published from project B.
status SubscriptionStatus Updated status for the subscription. Typically used to enable or disable a subscription.
statusMessage string Optional message that provides more details about the updated status.
subscriber IdentityRef User or group that will receive notifications for events matching the subscription's filter criteria.
subscriptionUserSettings SubscriptionUserSettings User-managed settings for the subscription. Only applies to subscriptions where the subscriber is a group. Typically used to opt-in or opt-out a user from a group subscription.

OperatorConstraint

Encapsulates the properties of an operator constraint. An operator constraint defines if some operator is available only for specific scope like a project scope.

Field Type Notes
operator string
supportedScopes array (string) Gets or sets the list of scopes that this type supports.

The class to represent a collection of REST reference links. Example: { self: { href: "http://localhost:8080/tfs/DefaultCollection/_apis/wit/workItems/1" } }

Field Type Notes
links dictionary (string, object) The readonly view of the links. Because Reference links are readonly, we only want to expose them as read only.

SubscriptionAdminSettings

Admin-managed settings for a group subscription.

Field Type Notes
blockUserOptOut boolean If true, members of the group subscribed to the associated subscription cannot opt (choose not to get notified)

SubscriptionChannelWithAddress

Field Type
address string
type string
useCustomAddress boolean

SubscriptionEvaluationRequest

Encapsulates the properties of a SubscriptionEvaluationRequest. It defines the subscription to be evaluated and time interval for events used in evaluation.

Field Type Notes
minEventsCreatedDate date-time The min created date for the events used for matching in UTC. Use all events created since this date
subscriptionCreateParameters NotificationSubscriptionCreateParameters User or group that will receive notifications for events matching the subscription's filter criteria. If not specified, defaults to the calling user.

SubscriptionEvaluationResult

Ecapsulates the subscription evaluation results. It defines the Date Interval that was used, number of events evaluated and events and notifications results

Field Type Notes
evaluationJobStatus EvaluationOperationStatus Subscription evaluation job status
events EventsEvaluationResult Subscription evaluation events results.
id GUID The requestId which is the subscription evaluation jobId
notifications NotificationsEvaluationResult Subscription evaluation notification results.

SubscriptionEvaluationSettings

Encapsulates the subscription evaluation settings needed for the UI

Field Type Notes
enabled boolean Indicates whether subscription evaluation before saving is enabled or not
interval int32 Time interval to check on subscription evaluation job in seconds
threshold int32 Threshold on the number of notifications for considering a subscription too noisy
timeOut int32 Time out for the subscription evaluation check in seconds

SubscriptionFlags

Enum Value Notes
none None
groupSubscription Subscription's subscriber is a group, not a user
contributedSubscription Subscription is contributed and not persisted. This means certain fields of the subscription, like Filter, are read-only.
canOptOut A user that is member of the subscription's subscriber group can opt in/out of the subscription.
teamSubscription If the subscriber is a group, is it a team.

SubscriptionManagement

Encapsulates the properties needed to manage subscriptions, opt in and out of subscriptions.

Field Type
serviceInstanceType GUID
url string

SubscriptionPermissions

Enum Value Notes
none None
view full view of description, filters, etc. Not limited.
edit update subscription
delete delete subscription

SubscriptionQuery

Notification subscriptions query input.

Field Type Notes
conditions array (SubscriptionQueryCondition) One or more conditions to query on. If more than 2 conditions are specified, the combined results of each condition is returned (i.e. conditions are logically OR'ed).
queryFlags SubscriptionQueryFlags Flags the refine the types of subscriptions that will be returned from the query.

SubscriptionQueryCondition

Conditions a subscription must match to qualify for the query result set. Not all fields are required. A subscription must match all conditions specified in order to qualify for the result set.

Field Type Notes
filter ISubscriptionFilter Filter conditions that matching subscriptions must have. Typically only the filter's type and event type are used for matching.
scope string Scope that matching subscriptions must have.
subscriber GUID ID of the subscriber (user or group) that matching subscriptions must be subscribed to.
subscriptionId string ID of the subscription to query for.
subscriptionType SubscriptionType

SubscriptionQueryFlags

Enum Value Notes
none
includeAllGroupSubscriptions Include all team subscriptions for teams that the user is not member of.
includeInvalidSubscriptions Include subscriptions with invalid subscribers.
includeDeletedSubscriptions Include subscriptions marked for deletion.
includeFilterDetails Include the full filter details with each subscription.
alwaysReturnBasicInformation For a subscription the caller does not have permission to view, return basic (non-confidential) information.
includeAllSubscriptions Include all group, invalid, and subscriptions marked for deletion.

SubscriptionScope

A resource, typically an account or project, in which events are published from.

Extends: EventScope

Field Type
name string

SubscriptionStatus

Enum Value Notes
jailedByNotificationsVolume Subscription is disabled because it generated a high volume of notifications.
pendingDeletion Subscription is disabled and will be deleted.
disabledInactiveIdentity Subscription is disabled because the identity is no longer active
disabledMessageQueueNotSupported Subscription is disabled because message queue is not supported.
disabledMissingIdentity Subscription is disabled because its subscriber is unknown.
disabledInvalidRoleExpression Subscription is disabled because it has an invalid role expression.
disabledInvalidPathClause Subscription is disabled because it has an invalid filter expression.
disabledAsDuplicateOfDefault Subscription is disabled because it is a duplicate of a default subscription.
disabledByAdmin Subscription is disabled by an administrator, not the subscription's subscriber.
disabled Subscription is disabled, typically by the owner of the subscription, and will not produce any notifications.
enabled Subscription is active.
enabledOnProbation Subscription is active, but is on probation due to failed deliveries or other issues with the subscription.

SubscriptionTemplateType

Enum Value Notes
user
team
both
none

SubscriptionType

Enum Value Notes
default
shared

SubscriptionUserSettings

User-managed settings for a group subscription.

Field Type Notes
optedOut boolean Indicates whether the user will receive notifications for the associated group subscription.

ValueDefinition

Encapsulates the properties of a field value definition. It has the information needed to retrieve the list of possible values for a certain field and how to handle that field values in the UI. This information includes what type of object this value represents, which property to use for UI display and which property to use for saving the subscription

Field Type Notes
dataSource array (object) Gets or sets the data source.
endPoint string Gets or sets the rest end point.
resultTemplate string Gets or sets the result template.

VssJsonCollectionWrapper<T>

This class is used to serialized collections as a single JSON object on the wire, to avoid serializing JSON arrays directly to the client, which can be a security hole

Extends: VssJsonCollectionWrapperBase

Field Type
value T

VssJsonCollectionWrapperBase

Field Type
count int32

VssNotificationEvent

This is the type used for firing notifications intended for the subsystem in the Notifications SDK. For components that can't take a dependency on the Notifications SDK directly, they can use ITeamFoundationEventService.PublishNotification and the Notifications SDK ISubscriber implementation will get it.

Field Type Notes
actors array (EventActor) Optional: A list of actors which are additional identities with corresponding roles that are relevant to the event.
artifactUris array (string) Optional: A list of artifacts referenced or impacted by this event.
data object Required: The event payload. If Data is a string, it must be in Json or XML format. Otherwise it must have a serialization format attribute.
eventType string Required: The name of the event. This event must be registered in the context it is being fired.
scopes array (EventScope) Optional: A list of scopes which are are relevant to the event.