Creating a PolyData Dashboards Agent

A new Agent can be created using the following steps:

1.) Navigate to the folder you’d like to create your Agent in.

Agents should be saved in the subfolder set aside for your department under Catalog –> Shared Folders –> Agents. Functional area developers only have access to the subfolder of their specific department and a General folder for Agents that don’t neatly fit into existing categories. Developers can create deeper levels of subfolders as needed.

Open

2.) Select New –> Agent.

Open

3.) You will be taken to the following screen with multiple tabs for configuring and customizing your Agent. The following sections describe each tab configuration in detail.

General tab

Priority – flags the email as High, Medium, or Low Priority. It makes no functional difference.

Run As – should be left set to Specified user with yourself as the value.

The Run As: Recipient option could be used to tailor the data in a report to the individual receiving it; however, the way use accounts are managed in PolyData Dashboards makes this option impractical.

If a developer wishes to tailor a report to the recipient, they should submit a ticket to the Help Desk. An ITS analyst can help you set up a BI Publisher report with the bursting feature to email specific data to specific people.

Schedule tab

Enabled – the Agent will only send emails when this is checked, so make sure this is checked when development finishes.

Frequency – can be set to Once, Daily, Weekly, and Monthly. You can also set specific days and weekly intervals for the Agent to run.

Start – the time you want the Agent delivered. The default time zone is GMT (Greenwich Mean Time), so it is highly recommended that you select PST from the dropdown before scheduling.

Re-Run – select if you want the Agent delivered multiple times per day.

End – choose Select end date if you only need the Agent delivered for a specific period.

Condition tab

Do not use a condition – select if you want the Agent to always be delivered on this schedule.

Use a condition – select if you sometimes do not want the Agent delivered. This condition can be based on the delivered report or a completely different report.

The only type of condition we create is one based on the number of rows in an Analysis object. Because the condition can be based on any Analysis, you could make a separate Analysis object that triggers this Agent. For example, the above report would be delivered when the row count is greater than 0 (i.e., the report has some data).

This feature could generate alert emails if an Analysis object were first built, which returns data only when the alert condition is met. Click the Test button to see if the condition you have built is currently met.

Delivery Content tab

Specifies what content will be delivered by this Agent and in what format. Choosing “Deliver as attachment” is recommended to avoid formatting issues that may arise when data is pasted into an email. In addition, you can specify a subject line and attach a note in the body describing to the recipient what is being delivered. Agents can only deliver an Analysis or a Dashboard Page object.

Subject – input the email subject line.

Optionally, some dynamic variables can be inserted into the Subject line. Most of these variables are date-based and can change from day to day. Below is a list of some potentially useful variables:

Content – specify the subject and choose the Analysis or Dashboard that you’d like to deliver.

Analysis –

Dashboard – note that you can only subscribe to one page of a Dashboard.

Recipients tab

Setting yourself as the only recipient while an Agent is still under construction is recommended. Be sure to note down all the recipient emails or mailing lists when you submit the ticket to have your Agent published by ITS.

There are multiple options for setting up a list of recipients:

Static List of Emails – use this option to create a list of specific email addresses.

Shared Mailing Group – set up and maintained through Help Desk tickets

You can also send the email to a mailing group and the emails will be forwarded to everybody in the group. That group can be requested and maintained through Help Desk tickets (Tech Services and Support). Add the mailing group address to the list of recipients.

Dynamic List of Recipients – generated by an Analysis. This option can send the email to a dynamic list of users.

First, set up or find an Analysis with a column containing the email addresses of the desired recipients.

Second, ensure the Agent's Conditions tab is pointed to in that Analysis.

Finally, click the “Use Analysis” checkbox and select the email column from the popup window. The entire report will be emailed to each email address in that Analysis.

If you need to email specific pieces of the report to each individual (for example, only the parts that concern them), submit a Help Desk ticket, and ITS can help perform a more complicated setup.

Because the recipient list must be used on the Condition screen, it is difficult to use a dynamic recipient list AND make the email delivery conditional. Usually, we must choose one feature or the other.

Destinations tab

Do not check – Home Page and Dashboard, System Services

Do check – Devices –> Specific Devices –> Email. Be sure to only select Email.

Actions tab

This allows your agent to trigger additional actions, such as executing scripts or triggering additional Agents. This level of complexity is generally not required.

Once all tabs are configured, save the Agent under the appropriate subfolder inside Shared Folders –> Agents –> [appropriate subfolder]. Feel free to create additional levels of folders within your subfolder.

You can also run the Agent immediately, regardless of schedule, by selecting the Run Agent Now option.

Setting Dashboard Page Filters

If scheduling a Dashboard Page, you probably want to choose which filters to run with. See an example of filters below:

The only way to specify which filters to run a Dashboard Page with is to navigate to the Dashboard Page, set the filters you want, and then save this page as a “Customization” using the gear icon in the upper-right. You MUST check “Make this my default for this page” when saving.

Functional area developers can only create/edit Agents in the Test site (http://analytics.test.calpoly.edu/ui/dv), not in the Production site (http://analytics.calpoly.edu/ui/dv).

Functional area developers should save their Agents in the subfolder set aside for their department under Catalog → Shared Folders → Agents. If needed, they can create deeper subfolders inside their department's folder.

If you want the Analysis that the Agent is scheduled to run to be accessible to users, it should be saved outside of this Catalog → Shared Folders → Agents structure. Since only developers have access to the “Agents” folders, the Analysis will be inaccessible to most users if saved inside.

Once set up and tested, functional area developers can submit a Support Request ticket and ITS staff will publish the Agent on the Production site (https://analytics.calpoly.edu/ui/dv).

Please include in the ticket:

• The name of the Agent

• The folder where you saved it

• The specific email addresses or mailing lists of the intended recipients (if they differ from the list of recipients saved in the Agent)

• If used, any dashboard filters you have set it to run with (see the section “Setting Dashboard Page Filters“)

Unless you specify otherwise in the ticket, all Agent settings (including schedule) will be carried over as is.