Help

Table of Contents

• Concepts
• Listing schedulers
• Defining scheduler
• Testing scheduler
• How agents call your urls
• Auth Codes
• Limits

Concepts

Scheduler Service application consists of two parts:

• Administration Interface lets you view, add, edit and test schedulers.
• Agents are long running processes that actually execute schedulers by fetching URLs defined with Administration Interface

Most important scheduler properties are:

• Interval: this is minimal number of seconds between scheduler invocations. Actual number of seconds will be bigger.
• Auth Code: authentication code used to verify that url called is really a scheduler url, not just a regular page. Auth code is automatically generated when you create url and cannot be changed. Read more about Auth Codes.

Listing schedulers

Main application screen shows table of your schedulers. Each table row represents scheduler.

Defining scheduler

Click "Add new scheduler" to display new scheduler form. Fill form fields:

• Scheduler Name - this is scheduler name, it identifies your scheduler. Scheduler names must be unique.
• URL - this is URL you want to be called periodically. URL must start with "http://". https is not supported.
• Interval - this is number of seconds between calls. This must be at least 900 seconds. Actual time your scheduler will be executed is bigger - currently, your scheduler can get called even hour after it's time comes (although it's very unlikely execution will be late that much). This will most likely change in future, but currently service is designed to help with relatively rare tasks, like sending reminder emails once a day, so higher resolution is not really needed.
  Also, keep in mind, that specifying an interval of 86400 and executing scheduler at some time of day will not make this scheduler execute at this exact time every day. Due to nature of how agents work, each invocation will be a little bit late and after some time execution time will change. If you need to execute some tasks at certain times of day, you can set interval to small value and execute necessary checks early in your scheduler handler code. This shouldn't take much of your apps resources.
  If advanced scheduler execution time settings are really needed - please contact me, and I'll try to find some spare time to implement this functionality.

Click "Ok" button if you're happy with your settings or click "Cancel" if you changed your mind.

After you create scheduler it's initially in disabled state.

Now it's time to setup URL that gets called by scheduler. You must make sure that script returns auth code you can see in schedulers table. If you want to test Scheduler Service and don't want to create real script, you can put a text file on your server and paste auth code in this file.
Agent will disable your scheduler if response will not match auth code.

After you've set up schedulers target URL, you can click "Enable" link in schedulers "Commands" and your scheduler will be configured.

Testing scheduler

For testing purposes there's possibility to execute given scheduler by clicking "Test" link in schedulers row. Application will fetch your url and update "last execution time" and "next execution time" for this scheduler. Test page will show first 256 bytes of response received, so you can check if URL is correct.

How agents call your urls

Agent is a long running process that periodically checks with main page if there are any URLs to be fetched.

For each URL agent executes GET request and fetches first 256 bytes of response. Your app can get "broken pipe" errors if response data is longer than 256, because agents don't try to fetch full response. Make sure your scheduler handler executes quickly and returns small amouts of data.

Response data must be exactly equal to scheduler's auth code.

Auth codes

Auth code is a randomly generated string of letters and numbers.
It's purpose is to prevent users from calling URLs they don't own.
URL you put in scheduler definition must return the auth code, or agent will disable scheduler.
You can later investigate why scheduler url didn't work and re-enable scheduler manually by clicking "Enable" link in "Commands" column.
Agents check auth codes against first 256 bytes of response stipped from whitespace. Python pseudocode is:

r = urllib.urlopen(url)
t = r.read(256)
if t.strip() != secretcode:
    disable_scheduler(owner, name)

Network problems do not cause scheduler to be disabled.

If your scheduler gets disabled by agent, you'll be able to check when and why it got disabled by clicking on "Disabled" link in "Is Enabled" column in schedulers listing.

Limits

Some limits are enforced to ensure service works reliably.