Assignment Notification Customization and Standalone Notifications

When the new approval mechanism was introduced in SP4 we also added a new notification script. This was designed to be fairly flexible and usable for other notifications as well so you can use it in your workflows to send notifications about anything. I will do two things in this blog

1) Add additional/custom replacement strings to existing template

2) Use the Assignment Notification task to send a message as part of a regular (non-assignment) workflow

Common steps

Importing the Assignment Notification task and Notification Templates job folder

Start by importing the job folder and task and configuring the notification repository as outlined in the documentation. This is the quick version:

The templates are located in “\usr\sap\IdM\Identity Center\Templates\Identity Center\Provisioning\Notifications“

Right click on a provisioning group of your choice (or create a new one like I did with “Notification blog thingy”) and import Assignment Notification_Task.mcc	Right click on a job folder of your choice or the top node (I used the default Job Folder) and import Notification Templates_jobFolder.mcc

The first thing to do is check if you need to fix a mistake we did. The Assignment Notification task was not made public in the template provided with some versions. So open the task and verify that Public is checked, and if not, check it and save:

If this is not done any attempts to start this task using uProvision will be rejected.

Configure the notification repository values

You also need a notification repository with these values set:

Import the standard notification templates

Next we need to update the templates in the database, so run the job named Import notification templates and verify there are no errors.

Create a basic approval workflow

Ordered task   Action with a To Identity Store pass   Approval Task
To Identity Store pass in Add approvers to PVO
Configure the approval task – use the PVO to get approvers (MX_APPROVERS attribute). – use the Assignment notification task as the … notification task. – use the Approval Initial Notification template as the initial message.

Create a test privilege

The privilege for this does not need anything more than a name and pointing the Validate Add task to the Assignment Approval Workflow that we created

Creating users and repeatedly testing

It’s very useful to create a small job that just creates a new user and perform a few test operations on it, and this sample can be used in a multitude of scenarios. In this job I have two very simple passes. The first just sets an email address on the user I’ve decided to use as an approver:

The next pass creates a new user prefixed with the %ddm.job% constant which is a counter that increases every time the job is run.

This means that every time I run this job a user with the name USER.TEST.BLOGNOTIFICATION.<number> will be created and assigned the privilege that has the approval  task, and I can rerun this and test the approval process with new users as many times as I need until I get all the bugs sorted out of my configuration.

At this point you should be able to run the job and get a notification in your mailbox when the assignment hits the approval task, more or less like this one if you’re using the same release as me. Not perfect, but enough for this purpose:

End of Common

Customizing existing message with new strings

This is a fairly simple operation and I will use the Initial Approval Notification sent to approvers to demonstrate this. The notification script looks at the context variables for most of its data. All the template files use a syntax of PAR_<VARIABLENAME> for text replacement strings. These are passed to the notification script as context variables named MSG_PAR_<VARIABLENAME>. This means that to add a new value all you have to do is

1) Add the new string replacement variable to the template file

2) Add the context variable using the uSetContextVar function

Editing the template

Locate the file AssignmentRequestApprovalinitialnotification_EN.html in \usr\sap\IdM\Identity Center\Templates\Identity Center\Provisioning\Notifications. Open it in a UTF-8 compatible editor and start editing. For this example I’ve modified the end of the file and added PAR_QOTD where the copyright notice used to be, and inserted a shoppinglist reminder above the URL:

Next we need to update the templates in the database, so run the job named Import notification templates as outlined in the common section

Setting the additional variables in the workflow

First we need an Assignment Approval workflow, again I keep most of this short and simple, it’s well documented in tutorials etc. and focus on the new part, Add custom message variables. The basic layout of the task is described in the Common section.

Insert a new action with a To Generic pass after the Add approvers to PVO action
Add custom message variables is a To Generic pass with a fairly simple entry script listed below. This simply takes the array and splits it first on !!, then writes each %1=%2 combination as an audit variable named #MSG_%1 with value %2. See the Additional Data section to see how it actually looks in the table

// Main function: setCTXVARS
function setCTXVARS(Par){
  tmp = Par.get("MSGVARS");
  ctxVars = uSplitString(tmp,"!!");
  for (ctxvar = ctxVars.iterator(); ctxvar.hasNext();dummy=1)
  {
  tmp = ctxvar.next();
  vals = tmp.split("=");
  ctxVarToSet = "#MSG_"+vals[0];
  ctxValToSet = vals[1];
  OutString = uSetContextVar(ctxVarToSet, ctxValToSet);
  }
}

The QOTD script returns a random string. I’ll attach it to the end of the blog for the curious.

With the templates up to date in the system it’s time to test, and to do that we just run the testjob from the common section again. My result, red outlines around the changes are added by me:

End of Customizing existing message with new strings!

Sending custom messages

This is a bit more complex. First we need to create a new template. The default location for the template files is

\usr\sap\IdM\Identity Center\Templates\Identity Center\Provisioning\Notifications

Creating a new template

Make sure you use a text editor that can save the file as UTF-8 without BOM (Byte Order Mark, gives two garbage chars at the beginning of the message if included) when performing the next steps.

We’re creating a new message template text file named MyCustomMessage_EN.html with the following content:

<html>

<meta http-equiv=”Content-Type” content=”text/html; charset=UTF-8″>

<head>

</head>

<body>

<p>Something PAR_DESCRIPTION has happened!</p>

</body>

</html>

Next we need to add a row describing this template to the index file, AssignmentNotificationsList.txt:

Here’s the text for those who like things easy.

Custom Workflow Message;EN;999;Its custom;Message for you sir;CHARENC=UTF8;MyCustomMessage_EN.html;CUSTOM

Importing the template

Next we need to get this template into the mc_templates table. This is what the Import Notification Templates job we imported earlier does. Run it and check the log. There should be no warnings or errors. You can also verify the database contents using this query

select * from mc_templates where mcClass = 'CUSTOM'

The result should be something like this:

Starting the notification from a workflow

Now we’re ready to trigger the notification. It requires some fixed values to be set to work, and these are:

#MSG_TEMPLATE     Should match the name we used: Custom Workflow Message

#MSG_TYPE              Should match the message class used: CUSTOM

#MSG_RECIPIENTS   Is the MSKEY of the user message recipient

#MSG_PAR_<variables> Whatever else we feel like saying

I already made a script that sets a range of context variables earlier so I reuse it with a small modification in the script. This can be part of pretty much any workflow, you decide where it makes sense to you. My test task works as a UI task and when started using test provisioning and should give you some ideas on how to use it, nothing more:

// Main function: setCTXVARS
function setCTXVARS(Par){
  tmp = Par.get("MSGVARS");
  ctxVars = uSplitString(tmp,"!!");
  for (ctxvar = ctxVars.iterator(); ctxvar.hasNext();dummy=1)
  {
  tmp = ctxvar.next();
  uInfo(tmp);
  vals = tmp.split("=");
  ctxVarToSet = "#MSG_"+vals[0];
  ctxValToSet = vals[1];
  OutString = uSetContextVar(ctxVarToSet, ctxValToSet);
  }
  mskey = Par.get("MSKEY");
  taskid = Par.get("NOTIFICATIONTASKID");
  AuditID = uGetAuditID();
  OutString = uProvision(mskey ,taskid ,AuditID, 0, "does this work?",0);
}

The key change is that in addition to set the #MSG_ context variables it also calls the Notification task. This is brute force hard-coded taskid in the action, no error checking and not pretty code. So go forth and improve it.

Anyway, the result in my case was a very simple but satisfying email in my inbox:

And thats it.

Additional data

What does all this context variable look like anyway

At the time when the Assignment Notification action runs the mc_audit_variables table can look like this:

And for the custom notification:

Quote of the Day script

, not well designed or thought out but for this sample it does what it needs to

// Main function: qotd
function qotd(Par){
  qn = Math.floor((Math.random()*5)+1);
  if (qn == 1) {
  return "A day without sunshine is like, night";
  } else
  if (qn == 2) {
  return "A penny saved is a government oversight";
  } else
  if (qn == 3) {
  return "When everything comes your way you're in the wrong lane";
  } else
  if (qn == 4) {
  return "Silence is golden, duct tape is silver";
  } else
  if (qn == 5) {
  return "The road to success is always under construction";
  }
  return "You should not be here?! No quote for you!";
}