MOSS Timer Jobs - Create Your Own!

In previous versions of SharePoint (or other platforms), if you had some task you wanted to perform on a scheduled basis, you'd have to either create a console EXE and schedule it to run via Windows Task Scheduler (ala AT.EXE) or create a Windows Service that went to sleep for a period of time. In order to install (and maintain) these tasks, you had to have console access to your production SharePoint (or other app) servers... something IT or admins wouldn't easily hand out.

Addressing this issue, Microsoft has added something called timer jobs to Microsoft Office SharePoint Server (MOSS) 2007. Microsoft uses timer jobs to do things like dead web cleanup (purging unused sites from site collections) among others. To see what other timer jobs are out there, from Central Administration, click Operations and then Timer Job Definitions. Not only does Microsoft use timer jobs in MOSS, but you can create your own custom timer jobs to do your own scheduled tasks. What's nice about this is once your timer job has been installed (something you can easily do with a solution & a feature), you can view it's status through Central Administration and even disable/enable it... all without console access to your production servers! Another cool thing is that when your job runs, MOSS passes it the GUID of the content database for the site the job is registered with. You can use this GUID to obtain a reference to a content database, then a site collection, and finally a site within the collection (SPWeb).

How do you build one? Well, unfortunately the documentation is lacking here... there isn't a single article in the SDK talking about creating custom timer jobs and the necessary objects aren't well documented either.

Everything surrounds the Microsoft.SharePoint.Administration.SPJobDefinition object. Create a new class that inherits from SPJobDefinition, implement a few constructors and a single method: Execute(Guid). I created a simple timer job that (assuming it's associated with a WSS site created using the Team Site template and there's a Tasks list in the root of the site) creates a new task every 5 minutes when the job is enabled. Here's what the constructors look like ([update 1/11 12p] added a default empty constructor[/]): 

   1:  public TaskLoggerJob ()

   2:      : base(){

   3:  }

   4:  public TaskLoggerJob (string jobName, SPService service, SPServer server, SPJobLockType targetType)

   5:      : base(jobName, service, server, targetType) {

   6:  }

   7:  public TaskLoggerJob (string jobName, SPWebApplication webApplication)

   8:      : base(jobName, webApplication, null, SPJobLockType.ContentDatabase) {

   9:    this.Title = "Task Logger";

  10:  }

Now, after you build the assembly containing your custom timer job and add it to the GAC (a requirement), you need to associate it with a specific site, site collection, web application, or farm and specify a schedule for when it should run. Ideally I'd like to do this with STSADM.EXE, but no such command exists (custom command opportunity out there!). Another way is to do this through the object model. Because I want to minimize any console access requirements, I'll do this in a feature by implementing the FeatureActivated event. To do this, you create an instance of your job, set the schedule, and call update like so: 

   1:  // get a reference to our job in the GAC

   2:  TaskLoggerJob taskLoggerJob = new TaskLoggerJob("Task Logger", site.WebApplication);

   3:  // set the execution schedule 

   4:  SPMinuteSchedule schedule = new SPMinuteSchedule();

   5:  schedule.BeginSecond = 0;

   6:  schedule.EndSecond = 59;

   7:  schedule.Interval = 5;

   8:  taskLoggerJob.Schedule = schedule;

   9:  //update the job

  10:  taskLoggerJob.Update();

That's it! Course you should take this a step further by packaging all this up in a solution that will deploy the assembly to the GAC and install a feature. Then, upon activating the feature, it will associate the web with the timer job. Conversely, upon deactivating the feature, it removes the timer job. Very slick! 

» MOSS SDK: Microsoft.SharePoint.Administration.SPJobDefinition

[Update 2/1/2007 @ 10p] Due to the great number of comments and questions triggered by this post, I took the time to write a new article explaining in more detail, with sample code, how to create a custom timer job. Please review that article before asking any questions: Creating custom SharePoint Timer Jobs. I'm closing the comments on this post... please post all new comments ot the article linked here.

Technorati tags: sharepoint, moss, timer job

posted on Wednesday, January 10, 2007 10:25 PM

href="http://andrewconnell.com/blog/Services/Pingback.aspx" rel="pingback" />