Agent Alerts Documentation


Field Descriptions

  • Agent Alert Name: This is just a meaningful name you can use to help find the alerts, but has no impact on functionality.
  • Active: This enables the agent alert
  • Alert Order: This is not a unique number, so these can overlap, but this is the ordering of the alerts as they will be displayed on the specific object with null values being sorted last. For example if you have 5 alerts set up on the Account, you could leave this blank for the least important alerts, then you could set a 1 value for the high priority, and a 2 for medium priority alerts to ensure that the most important alerts are displayed at the top when opening the account.
  • Object API Name: This is the object the Alerts will be displayed on. For example for an Account alert, this would just be Account. For your custom object, it might be Custom_Object__c. If you want to make a child alert to see warnings for child messages, then you need to include the child relationship name, for example Account.Opportunities. You can read more about this in the section for Creating a Child Object Alert.
  • Alert Message: This is the message you want to display for this alert. If this is a Child Object Alert, this field will be the top level message. For example it might say "You have open High Value Opportunities." which would be displayed once if the alert criteria are true. You can include merge fields from your object in the message to make it more meaningful.
  • Alert Message Children: This field is only populated if this is a child object alert. There will be one line item for each child record that matches the criteria and will be listed underneath the Alert Message. For more details on the usage of this field, see the section for Creating a Child Object Alert.
  • Use Advanced Filter Logic: This allows you to create advanced filter logic similar to what you can do in workflow rules, reports, and validation rules.
  • Advanced Filter Logic: This is where you'll enter the advanced filter logic. For example if you have 5 filters, the logic may look like (1 AND 2 AND ((3 OR 4) AND 5)). See here for more details.
  • Field: This is the field on the object you're watching for the alert. For example on the Account you may want to add a filter to the Name or BillingAddress, or maybe you're creating an Opportunity Alert and want to check the Account Record Type so you would use Account.RecordTypeId. If this is a Child Object Alert, these fields will be based on the child object. For example if this is an Account.Opportunities alert, the field will be an Opportunity. If you want a specific filter to be based on the Account, you'll have to use the parent relationship like Account.Name.
  • Operator: This is the operator for the field you're looking at. For example if the field has a string value, this would allow you to see if the string contains a value, or for a checkbox the only values are true and false.
  • Value: This is the value you're checking for. This can be a single value, or in cases of Strings or Id values it can be a list. See the section Value Lists for more details.

Creating a Basic Alert

Creating a basic alert is easy. If you've already done the initial setup and followed all the steps, then you've already created an alert. If you haven't done any of the initial setup, please see that documentation here to do so. If the app is installed and permissions are already updated, then you can just follow along here to the same instructions for creating your first Agent Alert.

To create your first alert, just navigate to the Agent Alerts tab and click the New button to start filling out the details. Start by giving your alert a meaningful name and set it to Active. For the example, you can leave the Alert Order blank, but can read more about it in the Field Descriptions section to understand how it works. Populate Account as the object and create a message. You can use the built in Rich Text editor tools to add graphics to your message to help particular messages stand out more. The value in the {!Name} is a merge field that will display the Account Name when this message is displayed on the output account. After you've created your message, add your first filter. In the filter, just populate the Field with "Name" to look at the Name field for this filter, then set the Operator to "contains" and finally the value to "test" like the screenshot and save the alert.

New Record Alert Screenshot

Now that your alert has been created, you can create an account to test it out. As long as the account has "test" somewhere in the name, then this alert will be true for the account and it will be displayed.

Record Alert Message View

Creating a Child Object Alert

Creating an alert for child objects is similar except you'll be referencing fields on the parent and child objects based on what field you're populating. In this example you are going to create an Account alert that will look at Opportunity records and display an alert for high value Opportunities with an Amount greater than or equal to $10,000. Below is a screenshot of the example alert that you can recreate, then a description of the differences here between a child object alert and same object alert.

High Value Alert Configuration

In this example, the Alert Order is populated. This is because we want this alert to be a high priority when determining what order it should show up on the Account. The Object API Name is Account.Opportunities because the Alert should be displayed on Account records, but it's based on Opportunity criteria. The first part of the API Name here is the full API name of the object, so if you have a custom object, it would be Custom_Object__c. The second part is the relationship name of the child list. To get the relationship name, browse to the child object, then look at the Child Relationship Name field. If you open the Opportunity object, then click on the Account field, you'll find that the relationship name for that field is "Opportunities", so the full Object API Name to use would be Account.Opportunities. All custom lookup and master detail fields will need to have a "__r" appended to the child relationship name. For example the Custom Object might have a custom child object that looks up to Custom Object with a relationship name of "Custom_Child_Objects" so the full name to create a child agent alert would be "Custom_Object__c.Custom_Child_Objects__r".

Getting the Child Relationship Name

In the Alert Message, the merge fields are the API Name fields from the parent object, in this case the Account. To create a merge field just place "{!" in front of the API Name, and "}" after the field. When this message is displayed, it will show the Alert Message once, then below that it will list each of the Opportunities that match the criteria in the filters. The merge fields can use Salesforce relationships to display parent record details. See the Merge Fields section for more details.

The Alert Message Children field is the message that will be displayed as a list for each Opportunity record that matches the filters. The merge fields in this one represent the Opportunity object. So this field will show the Opportunity Name and Amount, and there's also a link to open the Opportunity up. See the section for Message Links to link to create links in your messages.

The API Names for the filters here use the child object, so these reference the Opportunity object. If you want to base a filter on details from the Parent account, or some other parent object to the Opportunity, you can use the Salesforce relationship value to reference fields on parent objects. See the Merge Fields section for more details on relationships.

Visualforce Page for Custom Objects

Out of the box you can create Agent Alerts for any object, and drop the Visualforce Page on any page layout for Accounts, Contacts, and Opportunities, but you can create a page just by creating a new Visualforce page and copying and pasting a few lines of code, then changing one value to use the field on your custom object. To create a new Visualforce Page, you can go to setup -> Develop -> Visualforce Pages and click the New button. You can read more about it on the Create & Edit Visualforce Pages Trailhead. Create a new Visualforce Page and just copy and paste this code into the page, then set the standardController attribute as the Object API Name you'd like to put this page on and click save. That's it, you're done. Below is the code you can copy and paste, then a screenshot showing an example.

    

Custom Visualforce Page

Once you've created this page, just set up the profile security for the page then open up the page layouts for the object and place the Visualforce page wherever you want your alerts displayed and you're ready to start creating alerts for the custom object.

To set the profile security, the easiest way is to navigate back to the Visualforce pages from your setup menu and click the security button next to the page, then on the next page select the profiles that should have access to the page.

Visualforce Page Security

Visualforce Page Security Selection

Advanced Features

Now that you've created a few agent alerts, you can dive into some details of the more advanced features where you can craft your message with the exact field information you need, create more detailed filter logic, or even update the styling of your text in ways that the built in rich text editor doesn't allow.

Merge Fields

If you have already put a field reference into into one of the message fields for an Alert, then you have already used a merge field. The idea of merge fields is simple, but you may want to learn how to include fields from the parent objects in your message. Here you will learn about the basics, but you can read more about Relationship Names from Salesforce.

To include fields from your object in the Alert Message field, you just need to place "{!" on the left side of your field, and "}" on the right side. So if you are creating an alert on the Account object and you want the BillingState in your message, just write {!BillingState} in your message. If you're creating an Opportunity alert and want to display the same field from the Account, then you need to use the Account relationship on the Opportunity like this {!Account.BillingStreet} where Account is the standard lookup field. The way you actually reference the relationship will be different depending on whether or not the lookup field is a standard or custom field. To get relationship details through custom lookup fields, you need to replace "__c" in the field name with "__r" and for standard lookup fields, you'll just remove the Id from the field name. For the example above, we used the AccountId field on the Opportunity and just removed the Id from the relationship in order to get to the Account fields.

You can reference up the lookup chain to get values from ancestor objects. For example if you have a custom object linked to the Contact object using a lookup field called Contact__c, you might want to reference a field from the Account so you could add a merge field of {!Contact__r.Account.BillingStreet} to place the Account BillingStreet in a message down on an alert for your custom object linked to the Contact.

Below you can see an example created to show the values of Relationship merge fields. In this example, my custom child object is linked to a custom object, which is then linked to a the Contact object with a custom field named Contact__c, which is linked to the Account object through a standard field. After the setup, is what the record looks like with the output message.

Creating an alert with Relationship Merge Fields

Relationship Merge Field Output

Advanced Filter Logic

The items you can use in the filter logic are OR and AND values, and left and right parentheses and spaces, but the number of open and close parentheses must match. This logic works very similarly to the way you create custom filter logic on reports. At this time we do not support the NOT operator.

By default, all field filters have to be true in order for the alert to be displayed, but your needs are likely much more advanced than that. In a common example might be something like wanting to compare Open Opportunities that have an Amount less than a specific value like 1000. You might start out by creating 2 filters with IsClosed equals false, and Amount less than 500 like below but you might soon discover this will not work exactly as expected.

Advanced Filter Screenshot

After you view a few Opportunities, you might discover that Opportunities with a blank Amount don't show up because empty values don't result in a true when checking if the value is less than 500. In order to fix this, you can update the filters to add another filter for Amount equals [blank]. The default logic will want all conditions to be true, but the Amount cannot be less than 500 and blank at the same time. To fix this issue, just check the "Use Advanced Filter Logic" checkbox above the filters and and set up your filters like this.

Advanced Filter Logic Example 2

One other thing you might want to do is use relationship fields. You can see the Merge Fields section to read more details about using relationship fields and include those in your filter logic as well. For example you may want to only display Opportunity Alerts where the account has a specific record type, so you could reference the Id with Account.RecordTypeId, or the Record Type API Name with Account.RecordType.DeveloperName.

Value Lists

Another feature you may want to implement is checking the field against a value in a list. For example you might want an alert to show up on records that have or do not have a few record types. You could create multiple filters and advanced filter logic with several OR conditions, or you could just create a list. Currently we support string and Id fields for lists. There are also two different ways of creating a list, the easier way of creating a list is comma separated values without leading or trailing spaces. If you have a simple list of something like Ids, it's easy to comma separate them but you might have more complex strings you want to check for that have commas, tabs, or new lines. In order to check for these, you'll need to create a JSON array. You can read more about JSON here, but  this this will provide a brief overview of the details you will need to create your own JSON array.

To create a JSON array, you'll just need square brackets on both sides of the array. Each value will have a double quote on each side, and be separated by commas. For example a simple array would look like this: ["item1","item2","item3"]. So if you have a comma, you'll need to create a JSON array, but you might wonder what you do if you have something like a double quote inside your text. There are several characters in JSON that you'll need to escape if you want to use them. Below you'll find a table describing the fields that you will need to escape.

Character Escape Value
double quote " \"
backslash \ \\
backspace \b
form feed \f
new line \n
carriage return \r
horizontal tab \t

If you wanted to create an example where you are looking for text with a double quote and a backslash, it might look like this: ["here we are escaping a \"double quote\" in a string","but also have to escape the backslash \\ character as well"]

Now that you have an idea of how this might work, below you can see a couple examples of this in action. First is an example of a simple comma separated Id list, then a agent alert with the same list in a JSON array, and finally a more complex list that shows an escaped character.

Configuring a Value List with Comma Separated List

Configuring a Value List with JSON Array

Now you can see what this looks like on one of these VIP Accounts in the list.

Example output of an Alert created with a value list

Next is an alert to display on the Accounts "Widgets, Inc.", "Test \ Account", and "Test " Account". These examples highlight the escaping of the \ and " characters. You do not have to escape the comma, but we have to create the alert this way and not a comma separated list because that will not return a true value because a comma separated list would separate Widges and Inc. as 2 different account names.

Special Character Alert

Output of the Special Character Alert

Message Images

This is a built in feature of the Rich Text fields that Salesforce provides, but you can use it to really enhance your output. In the early examples we created, we inserted images into the alerts to make them more eye catching, but you could also do something more simple like adding an image for the message children to create a bullet point list. You could try to use the built in bullet point list, but this actually does not work because it creates a new bullet point list for each item in the children list. To get around this, you could imitate the output of a bullet list with a simple circle image. If you are interested in finding images, you can search around for many free clipart sources like openclipart.org. You may also need a photo editor to do some simple resizing for many of the options you'll find.

For this example we will revisit the high value Opportunity alert and add a bullet point to it. Here we don't show the creation of the bullet point image, just open the alert, click the image button to add the bullet point and prepare the child message. Below is a screenshot of the alert and the result.

High Value Alert Config Bullet Point Update

High Value Alert Bullet Point Update Output

Creating links in messages is a built in part of the Rich Text fields, but this section is to explain how to do this. You can create links just by highlighting the text you want to turn into a link, then click the link button. In this example, we are linking to the Opportunity records from the High Value Opportunity Alert. To do that, just set the URL as "/{!Id}" to bring in the Opportunity Id as the merge field. After setting the URL, go to the Target tab and set it to the target you want. If you want it to open a new browser tab, use the "_blank" target. This will now allow the user to click the Name of the Opportunity to open it in a new tab.

Create Record Alert Link

Create Link Target

Advanced Message Styling

This section is mostly irrelevant now if you use Chrome. You can install our Rich Text Enhancer Extension to handle most of these features for you.

You can create all kinds of styling in your messages, but Salesforce limits the things you can do with the built in rich text editor. For example, you may want to set font colors or make your font larger or smaller than the font allows. Here is how to do a few of these things and resource links to help you do even more.  If you you want Salesforce to enhance the rich text editor to give it more features, please vote on this Salesforce Idea to help put it on their road map.

This is the only section where you will need a tool like the Salesforce Data Loader to update your data. I would recommend creating your alert first, then pulling the message fields and updating them back into Salesforce. Do not add any new merge fields while you're doing this though because there are several fields in the background that are updated to store information like the merge field names and speed up processing.

The most important html element you will be using is the "span" element that you just wrap around the text that you want to style. Another important thing to know is that you can have multiple styles for the same span just by separating them with a semi-colon. You can read more about this element on the w3schools page for span. To add styling, you will use the style attribute on the span element that you just created. Below is a table with some of the attribute values you might want to set and links to the appropriate w3schools page for that attribute if you want to read more about it.

Element Explanation
color Set your font color
font-size Set the size of your font
font-weight Set the weight of your font like bold
text-decoration Set text decoration like underline or strike through

Here we will pull the High Value Opportunity agent alert with Data Loader, then update the message, and message child field to add some of this styling. To add your styling, just figure out where you want the style to start and stop. Where you want it to start, you open the span with "" then where you want to end, you close it with "". In the example, you will see nested spans where we want the entire message to be a larger font, but we also want the amount to be red.

Record Alert Advanced Styling

Now that we have added style, we can look at the alert and an account with high value Opportunities to see the alert. This styling went a little over the top, but you can see the end result.

Record Alert with Advanced Styling completed

Record Alert Advanced Style Output

RecordAlertChildSettings Configuration

style="font-size: 20; font-weight: bold;"
In order to speed up processing, by default, we limit the number of child records of each child alert object type to 10 records ordered by the CreatedDate descending. The child object queries are all sorted the same way. For example if you have have 5 Account.Opportunities alerts, we will only query for the newest 10 Opportunities and the alerts will apply to those Opportunities. This is done because the query for all records happens at one time. If you want to search for more records in a particularly important object, you could change the limit to a much larger value but it will impact performance. To change the child query settings, go to Setup > Develop > Custom Settings > RecordAlertChildSettings and click the Manage button. Next click the New button to add your new setting and fill out the Name, Object API Name, and either of the other 2 fields you want to change from default. The Object API Name is the same as the Object API Name you used in your Agent Alerts like Account.Opportunities.

Some things to note about populating these fields:

  • The actual value in the Name is irrelevant, just put in a value that might help you find this record to edit in the future.
  • The Object API Name is case sensitive and must match the Object API Name you have used or are going to use in your Child Agent Alerts.
  • The Order By Criteria is a field and can be Ascending or Descending with null values first or last. In order to define your ordering, just put the API Name of the field, then ASC for ascending, or DESC for descending, and finally you can specify NULLS FIRST or NULLS LAST. The defaults for sorting are ascending and nulls first, so you don't have to specify those things unless you want them. For example putting an order by value of "CreatedDate" would have the same result as "CreatedDate ASC NULLS FIRST". One more sorting option to throw into the mix is that you can order on multiple columns. For example you might want to sort something by Phone, then Name. In this case your order by criteria might be "Phone, Name" so this would sort by phone number, then when duplicate phone numbers are encountered in the sort, it sorts by the name as well. You can sort these by ascending/descending and null values as well. For example you might want to do this "Phone ASC NULLS LAST, Name NULLS LAST" which would sort the list by the phone number with blank values at the end, and then the name if duplicate phone numbers are encountered. You can read more about ordering from Salseforce here. If you leave this field blank, the default value is "CreatedDate DESC".
  • The final field is the Record Limit, and this is simply the number of records you want to query for within the child records. For example if you have an object with lots of children like Cases or Tasks that you want to search through, you may want to set this to a larger value like 100. If you leave this field blank, the default value is 10.

Configuring RecordAlertChildSettings

Debugging

Check Active

style="font-size: 20; font-weight: bold;"
This is a simple one and the first thing you should check because it's the fastest one to check. Make sure the Agent Alert you're expecting to see has the Active checkbox set to true.

Check the RecordAlertChildSettings Configuration

style="font-size: 20; font-weight: bold;"
If you see the records show up sometimes but not always, then double check the RecordAlertChildSettings and make sure the configuration allows for the querying of enough records to suit your needs. You can read more about configuring the settings.

Save the Record in the UI

style="font-size: 20; font-weight: bold;"
If you have made any changes in with an external tool like Data Loader, then navigate to the record in the Salseforce web interface and click edit then save on the record. There are record validations and several settings that are set in the background when a record is saved to make processing faster for loading the record. Make sure the record saves correctly, then try viewing a record that should show the alert.

Check the User Accessibility

style="font-size: 20; font-weight: bold;"
Salesforce requires that AppExchange packages honor the Salesforce security model, so if an alert isn't working for the user, check security permissions. Here are a few to look into.

  • Confirm the user has security access to the Visualforce page that displays the alerts they are expecting on the object. For example make sure they have access to the RecordAlertAccount page if they should be seeing the error there.
  • Confirm the user has read access to the Agent Alert object and fields.
  • Confirm the user has read access to the Agent Alert Filter object and fields.
  • Confirm the user has access to the parent and child objects being referenced in the Alert Message
  • Confirm the user has access to the fields that are referenced in the Alert Message, Alert Message Children, and Filter Fields.

Test Each Filter

style="font-size: 20; font-weight: bold;"
I saved this one for last because it could be the most difficult depending on your filters. Try removing all but 1 filter and confirm that you can see the alert based on that single filter. If that one works, try adding your next filter and confirm it works. Continue down the chain until you have added a filter and the alert disappears. If the first filter doesn't work, try something simple like a filter for "Name not equal to" and leave the value blank so you know it should be true. This is just a test to make sure your filter works at a most basic level. If this happens, you have just confirmed there is something unexpected happening with the first filter. A good example of this would be a blank number value. If your filter is something like "Amount less or equal 1000" and the actual Amount is blank then the filter will evaluate to false because blank is not evaluated as the number 0. If you want to create a filter for this, then you would actually need 2 filters for "Amount less or equal 1000" and "Amount equals" with an or condition to link them so it will link them.

If you are still experiencing issues with your agent alert, please reach out to support@crmforesight.com.