CodeGuru content and product recommendations are editorially independent. We may make money when you click on links to our partners. Learn More.
Introduction
Microsoft Windows SharePoint Services (WSS) and its Portal version, Microsoft Office SharePoint Server (MOSS), carries out various automatic, scheduled jobs to realize repetitive tasks in a standard way. For example, the alerts and notifications engine scans new items added to a site in a timetabled way and sends emails to users. Additionally, information generated from the log files to make statistical analysis occurs in pre-determined time intervals.
The SharePoint Timed Jobs infrastructure takes care of the scheduled tasks needed to ensure proper functioning of the system. Timed Jobs run in the background and are based in the Microsoft SharePoint Timer service, which is always installed in the default setup of WSS and MOSS. Installed Timed Jobs can be configured from SharePoint’s Central Administration using the Command-Line administrator’s tool or programmed using the Object Model.
Timed Jobs can be set up to run immediately or in a time frame based on “one,” meaning a SharePoint Job can run each minute, day, or week but not, for example, every two hours or days. Another limitation is that it is impossible to schedule Jobs to run on relative time frames; for example, the second Monday of every month. A Timed Job requires a starting time, and the configured time frame determines the interval it will run at. The starting time can be an absolute time (at 12:00 am, for example) or a time range (between 8:00 and 9:00 am); in the first instance, the Job would require a few seconds to execute because the service needs to be initiated; in the second case, the Job will run at a random time within the range, giving the different servers in the farm the opportunity to progress at varied periods, balancing the load on the system.
Finally, the Timed Jobs system relies on the Gregorian calendar, based on a 24-hour clock. The user configures the initial time using the local time of the SharePoint server, and the system calculates the offset from the Universal Coordinate Time (UTC) to store it.
Using the SharePoint Administration Pages
The Central Administration of SharePoint provides the location to configure a specified Job. For instance, it is possible to set up “Use Confirmation and Deletion” of sites in a Portal: If there is no traffic in a site, the system sends a notification to the owner. If there is no confirmation of use, after a number of send notification without confirmation, the site can be configured to delete.
This is a characteristic use of Timed Jobs; the Job engine runs the process in a time-tabled way, detects whether a site has been approached, and compares the time span with the configured value. It then sends an email if necessary, and eventually, if unconfirmed, deletes the site. Figure 1 displays the Central Administration Page to configurate the procedure. In the example, the Timed Job has been scheduled to run every day at 12:00 am, and after 3 unanswered messages, the site is deleted.
Figure 1: Configuration of a Timed Job
For the general administration of all Jobs, the SharePoint Central Administration has “Timer job status” and “Timer job definitions” pages (in the Central Administration, under the “Operations,” “Global Configuration” section).
The “Timer job status” page provides information about the server: where the Job has run (it can be a separate entry for each server in a farm), the Status of the Job, Progress indication if the Job is still running, and the date when the Job ran for the first time.
The “Timer job definitions” page shows all the Timed Jobs defined in the system, the scope of the Job, and the schedule type (time frame). Each entry in the page is a link to a specific page, where it is possible to enable/disable the Job and to change its name.
Figure 2: Timer Job Definitions
Using the Command Line
The “stsadm” Administrators command-line application can be used to control certain Timed Jobs functionality. Unfortunately, there are no default commands to install or start/stop Timed Jobs, but there is a command to run all Jobs immediately and commands to reschedule a number of Jobs.
The command “execadmsvcjobs” executes all the configured Timed Jobs present in the system immediately, as an alternative to waiting for the expiration of the time frame. This command does not require any parameters; the syntax is:
stsadm -o execadmsvcjobs
Bear in mind that, as all Jobs commence at the same time, it may present a burden on SharePoint servers. Also, if the Windows SharePoint Services Timer service has been stopped for any reason, the aforementioned command may be used to manually run the Jobs in the Portal.
There are also SharePoint components that use a Timed Job and can be controlled using the command-line tool. For example, the commands “setpolicyschedule”, “setcontentdeploymentjobschedule”, and “setsitedirectoryscanschedule” are components that support the Timed Job infrastructure. Each of the commands accepts a “-schedule” parameter (named “recurrence string” or “schedule” in the help function of stsadm) that is a free string of the form:
"[Time frame] [Interval] between [value] and [value]"
For example:
“every 5 minutes between 0 and 59”
“hourly between 0 and 59”
“daily at 15:00:00”
“weekly between Fri 22:00 and Sun 06:00:00”
“yearly at Jan 1 15:00:00”
The syntax looks like this:
stsadm -o setsitedirectoryscanschedule -schedule "daily at 03:00:00"
Using the Object Model
The Object Model of SharePoint also enables developers to manage Timed Jobs. The classes SPJobDefinitionCollection and SPJobDefinition from the NameSpace Microsoft.SharePoint.Administration contain the methods and properties necessary to operate Timed Jobs.
The class SPJobDefinitionCollection contains the entire Timed Jobs selection of a SharePoint Web application, each of the type SPJobDefinition. The SPJobDefinition class contains the properties that define a Job (Name, Title, Version, and in which Server and WebApplication it is working, and so forth) and the methods to process it (Execute, Delete, Update). A special property, “Schedule”, of the type “SPJobDefinition.Schedule”, sees to the time frame for the Job.
To enumerate all the Jobs in an application, the following routine can be used in a command-line application to show the title, last run time, and type of each Job:
static void GetAllJobs()
{
SPSite mySite = new SPSite("http://ServerName");
foreach (SPJobDefinition oneJob in
mySite.WebApplication.JobDefinitions)
{
Console.WriteLine(oneJob.Title + " -" +
oneJob.LastRunTime.ToLongTimeString() + " - " +
oneJob.Schedule.GetType().ToString().Remove(0, 21));
}
}
Note that the string “Microsoft.SharePoint” has been stripped from the schedule type.
Figure 3: Output from Timed Jobs for the application href=”http://ServerName”, together with the Central Administration Page showing the same results
The routine loops through the Job definitions of the application, displaying various properties of each found Job. It is necessary to set a reference to Windows SharePoint Services (Microsoft.SharePoint.dll) and “using” directives to Microsoft.SharePoint and Microsoft.SharePoint.Administration.
The next routine adds a new Job Definition to the application:
static void CreateJob()
{
SPServer myServer = SPServer.Local;
SPSite mySite = new SPSite("http://ServerName");
SPWebApplication myApplication = mySite.WebApplication;
SPJobDefinitionCollection myJobsColl = myApplication.JobDefinitions;
SPJobDefinition myJob = new SPJobDefinition("FakeTestJob",
myApplication, myServer, SPJobLockType.Job);
myJob.Title = "Fake Test Job";
SPDailySchedule myDailySchedule = new SPDailySchedule();
myDailySchedule.BeginHour = 3;
myDailySchedule.BeginMinute = 0;
myDailySchedule.BeginSecond = 0;
myJob.Schedule = myDailySchedule;
myJobsColl.Add(myJob);
myApplication.Update();
Console.WriteLine("Job Installed");
}
