Send custom notifications to Canvas Guest account recipients

On this page:


Overview

When new IU Guest accounts are created via the Canvas third-party provisioning process, a generic invitation is sent to each guest to complete the account registration process. You can also send an optional custom email message to each new guest Canvas user by uploading a text file named message.properties along with your users.csv file. Your custom message will be sent to all users created with the users.csv file.

To use this feature, the email address of the message sender must be added to a database of authorized senders. To request that a new sender be added as an authorized sender, email the UITS LMS Development team at lmsreq@iu.edu.

Format the message properties file

Use a plain text editor (not a word processor like Microsoft Word) to create the message.properties file. The name of the file should be exactly as written with no file extension. Also, the file must be formatted properly or the notification will not be sent. The file consists of three key/value pairs, each on a separate line; all keys and values are required:

Key Value
sender=
(required)
A valid, authorized sender email address
subject=
(required)
Subject of the email message
body=
(required)

Body of the email message. Blank lines are not permitted and special formatting is required to insert line breaks and blank lines, as well as to indicate continuation of the message. Use the following codes to format your message:

  • \ indicates that the message continues to the next line. Use this code on otherwise empty lines to tell the message processor to treat the next line as part of the body of the message. Completely blank lines are interpreted as the end of the message.
  • \n\ inserts a line break. Use this code at the end of paragraphs or list items if you want the next paragraph or item to appear on the very next line.
  • \n\n\ inserts a blank line. Use this code at the end of paragraphs or list items if you want a blank line between paragraphs or items.

Sample message properties file and rendered message

Below is an example of a message.properties file and the resulting formatted message to be sent to recipients.

Original message.properties file

The message.properties file uses soft wrapping to wrap the text of longer lines. The only line breaks in the file occur after the \n\, \n\n\, and \ codes.

sender=tjohnson@abcu.edu
subject=Invitation to create an Indiana University Guest Account
body=\
Greetings.\n\n\
\
Today you will receive an email invitation from Indiana University to create an IU guest account. Look for the invitation in your email inbox and complete the account registration process within 30 days.\n\n\
\
This account will give you access to continuing education courses for high school teachers on a variety of topics through IU Expand, an online portal for non-credit courses offered by Indiana University (https://expand.iu.edu)\n\n\
\
You have also been pre-enrolled in the following courses:\n\n\
\
* Teaching for Student Success: An Evidence-Based Approach\n\
* Student Academic Integrity and Faculty Responsibilities\n\n\
\
Please feel free to contact me if you have any questions or concerns.\n\n\
\
Sincerely,\n\n\
\
Thomas Johnson, Professional Development Coordinator\n\
ABC University

Formatted message sent to recipients

The message.properties file above produces the following formatted message.

Subject: Invitation to create an Indiana University Guest Account

Greetings.

Today you will receive an email invitation from Indiana University to create an IU guest account. Look for the invitation in your email inbox and complete the account registration process within 30 days.

This account will give you access to continuing education courses for high school teachers on a variety of topics through IU Expand, an online portal for non-credit courses offered by Indiana University (https://expand.iu.edu)

You have also been pre-enrolled in the following courses:

* Teaching for Student Success: An Evidence-Based Approach
* Student Academic Integrity and Faculty Responsibilities

Please feel free to contact me if you have any questions or concerns.

Sincerely,

Thomas Johnson, Professional Development Coordinator
ABC University

Preview your message before you send

It's a good idea to review a copy of your message to ensure the formatting and content are correct before you upload the message.properties and users.csv files to the secure FTP server. To receive an exact copy of the message that will be sent to each user in the users.csv file, follow the instructions below. These instructions guide you through the process of making a call to a locally developed API with Insomnia, a freely available, cross-platform REST client. You can use a different REST client if you prefer.

Note:
You must be listed in our database as an authorized sender before you can initiate a request for a preview message; to request addition to the database, email the UITS LMS Development team at lmsreq@iu.edu.
  1. If you have not done so already, download and install Insomnia on your local device.
  2. Open Insomnia. You should see three panels. The one on the left is for creating and organizing API requests. The middle panel is for configuring individual requests, and the panel at the right is for viewing the results of an executed request.
  3. In the left panel (also called the sidebar), click + (the plus sign), and then select New Request from the drop-down menu:
    New request button and drop-down
  4. In the "New Request" pop-up window:
    1. Enter a name for your new request.
    2. Change the request type from GET to POST.
    3. Using the No Body drop-down menu, set the body type to Multipart Form.
    4. Click Create.
      New request pop-up window

    Your new request will appear in the left panel below the "Filter" box:

    List of new requests
  5. If your new request is not already selected, select it. Then, click the first tab in the middle panel; this tab is for defining the body of the request. It should already be set to Multipart Form (if you selected that option in step 4 above):
    Blank multipart form request
  6. Add two fields to the form by filling in the name/value pairs as described below:
    1. In the first "name" box, enter department in all lowercase. Then, in the "value" box, enter the abbreviation of the department for which you have been authorized (for example, IUSM, IUSO, ELA, etc.).
    2. In the second "name" box, enter messagePropertiesFile with capitalization exactly as shown. Then, to the right of the "value" box, click the downward-pointing arrow. This will change the field type to a file upload.
      Multipart form
  7. In the form, click Choose File and select the message.properties file on your local or cloud storage device.
  8. In the middle panel, click the Header tab. This tab should already be populated as a result of your previous selections. If it isn't, in the "New Header" box, enter Content-Type, and in the "New Value" box, enter multipart/form-data.
    Populated header tab
  9. At the top of the middle panel, in the box for the request URL, enter or paste the following URL:
    https://canvas.iu.edu/lms-prd/v1/dept_message_tester/validate
  10. Click Send to initiate the request. If your request was successful, a copy of the message will be sent to the sender listed in the message.properties file, and you'll see "test email sent" in the Insomnia results panel on the right:
    Results panel showing test email sent

    If there was a problem with the message.properties file, you will see an error message in the results panel and the preview email will not be sent. Fix the problem, attach the revised file, and try again.

This is document baks in the Knowledge Base.
Last modified on 2023-11-28 12:09:40.