Analytics: Scheduled Reports

Setting up a scheduled report

Open a report that has already been saved or create a new report and save the changes you made. You can learn more about creating a new report here: Insights: How to Create a Custom Report and Dashboard

Once you've opened the saved report, select the Dashboard button in the top right corner and then select File from the top left corner of the page and choose Document Settings.

Note: If you select File and don't have the option for Document settings, you will need to verify that your workbook is saved and that you are viewing the Dashboard perspective.

By default the toggle for Schedule is not enabled. Enable this setting to gain access to schedule the report.

Select File once again and choose the new option that has now appeared, Deliveries & Alerts.

The New delivery sidesheet will appear on the left side of the page. Complete the fields to set up your first scheduled report!

Note: These steps highlight everything related to scheduling a report. For Alert, refer to the next section in this article.

• Send: Choose between sending the entire dashboard or one query
• Destination: Choose between Email, Amazon S3, SFTP, and Webhook. 
• Delivery name: Create a name that will help your team easily distinguish what this delivery entails
• Schedule: Select the cadence that the schedule will be sent. If you select Now, the report will send one-time, after you've set it up. If you select Weekly or Monthly, the report will send on the settings that you choose under those options. Read more about the Custom cadence below.
  • Custom: Enter a Cron string to customize the cadence that the schedule will be sent. An example cron string is 00 09 ? * 2,3,4,5,6 *. The first four numbers indicate the time (Military time format), the question mark separates the time from the days, the * represents skipping that day of the week, and any individual number represents that number of day in a week (ex. 1 = Sunday, 2 = Monday, 3 = Tuesday, etc.). Timezones can also be set below the cron string. In this example, the report would send at 9:00 AM on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays.
• Send on: Choose the days of the week that this report will send.
• At: Use the dropdown menu to select the time the report will send. These times are set up at 15 minute increments, if you want to send this at other times outside of the 15 minute increments, use the custom schedule option.
• Times are in: Use the dropdown menu to choose any timezone.
• Test Now: Send yourself a test email of what the scheduled report might look like for recipients. If you do not receive your test email within an hour, try again or contact Support.
• Send: Select this and the schedule will be created, the report will send at the allotted times and days. You can modify the schedule at any time.

There are additional steps for the Dashboard and Email when setting up a schedule.

Dashboard

• Format: Choose between PNG (Image), PDF, XLSX (Excel), CSVs (in ZIP file), Link back to dashboard. This is how the dashboard will show up for recipients of this scheduled report.
• Expand tables: Selecting this will ensure that the tables in the dashboard are expanded to 1,000 rows.
• Arrange dashboard tiles in a single column: Places multiple dashboard tiles into a horizontal column.
• Hide title: Select this to hide the title of the saved report from above the report.
• Include a link back to the dashboard: 
• Use cached results if available: If the recipient has received or viewed this dashboard before and their browser has cached data that matches the data in the dashboard, the results will load faster for them if this is enabled.

Email

• File name (without extension): Provide a filename (e.g. query-dashboard) and the selected format will appear at the end as an extension (e.g. .png).
• Recipients: Choose recipients to receive this email. Recipients do not need a Handshake account to receive the email. 
• Personalize content with recipient's user attributes: If the recipient does have a Handshake account, they will see content specific to their account. For example, if they are missing permissions to access certain data, that data will not appear in the email.
• Subject: Represents text that will appear in the subject line of the email.
• Body: Represents text that will appear in the body of the email.

Final steps

After you've entered your settings and customized the scheduled report to your preferences, you can use the buttons at the bottom of the page to finalize your decision on saving this scheduled report.

• Test Now: Send yourself a test email of what the scheduled report might look like for recipients. If you do not receive your test email within an hour, try again or contact Support.
• Delete: This option only appears after saving the scheduled report. Selecting this will delete the schedule you've set up.
• Save: Select this and the schedule will be created, the report will send at the allotted times and days. You can modify the schedule at any time.

Setting up a Scheduled Alert

Alerts send updates to recipients if a query has met a certain condition to trigger an alert. For example, you want your recipients to receive an alert whenever data on a dashboard has changed.

After opening the Deliveries & Alerts, select Alert as the delivery type. Most of the fields match the process for Setting up a scheduled report. However, there are some fields available specifically for alerts:

• Results to check: Select the query that will be checked for the alert notification to send.
• Condition: Choose between Results have changed, Results have stayed the same, No results are returned, Any results are returned. Our system will use this condition to determine whether the condition has occurred within the query selected.

Check the dashboard and email tabs to verify that the settings meet your expectations.

Note: The schedule cadence for alerts are not determined on the schedule in these settings. Alerts are sent whenever the condition is met. That means if you set this alert on a weekly schedule, it will still only send when "Results have changed" on the query.

Select Save and you can hover over the bell icon on the next screen to verify what conditions are set for this alert. This example states Sends when "Query" returns results that have changed.

Creating a new Reports schedule 

Reports can be scheduled via the Analytics overview page or while viewing a specific report: 

• On the Analytics overview page, click the three dots to the far right of the saved report name, then click Schedule.
• When reviewing a saved report or creating a new custom report, click Options in the upper-right corner, then click Schedule.

In the popup window that loads, fill out the following information: 

Basic Information

• Name of schedule (the name will default to the name of the saved report)
  • The Scheduled Report cannot work if there is a "/" in the name. Please remove any slashes from the schedule name before saving.
• Where should this data go? (Select One: Email / SFTP / Amazon S3)
  • Email: For security reasons, only the creator of the scheduled report can be the recipient. This email address will default to the email address on your Handshake account.
  • SFTP: Enter your URL or IP Address, Username, and Password.
  • Amazon S3: Enter your Bucket, Path (optional), Access Key, and Secret Key.
• What format should your data be delivered? 
  • Email: (Select one: CSV ZIP File / XLSX / JSON / HTML / Text)
  • SFTP: (Select one: CSV ZIP File / JSON)
  • Amazon S3: (Select one: CSV ZIP File / JSON)
• At this time, Row Totals and Calculations are not support for Scheduled Reports.

Delivery timing

• How often would you like the report to be delivered? (Select One: Daily / Weekly / Monthly)
  • Daily: Select one from the dropdown: Every day / Weekdays only / Specific day 
    • Specific day will allow for multiple days to be selected.
  • Weekly: Select one day of the week from the dropdown.
  • Monthly: Select one from the dropdown: Every month / Specific month and select what day of the month.
    • Specific month will allow for multiple months to be selected.
  • At what time? Select from the dropdown, the time you would like to receive the report. Times are available on a 24-hour time format, in 15 minute increments. The time you select will reflect your own timezone. 

Summary

• Confirmation of selections –– click Send test email to test delivery.

Note: For reports scheduled to SFTP or Amazon S3, your credentials are not validated upon entry in Handshake. Sending a test email will validate the credentials entered immediately. If you choose not to send a test email, your credentials will be validated on the first scheduled send date.

If the credentials were not entered correctly:

• SFTP: an error will appear in the lower-right corner that states either "Validation Failed. Check your credentials." or "Connection failed. Upload failed due to error."
• Amazon S3: an email will be sent to the address on your account. 
  • Subject: "Error with scheduled job SCHEDULE NAME"
  • Content: "The scheduled job "SCHEDULE NAME" failed for REASON. Please visit your content (link) to view and resolve the error, or contact your Looker administrator if you need further assistance. Error: (may vary)
    • Example email below:

Editing or deleting a schedule

To edit or delete a schedule:

1. From the left navigation bar, click Analytics, then click the Schedules tab.

2. Locate the desired schedule name, then click the ellipses (three dots) to the far right in the schedule row.

3. Click either Edit Schedule or Delete Schedule from the dropdown menu. 

• Edit Schedule: The same fields from creating a schedule (for Basic Information, Delivery timing, and Summary) are available on the Edit Schedule popup as well.
  • An example of the Edit Schedule popup: 

• Delete Schedule: if you choose to delete the schedule, a confirmation popup will appear that reads "Delete this schedule? This change cannot be undone. All future sends of this report will cease. You may create a new schedule from the report page." To proceed, click Delete.

Scheduled Dashboards

To schedule a Dashboard, click the Schedule button on the individual dashboard page, in the upper-right corner of the page.

The fields to enter will match those of Scheduled Reports. Fill in the Basic Information, select the Delivery timing, and Send test email, then click Confirm to save the schedule.

Click Confirm in the lower-right corner of the popup to create the schedule.

Reviewing Scheduled Reports

To review a list of your currently scheduled reports, click Analytics from the left navigation bar in Handshake, then click the Schedules tab.

A table will display all reports you've scheduled with the following columns: 

• Name (the name of the saved report or Dashboard scheduled)
• Created Date
• Type 
• Delivery Method
• Format
• Frequency

Click the three dots menu to the far right in each row to Edit Schedule or Delete Schedule.

Note: Scheduled Reports to an SFTP or Amazon S3 will only be visible to the schedule creator.

Q: What is SFTP and why would I use it? Can HS set it up for me?

A: SFTP stands for Secure File Transfer Protocol –– it's essentially a secure location that can receive files from Handshake. Because the data may likely contain PII (Personally Identifiable Information), Handshake ensures the options for export remain private and secure. Your IT contact should be able to set up an SFTP location with access permissions. Handshake will not set up the SFTP server on behalf of our partners due to the inherent security considerations. 

To learn more about set up, refer to the Looker Documentation. To receive SFTP deliveries from Handshake, be sure your network admin has added Looker’s IP addresses to your SFTP server’s IP allowlist or inbound traffic rules. 

For Looker Analytics, the necessary Public IP addresses to unblock are as follows: 

• 34.200.64.243
• 54.157.231.76
• 18.206.32.254

For Omni Insights, the necessary Public IP addresses to unblock are as follows:

• 54.172.168.164
• 52.205.119.255
• 3.211.115.21
• 44.199.154.198
• 54.213.219.131
• 52.33.167.28
• 54.213.140.155
• 34.215.77.3

Q: What time of day do reports arrive? Can it be changed?

A: You can select the time that you would like to receive the report! 

Q: Why can’t I email a report to someone else?

A: At this time, scheduled reports can only be sent to your own email address. Handshake may consider opening this up at a later date. The intent is to ensure data is not inadvertently sent to people who should not have access to it, so we are taking a conservative approach at this time.

Q: Is there a row limit on data pushed?

A: Handshake’s analytics service is backed by Looker (Google), which has placed some limits on the data that may be delivered to email / SFTP / Amazon S3 –– Read the details in Looker's scheduling and sharing article. The summary is: 

• Email
  • CSV or JSON formats do not have row limits, but have a file size maximum of 15MB so your email client doesn’t reject it.
• SFTP
  • CSV or JSON - No row limit

Q: What about other destinations like Dropbox?

A: There are numerous locations that can serve as intermediary ‘destinations’ for exported data. Handshake started with SFTPs because of their low-cost and ubiquity. If there are specific destinations you’d like added, we plan on releasing more options in the future, so please let us know what serves you best. 

Q: Who’s allowed to send reports to Email, SFTP, or Amazon S3?

A: Any user with Access and Manage Analytics permissions can schedule reports to be sent to their email address. There is a permission “Schedule Reports to File Storage” that needs to be granted for users to send reports to an SFTP or Amazon S3 destination.

Q: Would you recommend I use my own Handshake account to send reports, or should I set up a separate ‘system user’ account to manage the process?

A: This is up to you. The benefit of a system user is that it can remain untouched and a dedicated user account on which to run your automated exports. If your personal account becomes deactivated (if you leave the school, for example), having a separate account can be useful. However, be sure to control password and lock down permissions to ensure this doesn’t become a risk for improper access to student data. 

Q: What happens to the scheduled report if the saved report changes?

A: If the original report is edited and changes saved, the scheduled report will reflect those changes. Therefore, be careful not to disrupt automated reporting. It is recommended that SFTP and 3rd-party system integrations use a saved report that is a dedicated ‘integration’ export report.

Tip: if you'd like to use another user's saved report, we recommend to duplicate that report and save the duplicate as a dedicated schedule version, as described in Analytics: Using Saved Reports. 

Q: Can we use AZURE SFTP to receive Scheduled Reports?

A: At this time our data partner, Looker, does not support the host_key algorithm used by Azure SFTP. Any attempts to send reports to Azure SFTP will result in this error:
“Connection failed. Upload to SFTP host ‘______________’ failed due to error: Net::SSH::Exception. Error: could not settle on host_key algorithm. Please check your credentials.”