Scheduler Item

A scheduler item is also sometimes referred to as a scheduled job, or a scheduled task.  If you're already a developer, you can pretty much guess what this is, but it's a way to write some code that can get executed over and over, on a defined schedule.  This is a common way to synchronize information of any kind from one place to another, cleanup data, or anything else that you can think of.

What is it Really?

A schedule item is nothing more that a single class file that runs code that you want to have happen on a repeated basis.  This class file could of course call other code in other places, but it really is that simple.  

Code Sample

using System;
using DotNetNuke.Services.Scheduling;

namespace YourCompany.ScheduledItems
{
    public class SampleSchedulerItem : SchedulerClient
    {
        public SampleSchedulerItem(ScheduleHistoryItem oItem): base()
        {
            this.ScheduleHistoryItem = oItem;
        }
        
        public override void DoWork()
        {
            try
            {
                // Perform required items for logging
                this.Progressing();

                // Add your custom code here

                // Show success
                this.ScheduleHistoryItem.Succeeded = true;
            }
            catch (Exception ex)
            {
                this.ScheduleHistoryItem.Succeeded = false;

                this.ScheduleHistoryItem.AddLogNote("EXCEPTION OCCURRED: " + ex.StackTrace);

                this.Errored(ref ex);

                DotNetNuke.Services.Exceptions.Exceptions.LogException(ex);
            }
        }
    }
}

Deployment

The easy way to deploy this in a non-commercial way is to put your class file into the App_Code directory in the root of your website.  If the App_Code folder doesn't exist, you can create it.  However, you really should package this up as a DLL and formally version and install it as any other extension.  If you do the latter, the code will live in the DLL you created and that DLL will end up in the Bin folder instead.

Using the Schedule Item

Now that your code is in the correct place, you'll need to tell the CMS to run it.  The first step to make this happen is to login as a superuser.  You'll know if you have done this correctly, because you'll see a Host menu in the control panel.  Switch to show the "advanced" menu items and select the Schedule view.

When you arrive at the next view, you'll see that a number of schedule items already exist.  You can manage these at any time to disable, enable, or change the frequency of them.  

Click the Add Item to Schedule button to add your new schedule item.

There's literally only a single required field here, but you should consider filling most of these out.  Doing so will only help over time, as you begin to forget the specific details of this schedule item.

The most important field here is the Full Class Name and Assembly field.  This will tell the CMS where your code lives and what to run.  Using the sample above, this value may look like this:

YourCompany.ScheduledItems.SampleSchedulerItem

If you compiled your class like you should, then this value may look like this instead, assuming that you named your DLL YourCompany.ScheduledItems.dll.

YourCompany.ScheduledItems, YourCompany.ScheduledItems.SampleSchedulerItem

An example of the sample schedule item filled out is shown below.

In the example above, there were some assumptions made, based upon the example we attempted to show.  

This is what it might look like if you had a schedule item that would copy your product catalog from one store to another.  It's friendly name should hopefully tell you that.

The next field should tell you that this is compiled code because of the value before the comma, and where the code lives in the product using the information after the comma.  Due to naming convention, it should still be clear that this code will copy products.

Next, the schedule will be enabled upon save.  If this is the first time creating the schedule item, the item will go into a queue and run immediately.  

The Frequency field tells the CMS how often you want for the schedule item to run.  You can run this as often or seldom as you'd like.  Just keep an eye on how long schedule items take to run.  You don't want to have a situation where the schedule item begins to run again before it's last run has completed.

The Retry field value will only be used if the schedule item doesn't run for any reason.

The Retain Schedule History value is important.  If you don't save the history or don't save enough of it, you won't be able to troubleshoot when or if something went wrong and how.