[Insert State Logo]
Editing Email Notification Text
and Custom Text on BCS Pages
State Administrator User Guide
Version 01
3/9/2015
Introduction
The Background Check System (BCS) allows administrative users to edit the text in automated email notifications, as well as customize the text on certain system pages through a feature called Edit Templates.
The BCS currently contains approximately 50 automated email notifications and 30 pages with customizable text. Additional emails and customizable pages are routinely added to the system. Based on the configuration of your state’s BCS, your state may or may not utilize all of the emails and/or customizable pages that are listed on the Edit Templates screen.
Assigning Permission to Edit Email Notification and Custom Page Text
Before you can edit email notification text or customizable page text, your user role must have the appropriate permissions setup.
Hover over Admin on the navigation bar and determine if Edit Templates displays in the dropdown list of secondary navigation options.
If Edit Templates displays, then your user role has the permission needed. If it does not, the user role assigned to your user account must have the permission added by the person in your organization that manages user accounts. This person may be you or someone else.
To add the Edit Templates permission to a user role:
- Go to Admin > Roles on the navigation bar. The User Role page displays. Click Edit next to the user role you wish to edit. The Edit Permissions screen will display.
- On the Edit Permission page, scroll to the bottom of the permissions list and check the box next to Edit Templates. Click Save.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
· When you add the permission to Edit Templates to a user role, all user accounts that have this user role assigned will receive the ability to Edit Templates.
· If you are updating your own user role, you must log out and back into the BCS for the permission change to take effect.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Searching for Editable Emails and Customizable Page Text
- Go to: Admin > Edit Templates. The Notifications: Edit Templates page displays.
- Select either "Notification" or "Custom Page Text" from the Template Type dropdown.
· When the Edit Templates page initially displays, “Notification” will already be selected. The Email Templates table will list all notification templates in the BCS that can be edited. You can search this list for specific email templates in the following three ways:
1) Notification Type: This dropdown lists each email notification available in the BCS. Select the notification email you want to edit (e.g., “Password Reset”) and click Search. The templates associated with the “Password Reset” email notification will appear in the Email Templates table.
2) Text String Type: This field allows you to search for email templates by entering a keyword that is found in the Text String Type of the template. This is helpful when you don't know exactly which email you need to edit, but you know the email has to do with (for example) determinations. Entering the keyword "determination" and clicking Search will return all email templates that have this keyword in the Text String Type column of the Email Templates table.
3) Text: More generally, entering the word "determination" as a keyword in the Text field and clicking Search will return all email templates with the word "determination" in the subject, message header, message record, or message footer of the email, as shown in the Text column of the Email Templates table.
· Selecting "Custom Page Text" from the Template Type dropdown and clicking Search will populate the Email Templates table with a list of all BCS screens that have customizable text. You can search this list for specific BCS screens with customizable text in the following two ways:
1) Text String Type: Entering a keyword into the Text String Type field and clicking Search returns a list of all customizable system screens that have this keyword in the Text String Type column of the Edit Templates table. This search returns both customizable text screens that have already have customized text in place (which can be edited) and screens that have no text and where new text can be added.
2) Text: Entering a word in the Text field and clicking Search will return all customizable system screens that have the word in the screen's customized text as shown in the Text column of the Edit Templates table. This search will only return results if customized text has already been added to a screen.
Editing Email Notification Text
Email Text Structure
All email notifications generally have the same structure. Below is an example of an email notification from a BCS testing environment. (Note: This notification was created for testing purposes and is not real.) In this example, the email has four parts which are combined together to create the complete email notification that is sent out by the system:
- Subject – This text appears on the subject line of the email notification. All emails will have a Subject template that can be edited.
- Message Header – The message header text appears at the top of the notification email. Most emails will have a Message Header template.
3. Message Record – The message record consists of information about individual applicant records (such as the application number) that is pulled from the BCS database.
- Message Footer – The message footer is the text that appears last in the email body and typically provides instructions on how the user should respond to the information contained in the email.
The part of the email notification that a template represents is noted in the Text String Type column of the Email Templates table. The image below shows the Subject, Message Header, and Message Record templates for the notification show above. (Note: The Message Footer template is listed last and can be seen in full if you scroll down the list.)
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
Not all email templates have four parts as shown above. Some will only have two or three parts.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Email Placeholder Text
The Text of Notification Templates often include numbers in brackets, such as “{0}”. This notation represents placeholder text, where the information in the email itself will be populated (at the time the email is generated) from records in your BCS database or from your BCS settings. Examples of the Subject template and Message Record template are shown below:
Subject Template Example
The Subject template (shown below) for a sample Provisional Employment Warning email
is translated into the subject line (shown below) of the actual email that is sent to the BCS user. Note that the system substituted "OBCP - BCSDev - OHDPH" for the {0} placeholder.
When clicking the Edit button in the Action column of the Subject template shown above, the field shown below is displayed to the right of the Email Templates table. {0} is the placeholder for the BCS Department Acronym. In our example, the Department Acronym was defined in Admin > Site Data > Departments as “OBCP-BcsDev – OHDPH” and that is why that specific text that was inserted for {0}.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
In some instances, a template may have several possible placeholder values. The text for the template can include none, one, or more than one of the placeholders. The example text above includes one placeholder: {0}. You could, however, change the {0} to {1) or add the {1} after the {0} so that both the Department Acronym and System Abbreviation are included in the subject line of the actual email.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Message Record Template Example
The Message Record template (shown below) for a sample Provisional Employment Warning email
is translated into the body of the actual email (shown below) that is sent to the BCS user. Note that the system substituted "Smith, Timothy" for the {0} placeholder, “15500" for the {1} placeholder, and so on.
When clicking the Edit button in the Action column of the Message Record Template (in the first image shown above), the field shown below is displayed to the right of the Email Templates table. {0} is the placeholder for the Employee Name stored in the BCS database for the provisional employee and {1} is the placeholder for the Application # stored in the BCS database for the provisional employee. In our example here, the database value for Employee Name was “Smith, Timothy” and the database value for Application # was “15500” and that is why that specific text that was inserted for {0} and {1}.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
In the example above, all possible placeholders are currently used in the email text. If you did not want the Provider Name included, you could delete that row of text. You cannot, however, add a new placeholder option of {6} and define it to be Position, for example. A new placeholder option can be added only through implementation of new code.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
If more than one of the same bracketed numbers appears in a single email template, then they are placeholders for the same text. However, the value represented by “{1}” in the Subject template is not necessarily the same value represented by “{1}” in the Message Record template for the same email template (or for different email templates).
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Editing Email Text or Placeholder Text
- To edit the email notification, click the Edit button next to the part of the email you wish to change. To the right of the Email Templates table, the edit entry field will display. The Edit button for the "Provisional Employment Warning - Subject" template shown below was clicked to access the text entry field shown in step 2.
- In the text entry field, you can edit any of the non-placeholder text. You can correct typographical errors or add more instructions. You can choose to use a different placeholder if the system provides an option. For example, in the image below, you can choose between placeholder “{0}” or “{1}.” You could also include both {0} and {1}. You cannot, however, add a new, undefined placeholder of {2}. Once you have made your changes, click Save.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
Once you click Save, your changes cannot be reverted or undone. You can choose Edit again, but you would need to manually re-enter the original text.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
Most of the Department and System information can be defined by accessing Admin > Site Data > Departments on the navigation bar. See the “Managing Department Information and Registries” Users Guide.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
When editing an email template, you can remove placeholder text by deleting the bracketed item from the text entry field. Once deleted, a placeholder can be added back to the template by typing it back into the text entry field.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Editing Customizable Page Text
To see a list of the system pages that contain customizable text and/or to access the text to make a change, follow the steps below:
1. Go to Admin > Edit Templates on the navigation bar. Select “Custom Page Text” from the Template Type dropdown and click Search. A list of pages with customizable text will appear.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
Note
If your system’s configuration does not use a particular page, the Text column will be blank.
Editing Email Notification Text and Custom Text on BCS Pages Page 15 of 15
Version 01 | 3/9/2015 | Audience: State Administrator
2. Click Edit for the template for which you want to modify text (add, edit, or delete). The system will display the existing text (if there is any) in the entry field to the right of the list of templates. In this example, we will edit the custom page text on the Edit Employment page. Clicking the Edit button returns information about where the custom page text will display in the system. See the red box in the image below.
3. If the page has custom text defined, that text populates in the text entry field (under the red box above). In the example above, note that the text entry field is empty; therefore, the system does not currently have custom text displaying at the top of the Edit Employment page (see image below).