Entity notification workflow

Entity notification workflow is a plug-in for Microsoft Dynamics CRM and Resco Cloud environment. It allows administrators to configure automatic notifications that are triggered by specific entity record creation/modification.

This plug-in sends the push notification to specified users (or more exactly to mobile devices used by target users). Once the user clicks on these notifications, the Mobile CRM app opens and displays the created or modified entity record form. If the app is in offline mode and it doesn't have that record yet, it will ask user to switch to online mode or to synchronize the data.

In addition to this functionality, admin can configure the notification category which defines a set of actions that can be done on the entity record immediately as it opens (for example Sign quote).

Dynamics configuration

The entity notification workflow is a part of Woodford solution and it's installed when an administrator connects Woodford to the Dynamics CRM organization. It uses the standard process configuration in Dynamics.

1. In Dynamics, go to Settings > Process Center > Processes and click New.
2. Enter a process name and as Category select Workflow.
3. Select the entity that should produce notifications, for example Quote, then click OK.
4. Specify events that should trigger the workflow and add the step Resco MobileCRM > Send Entity Notification.
5. Click Set Properties and enter the notification text and target user definition.
   • Message property specifies the text that has to be shown in the notification. Special tag {entity} will be replaced by entity’s primary field value.
   • Category property optionally defines the category with a set of buttons that have to appear in the notification (see below).
   • User property defines a specific user that needs to receive the notification.
   • If User property is empty, the Team property can define the team which will obtain the notification.
   • If both User and Team properties are empty, the property UserLink can contain the logical field name of initiating entity which contains a lookup to user or team that needs to be notified. In our example, the notification is sent to the owner of initiating Quote, defined by ownerid field.
     Alternatively, the UserLink property can contain the XML with fetch request returning a set of users that have to be notified.
   • CustomTarget is an optional parameter.
     • null or empty - standard entity notification is sent. It opens entity form with record which initiated workflow (process).
     • Home:[HomeItemName] - notification opens home item, e.g. Home:account;Account List opens home account list with specified view, or Home:@Dashboard; opens the Dashboard.

       If your entity has exactly one view, use Home:entity;*.
       If your entity has more than one views, use Home:entity;viewname.

     • JSBridge:[Arguments] - invokes Javascript method "handleLaunch" on global iFrame. In addition to specified arguments, it passes also notification button action. So the "handleLaunch method will object JS object in form {args:"Arguments", btnAction:"ButtonName"}

Resco Cloud configuration

In case of Resco Cloud, entity notifications can be configured via the Admin Console.

1. Select Processes Center > Processes from the menu.
2. Click New to create a new process.
3. Select an entity, select Workflow as the Category, and select the conditions that should trigger the workflow.
4. Click Step and select Function, then enter the following details Server.Execute.Plugin.RescoCRM.Notifications.SendEntityNotification .
5. Specify additional workflow parameters:
   • Message parameter specifies the text that has to be shown in notification. Special tag {entity} will be replace by entity’s primary field value.
   • Category parameter optionally defines the category with a set of buttons that has to appear in the notification (see below).
   • User property defines specific user or team that has to receive the notification.
   • If User parameter is empty (or contains null lookup variable), the property UserLink can contains the logical field name of initiating entity which contains a lookup to user or team that has to be notified. In our sample, the notification is sent to owner of initiating Quote, defined by ownerid field.
     Alternatively, the UserLink property can contain the XML with fetch request returning a set of Users that has to be notified.
   • CustomTarget is an optional parameter.
     • null or empty - standard entity notification is sent. It opens entity form with record which initiated workflow (process).
     • Home:[HomeItemName] - notification opens home item, e.g. Home:account;Account List opens home account list with specified view, or Home:@Dashboard; opens the Dashboard.

       If your entity has exactly one view, use Home:entity;*.
       If your entity has more than one views, use Home:entity;viewname.

     • JSBridge:[Arguments] - invokes Javascript method "handleLaunch" on global iFrame. In addition to specified arguments, it passes also notification button action. So the "handleLaunch method will object JS object in form {args:"Arguments", btnAction:"ButtonName"}
6. Click Save, then click Publish or Activate to launch the process.

Defining notification categories with button actions

As mentioned above, the notification definition can contain a category defining a set of buttons that have to be shown in notification and perform specific actions (for example, sign a quote).

Mobile CRM has several pre-defined push notification categories: AcceptReject, ApproveDeny, OKCancel and ViewRecord.

A custom category can be defined in Woodford Localization section by defining strings Push.[category].. In our case, we have to define the string Push.SignQuote.Sign.

When the notification is displayed by the client app, it takes current localization and displays all Push.SignQuote.XY texts as buttons below the notification text. In case of iOS, the notification has to be swiped left to uncover the buttons. There’s a limit on number of buttons on iOS – it can show at most two buttons. It's not possible to show buttons for Windows Store app.

Handling notification buttons on entity form

When a user taps the Entity Notification button, the Mobile CRM application starts and it opens the initiating record form. It doesn’t perform any further action by default. However, it passes the name of pressed button into iFrameOptions object to all Offline HTML iFrames included on the entity form.

To handle the notification button action, you have to include following JavaScript code into you Offline HTML iFrame:

MobileCRM.UI.EntityForm.requestObject(function(entityForm){
	///var options=entityForm.iFrameOptions;
	if(options && options.btnAction == "Sign") {
		//Perform signing action
	}
});

Example with JSBridge

The following procedure lists the main steps for adding notifications to your project.

1. Define an entity notification when an Opportunity record is created on the backend server (Dynamics/Resco Cloud). As Custom Target, use:

   JSBridge:{"initEntity":"{entity}","type":"opptcreate"}

2. Using Woodford, add the following files to your Offline HTML:
   • JSBridge.js (get the latest version from GitHub)
   • iFrame.html (create the following sample file)

   <!DOCTYPE html>
   <html lang="en" xmlns="http://www.w3.org/1999/xhtml">
   <head>
   	<meta charset="utf-8" />
   	<meta http-equiv="X-UA-Compatible" content="IE=edge" />
   	<meta name="viewport" id="view" content="initial-scale=1, minimum-scale=1, maximum-scale=1, user-scalable=no" />
   	<script src="JSBridge.js"></script>
   </head>
   <body>
   <script>
   function handleLaunch(data) {
   	var json = JSON.parse(data);
   	var args = JSON.parse(json.args);
   	if(args.type == "opptcreate") {
   		var action = data.btnAction;
   		MobileCRM.bridge.alert("entity:" + args.initEntity + "\naction:" + json.btnAction);
   	}
   }
   </script>
   </body>
   </html>
   

3. In Woodford, edit the home screen and click Special IFrame and link to the iFrame.html file. As Type, use Global hidden iframe.
4. Save and publish the app project.
5. Synchronize your app and restart it to activate the global iframe.
6. Create a new opportunity on the backend server.
7. Soon, you should see a notification on your device. Click it to bring the app to foreground. It should display a message entity reference and optional notification button name.

Known issues

• External user projects are not supported.
• Windows 10 app has limited support for the notification category (buttons):
  • The notification category must be in form: Button 1|Button 2.
  • Button texts can't be localized.
    • If you want to support all platforms, use notification categories in above form and localize button text (so in above sample, you have to localize string "Push.Button 1|Button 2.Button 1" and string "Push.Button 1|Button 2.Button 2").
  • Win10 notification loses action button info if a notification button is clicked and the app is not running.
• Android notification isn't dismissed when the notification button is clicked.
• UserLink supports teams as owners but it doesn’t take users from child teams (when another team is member of our team).

Troubleshooting

If the notification is not sent:

• Make sure that the process is activated in Dynamics (in Settings/Processes)
• Make sure that workflow was created (open the process and make sure that new workflow appears when the event occurs). If it didn’t, open Settings/System Jobs and check whether the workflow isn’t pending (reports „In progress“ state).

Technical details

Sending notifications requires that the CRM server can connect to iservices.resco.net.

The notifications are then authenticated using the app's private keys (stored on Resco servers) and immediately sent out using platform-dependent notification services (Apple APNS, Google Firebase, and Windows WNS).