Communication

Overview

The Communication module supports sending outbound email and SMS messages to various types of recipients within an event. Message recipients can be drawn from record types containing relevant contact address data. These record types currently include contacts, recovery cases, case applicants, relief registration contacts, permit applicants and more, depending on the Crisisworks configuration.

The main record of the module is the Communication, which can range from a simple, one-off email to a single recipient, to a multi-channel, ‘campaign’ style message to hundreds of recipients. An example of where the second style of message can be used is the Relief Registrations module, which supports sending bulk Communications to Relief Registration Contacts.

Additionally, Communications can be automatically generated as a part of the workflow of another register. For example, the Permits module supports sending a Communication email message to approved applicants as part of its workflow.

There are two supporting record types in the Communication module. These are the Comms Recipient Address, which manages the address data for recipient emails and phone numbers, and the Comms Inline Recipient, which is a simple record type that supports sending messages to email addresses and phone numbers that do not exist elsewhere in Crisisworks.

Workflow

Each Communication Message follows the below workflow.

Open

Adding new Communications

To create a new, standalone Communication, follow these steps.

From any application view, select New Communication from the new item menu.

Open

Topic

Specify a topic for the new message. This is used to identify and distinguish the message from others in the event, and is the primary column in the data-grid view of Communication records. Complex events may end up with many Communication records, so it’s a good idea to specify a distinctive topic.

Formats & Recipients

Select the formats for the message. Currently email and SMS messages are supported, and at least one format must be selected. Selecting a format will control which recipient address types are selected for delivery, and will toggle the display of relevant form fields for each message type.

Next, choose one or more recipients for the message. To select a recipient, begin by typing some matching data to filter the list and locate the desired recipient. Usually this will be the full or partial ‘display name’ of the original recipient record, however a full or partial email address or phone number will also match recipients. When recipients are selected, they should appear in the Delivery Report table as pending deliveries if they have selected to receive communication in the format chosen (see Receive Communication Settings and Overriding preference below for more information).

For recipients that don’t exist in Crisisworks, any valid email address or phone number can be entered in the recipient list. In this case, an Inline Recipient record is automatically created at the time the message is sent. The data-grid for these records can be found in the Administration menu.

This screencast demonstrates how the recipient selector can be used:

Once the list of recipients has been populated, the message content for each selected format should be completed.

Adding Event Positions as Recipients

It is also possible to send a message to all users within an event’s participating position. This performs a live lookup and adds users that are currently on-duty in that position for the event. The users who are on-duty in the position will appear in the delivery preview (if they have selected to receive email or receive sms in their contact record). In the example screenshot, we have added the Red Cross EMLO as a recipient. The two contacts ‘Jen Haase’ and ‘Redcross Hundt’ are currently on-duty for this position in the Zombie invasion event. You can see these two contacts have been automatically added as recipients in the delivery preview.

Sending to Custom Recipient Groups

Some custom recipient groups have been created to allow you to easily target groups of multiple recipients.

The following custom recipient groups have been created in your default setup:

“All On-Duty In Current Event”
Add this recipient group to the Recipients box, choose a communication format and this will automatically populate the Delivery Preview area with all on-duty users in the current event. If you want to force send to these users regardless of their communication preferences then click the Override communication preferences checkbox (see below for further information on how this works)

“Contacts Internal Distribution” & “Contacts External Distribution”

You can mark a contact to be part of the “Contacts Internal Distribution” or “Contacts External Distribution” group by editing the contact and choosing one of these options in the Classification select box (see below).

Add the Contacts Internal Distribution or Contacts External Distribution group to the Recipients box and any contacts that have been saved with this classification will automatically be added to the Delivery Preview. If you want to force send to these users regardless of their communication preferences then click the Override communication preferences checkbox (see below for further information on how this works).

Receive Communication Settings & Overriding preferences

For existing Contact recipients, the Communication Message will comply with their “receive communication preferences” set in their contact record (see below). If a contact has selected to not receive communication by email and they are selected as a recipient to be sent to via email, the contact will not appear in the delivery preview section meaning they will not be sent to for this format. To override their preferences and send to this contact via this format anyway, there is an “Override communication preferences” checkbox that can be ticked which will ignore the contact’s preferences . This override feature should only be used in rare circumstances for emergencies and other important messages.

To override their preferences and send to this contact via this format anyway, there is an “Override communication preferences” checkbox that can be ticked which will ignore the contact’s preferences . This override feature should only be used in rare circumstances for emergencies and other important messages.

Email

Specify a Subject for the email. This is mandatory and can be the same as the message topic, if appropriate. If the subject field is empty, clicking the ‘Copy from Topic’ button will populate it with text from the Topic field.

Compose the Body text of the message using the rich text editor and optionally upload any files to the Attachment field. These will be attached to each email that is delivered.

‘Enable template variables in email body’ is a beta feature which allows recipient properties, such as ‘display name’, to be substituted in the email body via predefined placeholder ‘variables’ that are specific to the recipient. Using this feature, the message content can be customised per recipient, for example by substituting recipients’ names in the opening greeting.

SMS

Specify a mandatory message for the SMS. If the message field is empty, clicking the ‘Copy from Topic’ button will populate it with text from the topic field.

‘Enable template variables in SMS’ is a beta feature which allows recipient properties, such as ‘display name’, to be substituted in the SMS via predefined placeholder ‘variables’. Using this feature, the message content can be customised per recipient.

To help identify long messages, Crisisworks displays a warning with an estimate of the number of message parts needed.

Support for long SMS messages and message parts

If your message is longer than the size of a single SMS, the message will be split into multiple parts by the telecommunication provider.

Each message part is charged a separate message, even though modern phones recombine them to display the single, long message to the recipient. This behaviour is due to technical limitations with SMS technology itself.

The single message limit for SMS is typically 160 ASCII characters, but this can be as low as 70 characters if any extended characters such as symbols, emojis or other unicode characters are used.

The full message includes additional text beyond the ‘message’ field

SMS messages generated from this module can contain more characters than your main message entered into the message box, based on other options you select.

• By selecting a priority other than “normal”, a unicode symbol is prefixed to the message

• By selecting an acknowledgement, additional text is added to instruct the user how to acknowledge, and a short link is also added into the message.

• A footer text can be configured based on your site to sign off each message, e.g. “Sent from Your Organisation”

Special characters and unicode

A single message containing only standard English characters (ASCII) can be 160 characters long.

If the message contains any unicode characters such as emojis (🍕), symbols (♹) or non-English or accented characters (á), the initial message size reduces to only 70 characters.

Once the message exceeds the single message limit, it is split into parts.

Message part and size estimation

Messages longer than supported in a single message are split into multiple parts, which are sent separately by the network and re-combined by the end user. Users do not see this, however it has an impact on costs. Additionally, telecommunication infrastructure has an upper capacity of 5 message parts per message.

Crisisworks estimates the message parts for you if it is larger than one message long and warns you if the message is likely to exceed more than one message.

Billing

SMSs are billed per message part. This means the total billing for an SMS Communication is:

cost = [cost per SMS] x [number of message parts] x [number of recipients]

Example: at 8.5c per SMS with 35 recipients and 3 message parts estimated by Crisisworks, the total cost will be $0.085 x 35 x 3 = $78.93

Sending

Status

For a Communication record, the workflow status is used to control message sending.

If the message is still a work-in-progress, leave it in the default ‘Save as Draft’ state and save. The message contents, recipients and other settings can be adjusted until it is ready to send.

To schedule the message to be sent at a later time, select ‘Send Later’ and then specify the date and time to send in the ‘Time to Send’ field that is revealed.

To queue the message for immediate sending, select ‘Send Now’. Crisisworks will then attempt to deliver one message to each of the recipient addresses listed in the Delivery Report table.

Once the deliveries have been dispatched, the Communication is moved into another workflow state. This is explained in the documentation on message delivery.

If the message is no longer needed, select ‘Cancelled’. If needed at a later time, it can be transitioned back to draft status.

Priority

A priority can optionally be selected for the Communication.

Adding a priority distinguishes delivered messages visually—email subject lines and SMS messages are prepended with the symbol depicted next to the priority option.

For email deliveries, the dispatched email is also assigned a priority ‘header’ matching the priority specified, however it should be noted that many email clients no longer honour this header.

In addition to visually changing delivered messages, assigning a priority also distinguishes the Communication record from others in search filters and data-grid lists.

Options

There are optional message settings which control how recipients may provide feedback.

The ‘Include opt-out’ option includes a link for recipients to opt-out of receiving future messages at a specific address. If a recipient selects an opt-out link in a message they have received, the address associated with that message is added to a global opt-out suppression list. The address will be displayed with a ‘struck out’ red style in delivery reports, and future messages won’t be delivered to the address. Addresses can be opted back in by removing the suppression list setting. See the documentation on managing addresses for instructions on how to do this.

The ‘Ask recipients to acknowledge the message’ option includes a ‘Click to Acknowledge’ link for recipients to flag that the message has been received and understood.

Selecting the option ‘Ask recipients to respond to one or a pair of options’ is similar to the ‘acknowledge’ option, but presents up to two choices for recipients to select from. There is an additional setting which supports tagging the original recipient record based on their response. Selecting this tag setting reveals another field for specifying a prefix to apply to the tags when they are applied.

If a recipient selects the response link in a message they have received, the options are presented for them to choose from.

The chosen response is recorded against the associated delivery report record, and if the tag option was selected the original recipient record is also tagged.

Classification

As with other record types, Communication records can be tagged and assigned to open events that support this record type.

Administration

Communication messages that are frequently used can be saved as templates. Select the option, and specify a name for the template.

Once saved, the template record can be copied from the Communication data-grid or selected from the bulk recipient selection wizard when creating a new message. In the latter case, all field values from the template are preserved when a new message is created, except for the recipient list, which is updated with the bulk-selected recipients, and the status, which is set to draft.

Example Message

Below is an example of a delivered email, with high priority and the ‘request acknowledgement’ option selected.

Message Delivery

Once a Communication record’s deliveries have been dispatched successfully, it is moved into the ‘Sent’ workflow state. If none of the deliveries are successful at the time of dispatch, it is moved into the ’Failed’ workflow state and if some are successful and others not, it is moved into the ’Partially Failed’ state.

Following the initial dispatch, the status of individual delivery records may be updated, either by messaging provider ‘delivery events’ or by user ‘feedback events’, which are explained below. Following the initial dispatch, these status updates to the delivery records don’t affect the status of the parent Communication record.

Delivery Events

Events that occur in the delivery of a message are reflected in the status of the delivery record.

Feedback Events

User events that occur in the delivery of a message are also reflected in the status of the delivery record.

Direct Replies

If a recipient replies directly to the email this is are not automatically handled by the system and there is currently no report or status for this. These replies don’t go anywhere by default and you may not receive them.

We recommend the following workarounds:

• A general DO NOT REPLY policy for outgoing messages 

• For email:

  • A reply-to email address can be set up so that any direct replies can be forwarded there. To set this up, please make a request to the Crisisworks Help Desk. 

  • A footer message can be configured for your Crisisworks system for email messages. For assistance with this contact the Crisisworks Help Desk.

• For SMS:

  • manually include a Do not Reply message (note this may take up some of the message quota)

Delivery Report

Once a Communication has been sent, the Delivery Report displays the current status of each delivery record. These statuses may change as delivery and user feedback events occur, so the report can be refreshed by clicking the ‘refresh’ icon at the top-right of the field.

For some statuses, hovering over the status lozenge can reveal further information about the underlying event. In the case below, the delivery bounced due to the email address being invalid.

Copy Recipient CQL

Underneath the Delivery Report is a link called “Copy Recipient CQL” (see screenshot below).

To display further links so you can choose what CQL you would like to copy, click on the Copy Recipient CQL link. This will display additional links to the right of the Copy Recipient CQL link (see screenshot below).

CQL is the Crisisworks query language which uses advanced word/text searches that supports sophisticated searching and filtering of its data, beyond what is supported by the standard field filters.

This feature allows you to click on the appropriate link (ie Read ,Failed, Delivered etc) and copy the CQL so you can paste this search term into the appropriate register’s search area.

You have the option of copying the search term to find recipients where the message status is Sent, Failed, Delivered, Read, Acknowledged or Responded.

If your message included response questions, you will also have the option of copying the search term to find which recipients responded with Response 1 or Response 2.

For example, you may have sent a Communication message with the ID of 53605 that contained a question with the Response 1 of “I can make it” and the Response 2 of “I can’t make it”. You may then wish to find all recipients for this message that responded with “I can make it” so you can send them a follow up communication.

To do this, click on the “Response 1” link. You will see a blue Information pop-up at the bottom of the page if you have copied this correctly (see screenshot below)

This will copy the following CQL to your clipboard.

For the Delivery Report screenshot above, the Type for both recipients is “Contact”. Therefore you should click on the Contacts register and perform the following steps:

1. Click on the Magnifying Glass to the right of the Contacts heading on the left hand sidebar

2. In the Search text box that is displayed, place your cursor in the box and copy the contents of the Clipboard (For Windows users Ctrl-V, for Mac users Command-V) and click the green “Apply” button to perform the search. This will re-load the Contacts datagrid with the search results.

3. You can then select all of the items currently displayed in the datagrid by clicking on the yellow tick that appears next to the ID heading. This will select all items displayed.

    

4. You can now click on the Send Communication button at the bottom of the datagrid. Choose Add to New Communication to create a new communication message. This will automatically populate the recipients with the Contacts that were selected in the Datagrid.

Managing recipient addresses

‘Blacklisted’ addresses

If a message delivery bounces, a recipient opts out of receiving messages, or marks a message as spam, the recipient address or phone number is placed into a suppression ‘blacklist’, and no further messages will be delivered to the address unless this status is changed.

If the message has bounced due to an incorrect address, correct this in the source recipient record. The updated address has an associated record in the Administration menu; once the corrected address is reflected in this related address record, it can be removed from the email bounce list. Go to the Comms Recipient Addresses register in the ‘Administration’ menu.

Find the address record in the relevant ‘Blacklisted’ counter.

Change the value of Blacklisted to ‘None’.

Finally save the address record. New messages can now be sent to the address.

Creating or updating Communications with bulk recipients

Communication messages can be created from the data-grid view of record types that have been configured as recipients. For an example of this, see Sending Bulk Communications to Relief Registration Contacts.

Depending on the Crisisworks configuration, similar steps may be followed for sending messages to selected groups of Contacts, Recovery Cases and Recovery Contacts.

To send a message to bulk recipients, filter and select the recipients via the relevant data-grid, then select the ‘Send Communication’ bulk action button. Recipients can be added to an existing Communication, or a new one.

When adding recipients to an existing Communication, current messages in draft or ‘resend' state can be selected from the ‘Select Existing Message’ option. When creating a new message, recipients can be added to an empty message or a predefined Communication template using the ‘Select Template’ option. Further options for overriding the template’s Topic and Format fields can also be selected.

Upon submission, the updated or created Communication can be opened and modified as necessary.

New messages will be saved in draft state, regardless of the status of any template that may have been used. On the contrary, existing messages will retain their existing status when updated.

Viewing the data-grid

To view the list of Communication records accessible in current events, select the Communications option from the Operations Menu, or from the left-hand panel on the Dashboard.

The data-grid list view includes the Communication status, priority, topic, recipients list, scheduled time to send and the date recorded.

From this view, Communication records can be copied or bulk-edited to update their status.

Counters

Data-grid counters list Communication records based on their current status, or by tag.

Technical Reference

Schema

Communication register

A register for communication records.

Outbound schema

Non-schema fields

Workflow