-
Notifications
You must be signed in to change notification settings - Fork 2
Subscriptions and Notifications
PowerKanban features a subscription and notification system like many platforms offer. Every user can subscribe to his own records and also sees and confirms his own notifications for his subscribed records. You will only get notifications regarding a record when you are subscribed for it.
Being subscribed means, that there is a subscription record which you is owned by you and which points to the record which you subscribe to. It is important to know, that the subscription and the notification entity both need to contain a lookup to every entity that you want to subscribe to / be notified about. You can create them yourself and set the names for your lookups in the configuration json.
This was a design decision for not running into trouble with cluttering your system when records are deleted. You should set all your custom lookups inside subscriptions and notifications to "Cascade Delete" so that subscriptions are deleted once their reference record is deleted.
You need to configure the Xrm.Oss.PowerKanban.CreateNotification plugin with new plugin steps registered to the entity events that interest you. You should register your steps on post stage, if possible in asynchronous mode.
{
"$schema": "http://json-schema.org/draft-07/schema",
"$id": "http://example.com/example.json",
"type": "object",
"title": "PowerKanban SDK message config",
"description": "Schema for a complete PowerKanban SDK message step config",
"default": {},
"examples": [
{
"parentLookupName": "regardingobjectid",
"subscriptionLookupName": "oss_incidentid",
"notificationLookupName": "oss_incidentid",
"notifyCurrentUser": true,
"xtlCondition": "IsEqual(Value('directioncode'), false)",
"messageConfig": {
"default": "A new mail regarding this case has been received"
},
"emailLocaleConfig": {
"default": "new_task_for_incident"
},
"globalNotificationConfig": {
"default": "New tasks regarding cases have been created, click to open"
}
}
],
"required": [
"subscriptionLookupName",
"notificationLookupName"
],
"properties": {
"parentLookupName": {
"$id": "#/properties/parentLookupName",
"type": "string",
"title": "parentLookupName",
"description": "Pass the lookup name to a parent entity if the current record is a child record of a parent, where you want to see notifications. When using this, subscriptions are checked for the parent record and notifications are also created targeting the parent record. Therefore when using this option, subscriptionLookupName and notificationLookupName should contain the lookup names pointing to the parent entity.",
"default": "",
"examples": [
"regardingobjectid"
]
},
"subscriptionLookupName": {
"$id": "#/properties/subscriptionLookupName",
"type": "string",
"title": "subscriptionLookupName",
"description": "The name of the lookup you created on the subscription entity, that points to your entity that you want to subscribe to. When using parentLookupName, the lookup must point to the parent entity, not to the current one.",
"default": "",
"examples": [
"oss_incidentid"
]
},
"notificationLookupName": {
"$id": "#/properties/notificationLookupName",
"type": "string",
"title": "notificationLookupName",
"description": "The name of the lookup you created on the notification entity, that points to your entity that you want to be notified about. When using parentLookupName, the lookup must point to the parent entity, not to the current one.",
"default": "",
"examples": [
"oss_incidentid"
]
},
"notifyCurrentUser": {
"$id": "#/properties/notifyCurrentUser",
"type": "boolean",
"title": "notifyCurrentUser",
"description": "Define whether current user should receive notifications for actions he did himself. If true, all users, even the current user, are notified on events. If false, all users except the user who triggered the event are being notified.",
"default": false,
"examples": [
true
]
},
"xtlCondition": {
"$id": "#/properties/xtlCondition",
"type": "string",
"title": "xtlCondition",
"description": "An XTL expression which should evaluate to True or False. A false result will abort the execution, whereas true continues with creating notifications. If this is not configured, notifications are always created.",
"default": "",
"examples": [
"IsEqual(Value('directioncode'), false)"
]
},
"messageConfig": {
"$id": "#/properties/messageConfig",
"type": "object",
"title": "messageConfig",
"description": "A string-string dictionary for defining custom messages that should be shown inside the notifications. The key inside the dictionary is the LCID that the value targets. For defining a catch all, the key 'default' can be used. May contain XTL placeholders in the usual ${{}} style which will be resolved. The starting record for all XTL expressions is always the target record of this event, even when using the parentLookupName property.",
"default": {},
"examples": [
{
"default": "A new mail regarding this case has been received",
"1031": "Eine neue Email bezüglich dieser Anfrage wurde empfangen"
}
],
"required": [
"default"
],
"properties": {
"default": {
"$id": "#/properties/messageConfig/properties/default",
"type": "string",
"title": "default",
"description": "A default text which should be used as catch-all when a message in the language of the user being notified is not available.",
"default": null,
"examples": [
"A new mail regarding this case has been received"
]
}
},
"additionalProperties": true
},
"emailLocaleConfig": {
"$id": "#/properties/emailLocaleConfig",
"type": "object",
"title": "emailLocaleConfig",
"description": "A string-string dictionary for defining which Xrm-Html-Templating template to use for a given LCID, or default as fallback for all not explicitly defined LCIDs. Each value has to be the unique name of an existing HTML Template. Do not define anything for using a default text.",
"default": null,
"examples": [
{
"default": "new_task_for_incident_en_us",
"1031": "new_task_for_incident_de_de"
}
],
"required": [
"default"
],
"properties": {
"default": {
"$id": "#/properties/emailLocaleConfig/properties/default",
"type": "string",
"title": "default",
"description": "Default template which should be used if no template matches the LCID of the user to be notified",
"default": null,
"examples": [
"new_task_for_incident_en_us"
]
}
},
"additionalProperties": true
},
"globalNotificationConfig": {
"$id": "#/properties/globalNotificationConfig",
"type": "object",
"title": "globalNotificationConfig",
"description": "A string-string dictionary for defining localized messages that should be displayed for users inside the global notification bar. If left out, global notifications are not shown.",
"default": null,
"examples": [
{
"default": "New tasks regarding cases have been created, click to open",
"1031": "Neue Aufgaben bezüglich Anfragen wurden erstellt, klicken Sie um diese zu öffnen"
}
],
"required": [
"default"
],
"properties": {
"default": {
"$id": "#/properties/globalNotificationConfig/properties/default",
"type": "string",
"title": "default",
"description": "A default text which should be used if no text matches the LCID of the user to be notified",
"default": null,
"examples": [
"New tasks regarding cases have been created, click to open"
]
}
},
"additionalProperties": true
}
},
"additionalProperties": true
}A plugin for notifying users when the description of a case (that they subscribed to) can be created with this unsecure configuration inside your SDK step:
{
"subscriptionLookupName": "oss_incidentid",
"notificationLookupName": "oss_incidentid",
"notifyCurrentUser": false,
"capturedFields": [ "description" ],
"messageConfig": {
"default": "This case was updated"
}
}A plugin configuration for notifying users when a new task is created regarding a case (that they subscribed to) can be created with this SDK message unsecure configuration:
{
"parentLookupName": "regardingobjectid",
"subscriptionLookupName": "oss_incidentid",
"notificationLookupName": "oss_incidentid",
"notifyCurrentUser": true,
"messageConfig": {
"default": "A new task regarding this case has been created"
}
}You might also want to only create a notification when the record matches some given criteria. You can achieve this (since v0.9.12) using a XTL expression:
{
"parentLookupName": "regardingobjectid",
"subscriptionLookupName": "oss_incidentid",
"notificationLookupName": "oss_incidentid",
"notifyCurrentUser": true,
"xtlCondition": "IsEqual(Value('directioncode'), false)",
"messageConfig": {
"default": "A new mail regarding this case has been received"
}
}Above example registered on creation of email entity only creates a notification, when the email is of direction incoming.
You might also want to create a notification with a custom message. You can use placeholders inside the messageConfig which will be resolved before creating the notifications. You can achieve this (since v0.9.12) using a XTL expression:
{
"parentLookupName": "regardingobjectid",
"subscriptionLookupName": "oss_incidentid",
"notificationLookupName": "oss_incidentid",
"notifyCurrentUser": true,
"messageConfig": {
"default": "A new mail regarding case with number ${{Value('regardingobjectid.ticketnumber')}} has been received"
}
}