Sign in

Tutorial 29: Sending a Message

figure

Result

Understand how to create a new Flow message that is sent on a periodic schedule

Tutorial steps

  1. Create a Message Channel
  2. Create a Message Definition within the message channel
  3. Create a Notification Service
  4. Link the message definition to the Notification Service
  5. Trigger the sending of a message

In this tutorial, you are going to create a new Flow message that is sent via email on a periodic schedule. Select the "Messages" tab at the top of the "Information Model" view.

Notification Services

Notification Services are the mechanisms available to send messages. These will be discussed in more detail in the following sections.

Messages

The message definition section is made up of "Message Channels" that contain one or more "Messages". By default, Flow creates a "System" Channel that contains an "Engine Status" Message.

Create a Message Channel

A Message Channel provides the following functionality:

  • Message organization similar to folders
  • Group-level channel access
  • User-level channel subscription

Right-click in the message definition section to create a new "Channel". Name it "Packaging".

Double-click the "Packaging" Channel to open its editor. The "Allow" section of the editor defines which user groups have access to receive messages defined in this channel. By default, the "Everyone" group has access to the channel. However, just because a group is given access to the channel, does not mean the users in that group are "Subscribed" to the channel.

The "Subscribed Users" section of the editor defines which users are subscribed to receive messages defined in the channel.

If you wanted to configure User Groups, you would do so in the "Users" tab at the top of the Model View. For example, you could have a group for the "Packaging" users and another for the "Utilities" users. You could then choose to only subscribe the Packaging users to the Packaging Message, by dragging the Packaging User Group from the Users tab into the "Allow" section of the message definition. Both "Windows Users" and "Message Recipient" users can subscribe to Message Channels.

Click on the Everyone group within the Allow section of the message definition, and notice that you can see a list of users that are configured in your system.

Users can be subscribed to a channel in one of the following ways:

  • Drag an individual user from the "Allow" section to the "Subscribed Users" section.
  • Drag a whole group from the "Allow" section to the "Subscribed Users" section. Note that this will subscribe all the users currently defined in that group, but will not automatically link users that are added to the group at a later stage

Drag your user from the Allow section to the "Subscribed Users" section

From the Flow Server, a signed-in user can view the Channels they have access to via their "Profile". Clicking the available channels in the "Subscriptions" section allows the user to toggle which channels they want to subscribe to.

Create a Message Definition

Now that you have a Message Channel to define group access and user subscription, let’s create a Message that publishes to that Channel.

Right-click the "Packaging" Channel and create a new Message. Name it "Packaging Daily Scorecard".

Double-click the "Packaging Daily Scorecard" Message to open its editor.

General Properties

The top section of the editor displays the general properties of the Message:

  • Description – message description.
  • Purge Age – this is the number of days that an instance of a message will be stored in the Flow System. After this time, the message will be removed. Note that this property cannot be edited.

Message Trigger

The message trigger determines when a message needs to be compiled and sent. For this tutorial, let's create a message that is sent on a daily schedule. You will create a new "Time Period Trigger" in one of the following ways:

  • Right-click in the Message Triggers section to create a new "Time Period Trigger".
  • Drag the Daily icon from the Flow Zone into the Message Triggers section.

The "Time Period Trigger" has the following properties:

  • When ("At the") – either at the start or at the end of the period, in this case "Daily" (i.e. at the end of the day)
  • Calendar – this specifies which calendar the time period is derived from. If the calendar’s day starts and ends at 07:00, then this will be the time period used for "the end of the day" trigger evaluation.
  • Refresh offset – this is the number of seconds after the "when" that Flow will attempt to compile the message contents. A default value of 300 seconds (i.e. 5 minutes) is set. If you find that some information is not being provided in the compiled messages, you may need to increase this Refresh Offset.
  • Delay sending – this is the number of seconds after the "when" that Flow will send the message. If the delay is set to the same value as the Refresh Offset, then Flow will send the message as soon as it is compiled. If "the end of the day" is 07:00, you may want to set the delay to 1800 seconds (i.e. 30 minutes) to send the message at 07:30.

Message Contents

Now that we have determined when the "Packaging Daily Scorecard" will be triggered, let’s define what the message should contain. Expand the "Message Contents" section:

You will notice that by default, Flow creates some initial message content. The message content is defined by one or more Sections, and each section can contain one or more Segments. Think of sections as a grouping of your message content.

In a message, one section can be defined as the message subject. This is displayed as the bold section. Within each section, one segment can be defined as that section’s heading. This is displayed as the bold segment.

Looking at the default content Flow has created, the section "Packaging Daily Scorecard" is set to be the subject (i.e. bold). The single segment within the section is the text "Packaging Daily Scorecard". This is the text that will be used by Flow as the subject of the message.

For clarity, let’s rename the subject section to "Subject":

Create two new sections, one named "Summary" and the other named "Dashboard":

On the "Summary" section, create a new "Constant" segment:

Notice that the new segment is set to represent the heading (i.e. bold text) of the "Summary" section. The segment's text is also set to "Summary", as derived from the section name. Edit this segment text to "Packaging Daily Summary".

Create a new "Measure Value" segment in the "Summary" section. Drag the "Total Production" measure from the Model View across to the new segment’s "Measure" textbox:

The segment's text is made up of static text and placeholders. Right-click in the segment text section to add one or more available placeholders. For this tutorial, use the simple example:

This will add the following placeholders:

[Measure]: [Value("0.00")][UOM]

When Flow evaluates this segment, the placeholders will be replaced by actual names, values, or text strings, e.g.

Filler 1 Total Production: 24607bottles

You can change the segment text as required. See the Flow Knowledgebase article What Message Content Placeholders may be used in my Message Definition? for a description of the available placeholders you can add for each segment type.

To finish our message contents, let’s add the "Packaging Dashboard" to the "Dashboard" section. First, create a Dashboard Link segment under the "Dashboard" section (right-click > New > Segment > Dashboard Link)

Then, select the "Charts" tab at the top of the Information Model, find the "Packaging Dashboard" you created earlier, and drag it onto the "Dashboard" link placeholder:

For the "Dashboard" segment, set the following properties:

  • Segment Text – this can be left blank (default). If any text or placeholder is included here, Flow will use it as a hypertext link to open the dashboard via a default browser.
  • Attachment – by default this is set to "PDF", at "Screen HD 1080" size. Flow will render the dashboard as a PDF and include it with the message contents. 

Notification Services

Now that we have defined when and what needs to be sent in our message, let’s define how Flow will send the message to the Message Channel’s subscribers.

Flow makes use of Notification Service plug-ins to send messages. Think of a Notification Service as a mechanism to deliver a message to an "external" system (e.g. an email system). For this tutorial, you will configure an Email Notification Service to deliver your message.

Expand the "Notification Services" section:

A message definition must have at least one Notification Server assigned to it. Before we can assign a Notification Server to this message, we will need to configure one.

Create an Email Notification Server

Right-click "Notification Servers" in the Messages tab of the Information Model and select New > Email:

"Smtp" stands for Simple Mail Transfer Protocol. Smtp is the internet standard for electronic mail submission.

The "Smtp Email" Notification Service requires the following properties to be set:

  • Name – set this to a name that describes the email system.
  • Server – set this to the Smtp server name. This would typically be an internal email server host name. "smtp.office365.com" is the server address for Microsoft Office 365. Similarly, "smtp.gmail.com" is the server address for Gmail.
  • Port – this is the port used by the Smtp protocol. Contact your System Administrator for details relating to your internal email server.
  • Enable SSL – specify whether Smtp server uses SSL (Secure Sockets Layer) to encrypt the submission.
  • Timeout – the amount of time in milliseconds after which a send will fail.
  • Username – email account that will be used to send the email messages. If your email server allows anonymous sending, then leave this property blank.
  • Password – password of the above account
  • Sender Display Name – the sender’s name that will be displayed to the email recipients. Some email servers will ignore this property and use the "Username" email properties.
  • Domain Mask – a mask that will only allow messages to be sent to users that have an email address that uses this domain. This property can be a comma separated list of domains. At least one domain mask must be specified.
  • Test Email – the email address that must be used when the "Test" button/option is used. This email address must be part of one of the domains that is configured in the Domain Mask field.

Configure your SMTP Email Notification Server using the values in the above picture. Remember to:

  1. Ask your instructor for the password
  2. Change the domain name to your company's domain name

Now, let's test that the configuration is correct. Select the "Test" button. 

If all is well, you should get a success message ...

You should also get an email in your mailbox ...

Select "OK" to close the "success" dialog, then select "Save". Notice that your Notification Server has a fault status - if you hover the mouse pointer over it, you'll see the reason in the tooltip "Smtp Gmail is not assigned to a platform". As is the case with Data Sources and Data Consumers, you need to assign Notification Servers to a platform and then deploy them - Flow will then run the Notification Server from the platform you deployed it to. 

Note: When you tested your Notification Server and it was successful, that's because the device that your Config Tool is running on was able to access the Notification Server. Ensure that the platform that you are deploying the Notification Server to also has access (you may have noticed this in the success message above). In corporate networks, while your PC may have access to the Internet, you will need to arrange with IT for the server where the platform is deployed to have access to the Internet!

Assign your "Smtp Gmail" Notification Server to your platform by dragging it onto the platform in the Deployment view. This will add "Smtp Gmail" to a "Notification Servers" group under the platform. Right-click "Smtp Gmail" and select "Deploy" ...

Now your Notification Server is ready for use in your message definition. Drag the "Smtp Gmail" Notification Server into the message definition:

Some Notification Servers will require additional properties to be set (e.g. email priority).

Note: A message can be delivered to more than one Notification Server.

Deploying and Testing a Message

Now that you have configured your message definition, you will need to deploy it. Click the "Deploy" button at the top of the message editor:

Once deployed, the Flow Message Engine will automatically manage the scheduling, compiling, and sending of messages.

To facilitate the testing of your message definition and Notification Services, you can manually trigger a message by right-clicking in the triggers section of a message and selecting "Trigger now":

Note: Use the Event Viewer on the platform where the Message Engine is deployed to monitor for any message processing errors.

Received Email Message

Once the Flow Message Engine has compiled and sent the test message, you should notice an email in your inbox (perhaps in Junk Email/Spam??).

Notice that the email contains the following elements that you had configured in your message definition:

  • The email subject is "Packaging Daily Scorecard", which is the Segment Text you configured in the "Subject" section
  • The body of the email has the bold text "Packaging Daily Summary" which is the Segment Text you configured in the "Summary" section. By default, this was also set as the "Section Heading" for that section (as indicated by it being in bold in your message definition). You can change the Section Heading to any segment within a section. You can even choose to have no Section Heading.
  • The Packaging Dashboard is attached as a PDF, as per the Attachment configuration in your message definition

Make a change to the Attachment settings - instead of the type being PDF, change this to Image. Also, add the Segment Text "Packaging Dashboard" to your Dashboard Link segment ...

Now, trigger the message to send again and wait for the email in your mailbox. Notice how the email layout matches the message content definition ...

You can even click on the "Packaging Dashboard" segment text at the bottom of the email to take you directly to the report.

Note: When the Message Engine is ready to send a message, it will pass the message and recipient information to the configured Notification Services. If the Notification Service is unavailable at this time, the Message Engine will not attempt to send the message again.