This document refers to using Nerdgraph APIs for the new notification platform using destinations and notification messages. Notification messages are also referred to as channels, which are different from legacy notification channels.
The channels query allows you to paginate through all of your channels per account. It also allows some filtering functionality.
Here's an example:
{
actor{
account(id:YOUR_ACCOUNT_ID){
aiNotifications{
channels{
entities{
id
name
}
error{
details
}
}
}
}
}
}
In order to paginate through your channels, you must request the nextCursor field on your initial query.
With cursor pagination, you continue to make a request through the result set until the nextCursor that is returned from the response comes back empty. This signifies that you reached the end of your results.
Here's an example:
{
actor{
account(id:YOUR_ACCOUNT_ID){
aiNotifications{
channels(cursor:""){
nextCursor
entities{
id
name
}
totalCount
}
}
}
}
}
The code above returns a set of results like this:
The API allows channel queries by name. The name filter returns exact matches and partial matches. It's case insensitive. This will only return the information for the channels that match the name supplied.
In this example, we want to find channels with "DevOps" in the name:
{
actor{
account(id:YOUR_ACCOUNT_ID){
aiNotifications{
channels(filters:{name:"DevOps"}){
entities{
id
name
}
}
}
}
}
}
The API lets you query by channel ID:
{
actor{
account(id:YOUR_ACCOUNT_ID){
aiNotifications{
channels(filters:{id:YOUR_CHANNEL_ID}){
entities{
id
name
}
}
}
}
}
}
The API lets you query channels by destination ID:
The API lets you query by channel type. The following query will return all email channels on the chosen account:
{
actor{
account(id:YOUR_ACCOUNT_ID){
aiNotifications{
channels(filters:{type:EMAIL}){
entities{
id
name
}
}
}
}
}
}
Create a channel
In order to create a channel, different inputs must be supplied for each channel type. Each channel is connected to a destination. For information on destinations, see the NerdGraph tutorial on destinations.
The best practice is to use the channelSchema endpoint to see which fields must be sent under properties like so:
{
actor{
account(id:YOUR_ACCOUNT_ID){
aiNotifications{
channelSchema(
channelType:CHANNEL_TYPE
destinationId:YOUR_DESTINATION_ID
product:YOUR_PRODUCT
constraints:[]
){
schema{
fields{
mandatory
label
key
component
}
}
result
}
}
}
}
}
Jira is a configurable ticketing system, and therefore there's no static way to create this channel.
There are two static fields - project and issuetype.
Fetch the project suggestions, and use one of the values as the constraint for issuetype, as shown here:
The payload property is the payload that will be sent in the notification. It uses the handlebars syntax to dynamically insert information from the request.
The eventSource must be the full url for an existing event source.
The eventContent is the payload that will be sent in the body of the notification, as shown here:
When you update a channel, note that you don't need to supply all of the attributes on the channel. For example, if you only want to update the name, that's the only attribute you need to update, as shown here:
mutation{
aiNotificationsUpdateChannel(
accountId:YOUR_ACCOUNT_ID
channelId:YOUR_CHANNEL_ID
channel:{name:"Updated channel Name"}
){
channel{
id
name
}
}
}
Testing a channel
You can test channels via the NerdGraph API. This can be done before or after creating the channel.