Subscription keys

The Subscription API links users to URI-formatted keys and provides lookup methods for notification recipients. Use it to build recipient lists for notification messages based on content or workflow events.

Access the API through ISubscriptionService. This interface provides methods to subscribe users, unsubscribe users, and find subscribers for a given key.

The Subscription API operates independently from user notifications. Neither system calls the other. For an overview of the notification framework, see User notifications. Populate the recipient field of a notification message by querying subscriptions when an event occurs. Filter the sender from the subscriber list before posting the notification.

Subscription keys

A subscription key uses URI format and identifies an item that triggers notifications. The format is unconstrained but should represent the item it identifies.

Subscribing to a key indicates interest in that item and all items below it in the URI hierarchy. Items below a key are those whose key begins with the subscribed key.

Subscribe and unsubscribe

The ISubscriptionService interface provides methods to add and remove users from subscriptions.

Call SubscribeAsync to add one or more users to a subscription. Call UnsubscribeAsync to remove one or more users.

Subscribe to the UserSubscribed and UserUnsubscribed events to track changes. These events fire only on the first change. Adding a user to a subscription a second time does not trigger the event.

Clear subscriptions

Use ClearUserAsync and ClearSubscriptionAsync to remove subscriptions in bulk when cleaning up users or keys.

Call ClearUserAsync to remove all subscriptions for a user when deleting that user from the system. Call ClearSubscriptionAsync to remove all users from a specific subscription. The UserCleared and SubscriptionCleared events fire for these operations.

List subscriptions

ListSubscriptionsAsync returns all subscriptions for a specific user. Display or audit a user's subscription state with this method.

Find subscribers

Use ListSubscribersAsync and FindSubscribersAsync to identify users subscribed to a key and build recipient lists for notifications.

ListSubscribersAsync returns users subscribed to a specific key. FindSubscribersAsync returns users that match a key fully or partially through a begins-with comparison on whole URI path segments.

📘

Note

Partial matching operates on whole segments delimited by slashes in the URI path.