Contact us Blog

Scheduler add-on


The Apsona Scheduler add-on enables you to:
  • Schedule your Apsona reports and multi-step reports to run periodically, and e-mail the results to a specified list of contacts.
  • Schedule runs of merge actions from your Apsona Email and Document Generator add-on, to generate and email documents.
For example, you can:
  • Schedule your weekly sales summary report to run every Sunday at midnight and be delivered to all of your sales managers.
  • Run a merge action once a week, e.g., Friday at 6 pm, and generate all your pending invoices for the previous week and email them to the appropriate recipients.
  • Run a merge action every day at 6 am, generate and send an email containing the day's schedule for each of your field service personnel.

This add-on requires Apsona for Salesforce. To schedule multi-step reports, you will need the additional Multi-step Reporting add-on. To schedule merge actions, you will need the additional Email and Document Generator add-on.

Pricing plans

We offer separate plans for Scheduled Reports and for Scheduled Document/Email Merges. You can mix and match a Scheduled Reports plan with a different Scheduled Document/Email Merge plan to suit your needs. Below are the limits we offer under each plan. All prices are annual.

Scheduled Reports

Small Medium Large Enterprise
Price $200 $1,200 $2,000 Contact us
# Runs 1,000
A "run" is one report sent to unlimited email addresses.

Scheduled Document/Email Merges

Small Medium Large Enterprise
Price $200 $1,000 $2,000
# Merges 600
Each generated document or email counts as one merge.

NOTE: These plans apply only for merges or reports invoked via the Scheduler. Documents or emails you generate interactively via the browser are not subject to these prices, since they are included in the add-on prices shown on our pricing page.

For non-profits

We offer a 20% discount on the above prices for non-profit organizations.

How the limits work

General guidelines:
  • Once you purchase a plan, you may schedule your reports and merge actions to run at any time, as you need.
  • When your usage exceeds 75% of your plan's limit, we will notify you of its impending expiry by email. You can purchase a new plan if you run over the limits of your current plan.
  • Once you have used up the merges or runs in your plan, the scheduler will not run further merge actions or reports until you purchase a new plan. When you do so, you can change to another plan if you like.

Trial periods

We offer free trials of the Scheduler add-on. During the trial period, you may send up to 20 Scheduled Reports, and up to 20 runs of document or email merge actions.

Installing and enabling the Scheduler

To install this add-on:
  1. Visit our AppExchange listing and click the "Get It Now" button. Then proceed through the on-screen directions to install the add-on into your org.
  2. Contact us for a license for the add-on for your org.

Existing Scheduler users: If you already have the Scheduler add-on installed in your org, please make sure to update it to version 1.2 or better. You can do this by visiting our AppExchange listing and clicking the "Get It Now" button. This version update enables you to track your usage (for accounting purposes), and is also required for the Scheduled Document/Email feature.

Once the scheduler is installed into your org, each user who has an Apsona for Salesforce license can enable it for their use. The scheduler adds two menu items in your Reporting Tools menu, named "Scheduled Reports" and "Scheduled Report Runs". Before you can use the scheduler, you must enable it to access Salesforce as you, so that it can fetch data and run reports on your behalf. Do this as follows.
  1. Click Reporting tools - Scheduled Reports. In the main tool bar, the scheduler's status button shows as OFF if you have not yet enabled access for yourself.
  2. Click the status button. A popup window appears. (If you have disabled popup windows in your browser, you will need to enable them at least temporarily.) This popup will walk you through three steps and set up your account for the Scheduler.
  3. After this step is complete, the scheduler status button will show as ON.
  4. Click Settings - Clear cache in Apsona, so that your metadata becomes available to the scheduler when it runs next.

How it works

The Apsona Scheduler relies primarily on the Salesforce Oauth 2.0 facility for authentication, and the Salesforce SOAP API for data retrieval. The scheduler is simply a service that repeatedly runs these steps in order:
  1. Wake up every three hours (midnight, 3 am, 6 am, etc.)
  2. Log in to your org with the Oauth credentials you enabled
  3. Check for any scheduled tasks that should be run
  4. Run the tasks, process the results and send any necessary emails
  5. Go back to sleep.

Scheduling a report

Once the Scheduler is available for your account, you will see a "Schedule..." menu item in each report's menu within Apsona. Clicking the menu item displays a popup window via which you can set up the scheduled runs for your report. Here you can provide
  • a name and description for the schedule
  • the format in which the report should be delivered (HTML in-line, HTML attachment, or CSV)
  • the email addresses to which the scheduled report should be delivered (you can specify multiple email addresses separated by commas or newlines)
  • the subject of the email
  • the frequency of runs, e.g., daily, weekly, or monthly, and the specific days of week or month when the report should be run
  • the time of day when it should be run, which is either midnight, 6 am, noon or 6 pm (all times specified in the Pacific Time Zone).
You can also specify a Start Date and an End Date for the schedule. A scheduled report is run only if, at the instant when the scheduler examines the schedule, its Start Date is in the past, and its End Date is in the future. Note that if a Start Date is not specified, it is assumed to be in the past. Similarly, if an End Date is not specified, it is assumed to be in the future.

The Active checkbox specifies whether the schedule is currently active. Only active schedules are actually executed. So if you want to temporarily disable the schedule runs for a particular report, you can simply un-check the Active box and click Save.

Data produced by a scheduled report

Bear in mind that the scheduled report runs with the credentials of the user who set up the schedule. It therefore respects any object, field or data constraints of that user's profile. For example, if record sharing is set up so that certain records are not visible to that user, then those records will not be retrieved by the scheduled report.

Scheduling a merge action

To schedule merge actions, you will need the Document Generator add-on, which enables you to create merge actions via the browser. Once a merge action is created and available for use, you can set up a schedule for the merge action as follows.
  1. Navigate to Settings - Merge actions in Apsona, where you can view and manage all the merge actions that have been set up in your org. Click the row for the merge action you wish to schedule. With the Scheduled Document Generator add-on license enabled, a "Schedule" button will be available on the detail record of the merge action, as in the screen shot below.
  2. Click the Schedule button to bring up the scheduler popup, shown below. In this popup, you can set the parameters for the schedule, including the start and end date, frequency (Daily, Weekly, Monthly, etc.), and the preferred start time.

    When you click Save in this popup, you will create a record in the Apsona Scheduled Job object, which is part of the Scheduler managed package. If you are creating a new schedule for a merge action, the caption for the popup is shown as "Add Apsona Scheduled Job record". But if there is already a Scheduled Job record created for this merge action, the caption is shown as "Add Apsona Scheduled Job record".

How a scheduled merge action is run

To run a merge action, the scheduer follows these steps:
  1. Retrieve the data needed for the merge action into memory.
  2. Construct all the necessary documents or emails needed by the merge action.
  3. Carry out all the actions required by the merge action:
    • If the merge action generates emails, send any emails needed, along with any necessary attachments;
    • Attach the documents to data records, if needed;
    • Update any fields that should be updated;
    • Create any necessary tasks.
  4. Send a confirmation email to the owner of the merge action, with the results of the merge action attached. These results will be the same as the download available if the merge action were to be run interactively via the browser.
    • If a single document is generated, it will be emailed to tne owner.
    • If multiple documents in are generated in a zip file, the zip file will be emailed to the owner.
    • If emails are generated and sent by the merge action, the resuls CSV file (which would be available for download in interactive mode) will be emailed to the owner.
    Note, however, that the results attachment is limited to 5 MB. If the generated results file exceeds this size, the confirmation email will still be sent, but the attachment will not be included.
It is worth pointing out that the data retrieved from your Salesforce org is never stored anywhere on the server, not even temporarily. It is only available in volatile memory and only during the document/email generation period. It is completely erased from memory immediately after the merge action processing is completed.

Managing scheduled jobs

If you click Reporting tools - Scheduled Jobs in Apsona, the screen shows the scheduled jobs in your org, with a list on the left and a detail panel on the right. Clicking a row in this list shows the details for that schedule, and in a child tab, it shows a list of all the previous runs of the schedule. See screenshot below. Some things to note:
  • The Item Type field shows the type of item being scheduled: either a Doc/Email Gen (merge action), a Report, or a Multi-step Report.
  • You can use the usual Apsona filter feature at the top of the list to find specific jobs.
  • The detail area on the right of the list includes a "Delivery" panel that shows the delivery options that the user selected for reports and multi-step reports, showing the email subject and the recipients of the scheduled report. This panel is not applicable to merge actions, so it won't appear when a merge action's details are shown.
  • If you are an administrator, the list will contain the schedules set up by all the users in your org. If you are not an administrator, you will see only your own schedules.
You can use this list to find particular schedules (via the filter mechanism), update or delete them. If you delete a schedule, the corresponding report or merge action will of course no longer be run on a scheduled basis, but the report or merge action itself will be unaffected.

Schedule run results

The child tab at the bottom right of the Scheduled Jobs view shows a list of run results for the selected Scheduled Job. Each Run Result record in this child tab includes the time of the run, the result of the run, and the Generated Item Count. This number is always 1 for reports and multi-step reports, but for merge actions it shows the number of documents or emails generated by that specific run of the merge action. The screen shot below shows an example detail area and the Run Results child tab. You can also access the list of all Run Result records by clicking Reporting Tools - Scheduled Job Runs. This lets you inpect the entire list of scheduler runs for your org, so that you can view and manage the scheduler usage for your org. The Item Count field for these records indicates the number of items generated by each run, and is used for calculating the costs for which you will be billed.

Frequently asked questions

I don't see the scheduler menu items in my Apsona menu bar.
Please see the Troubleshooting section below.
Are my user credentials (user name/password) stored in the Apsona servers outside Salesforce?
No, we do not store your credentials. Apsona's scheduler uses Salesforce's Oauth 2.0 capability to run your reports for you. This ensures that your credentials are not stored anywhere outside Salesforce.
Will changing my password affect scheduled reports?
No, because Apsona's scheduler uses Salesforce-issued Oauth security tokens to access your data. Your scheduled reports will continue to work even if you change your password.
Is the data in my Salesforce org copied into an external data store for reporting?
No. When the report must be executed, the scheduler queries your Salesforce database directly, extracts only the necessary data, constructs and formats the report and sends off the email messages. The data is never stored anywhere on our servers, not even temporarily.
What are the limits on report sizes for the scheduler?
The total size of the HTML email body, HTML attachment or CSV attachment cannot exceed 20 MB. If your email body or attachment exceeds that limit, the email you receive will include an error message indicating the size of the generated attachment, so that you can tweak your report to reduce the attachment size.
What email provider does the scheduler use for sending its email?
The scheduler sends its emails through your Salesforce org. So these messages count against your message quota, which is usually at least 1,000 messages a day.


Please ensure that:
  1. The package is installed: The Apsona Scheduler package is installed in your org - you can get it from our AppExchange listing.
  2. The license is valid: Your org has a license for the Scheduler add-on. Please click Settings - Manage licenses in Apsona to verify the license. Read more about this.
  3. Objects are accessible: Your Salesforce user profile has full read/write access to the two Scheduler objects, Apsona Schedule (API name apsona_sched__Schedule__c) and Apsona Schedule Run Result (API name apsona_sched__Schedule_Run_Result__c), as well as all of their fields.
  4. Email permissions are set: If you have integrations with other email providers such as Office 365, each user who uses the scheduler should have their email delivery provider set to "Salesforce". See this article on for details. If this is not done, scheduled report delivery will fail with errors such as "Missing refresh token. User might not have been authorized."
  5. Owner is set correctly: The Owner field of your Scheduled Report records is set to your user id. The Apsona Scheduler runs only those Scheduled Reports whose Owner is the same as the user who is authenticated to run the Scheduled Report record, so of those two aren't the same, the Scheduled Report will not be executed.