Implementing Jobs - Revision history

Craig: Remove pre-4.x version references (4.0.0 is the oldest documented release)

2026-07-31T14:49:53Z

Remove pre-4.x version references (4.0.0 is the oldest documented release)

← Older revision		Revision as of 14:49, 31 July 2026
Line 3:		Line 3:
	We recommend you review this page fully before implementing your own jobs. Obsidian provides you features that are not available in other schedulers which greatly improve re-usability and help ensure reliable execution. Reviewing this page and considering all available features will help you make the best choices for your needs.		We recommend you review this page fully before implementing your own jobs. Obsidian provides you features that are not available in other schedulers which greatly improve re-usability and help ensure reliable execution. Reviewing this page and considering all available features will help you make the best choices for your needs.

	You can also look at examples in our convenience [[Built-in_Jobs\|Built-in Jobs]] that have been open-sourced under the [[https://opensource.org/license/mit/ MIT License]] ~~as of Obsidian 2.7.0~~. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.		You can also look at examples in our convenience [[Built-in_Jobs\|Built-in Jobs]] that have been open-sourced under the [[https://opensource.org/license/mit/ MIT License]]. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

	In addition, you can check out our [https://web.obsidianscheduler.com/obsidianapi/ Javadoc] which documents the features you'll need to write your own Obsidian jobs. We recommend you consult with the Javadoc in combination with this page to understand the best way to use Obsidian's job functionality.		In addition, you can check out our [https://web.obsidianscheduler.com/obsidianapi/ Javadoc] which documents the features you'll need to write your own Obsidian jobs. We recommend you consult with the Javadoc in combination with this page to understand the best way to use Obsidian's job functionality.
Line 126:		Line 126:
	public String name();		public String name();
	public boolean required();		public boolean required();
	public boolean requiredAtRuntime(); ~~// as of 3.7.0~~		public boolean requiredAtRuntime();
	public Type type() default Type.STRING;		public Type type() default Type.STRING;
	public boolean allowMultiple() default false;		public boolean allowMultiple() default false;
	public String defaultValue() default "";		public String defaultValue() default "";
	public Class<? extends ListProvider> listProvider() default StaticListProvider.class; ~~// as of 3.3.0~~		public Class<? extends ListProvider> listProvider() default StaticListProvider.class;
	public String[] listArgs() default {}; ~~// as of 3.3.0~~		public String[] listArgs() default {};
	public String description() default ""; // as of 4.0.2		public String description() default ""; // as of 4.0.2
	public String[] urls() default {}; //as of 4.9.0		public String[] urls() default {}; //as of 4.9.0
Line 140:		Line 140:
	''As of Obsidian 4.0.2'', a parameter can be associated with a <code>description</code> that is integrated with help information displayed in the user interface. This description is also returned in the API calls that return job parameter information.		''As of Obsidian 4.0.2'', a parameter can be associated with a <code>description</code> that is integrated with help information displayed in the user interface. This description is also returned in the API calls that return job parameter information.

	~~''As of Obsidian 3.7.0'', a~~ parameter can be defined as <code>requiredAtRuntime</code>. This allows the job to be configured without a parameter, but ensures a parameter value is set with one-time submissions. Of course, if it is configured with a parameter value, one-time submissions will not require a value.		A parameter can be defined as <code>requiredAtRuntime</code>. This allows the job to be configured without a parameter, but ensures a parameter value is set with one-time submissions. Of course, if it is configured with a parameter value, one-time submissions will not require a value.

	''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI's inline help for the parameter. This is useful for linking to additional documentation regarding your parameter.		''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI's inline help for the parameter. This is useful for linking to additional documentation regarding your parameter.
Line 148:		Line 148:
	== List Parameterization ==		== List Parameterization ==

	~~''As of Obsidian 3.3.0'', you~~ can directly specify a list of valid values within a <code>@Parameter</code> annotation by using the <code>listArgs</code> option. The [[Admin_Jobs\|job screen]] will then present the values for these parameters as a selection list. Note that if <code>required</code> is set to false, an empty value will automatically be included in the list.		You can directly specify a list of valid values within a <code>@Parameter</code> annotation by using the <code>listArgs</code> option. The [[Admin_Jobs\|job screen]] will then present the values for these parameters as a selection list. Note that if <code>required</code> is set to false, an empty value will automatically be included in the list.

	<pre>		<pre>
Line 175:		Line 175:
	=== Dynamic File Lists ===		=== Dynamic File Lists ===

	~~As of Obsidian 3.3.0, if~~ you wish to define a parameter which enumerates a file listing based on a server-side directory, you can use the built-in [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider]. It also marked with the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/ListProvider.DynamicListProvider.html DynamicListProvider] annotation explained below.		If you wish to define a parameter which enumerates a file listing based on a server-side directory, you can use the built-in [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider]. It also marked with the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/ListProvider.DynamicListProvider.html DynamicListProvider] annotation explained below.


Line 193:		Line 193:
	By default, all <code>@Configuration</code> annotations on the job class hierarchy are inherited by children and their parameters are combined. However, if a subclass defines a parameter with the same name as a parent class, the subclass version will override the parent version.		By default, all <code>@Configuration</code> annotations on the job class hierarchy are inherited by children and their parameters are combined. However, if a subclass defines a parameter with the same name as a parent class, the subclass version will override the parent version.

	~~As of Obsidian 3.0,~~ <code>@Configuration</code> ~~added~~ a <code>replaceInherited</code> attribute. If set to true, parent classes' <code>@Configuration</code> annotations are completely ignored, effectively replacing their parameter definitions completely.		The <code>@Configuration</code> annotation supports a <code>replaceInherited</code> attribute. If set to true, parent classes' <code>@Configuration</code> annotations are completely ignored, effectively replacing their parameter definitions completely.

	== Global Parameters ==		== Global Parameters ==

	Obsidian ~~2.5 introduced~~ [[Admin_Global_Parameters\|Global Parameters]]. These let you configure job parameters globally, and then simply import them into jobs as needed. Global parameters help avoid repeating the same configuration steps over and over, and can even be used to hide sensitive values from users, since they have separate access control in the admin web application.		Obsidian supports [[Admin_Global_Parameters\|Global Parameters]]. These let you configure job parameters globally, and then simply import them into jobs as needed. Global parameters help avoid repeating the same configuration steps over and over, and can even be used to hide sensitive values from users, since they have separate access control in the admin web application.

	By default, if a job parameter is configured with a value that is surrounded by double curly braces (e.g. <code>{{param}}</code>), then it is treated as a global parameter reference. When Obsidian sees a global parameter reference in this format during job execution, it imports all configured global parameters under the name (e.g. <code>param</code>) in place of the reference. Note that Obsidian does not support global parameter references embedded inside parameter values, since it does not perform text substitution - only parameter values containing only the global parameter reference will be replaced with the global parameter value.		By default, if a job parameter is configured with a value that is surrounded by double curly braces (e.g. <code>{{param}}</code>), then it is treated as a global parameter reference. When Obsidian sees a global parameter reference in this format during job execution, it imports all configured global parameters under the name (e.g. <code>param</code>) in place of the reference. Note that Obsidian does not support global parameter references embedded inside parameter values, since it does not perform text substitution - only parameter values containing only the global parameter reference will be replaced with the global parameter value.
Line 211:		Line 211:
	=== Global Substitution Mode ===		=== Global Substitution Mode ===

	~~''Available as of Obsidian 3.4.0''~~

	In some cases, you may wish to embed global parameters inside other parameters, rather than substitute them entirely. For example, when using a [[Built-in_Jobs#Script_Job\|ScriptFileJob]], you may wish to inject a global parameter value into an argument passed into a script as follows:		In some cases, you may wish to embed global parameters inside other parameters, rather than substitute them entirely. For example, when using a [[Built-in_Jobs#Script_Job\|ScriptFileJob]], you may wish to inject a global parameter value into an argument passed into a script as follows:
Line 289:		Line 288:
	context.saveJobResult(resultsParamName, oldResults + " Updated");		context.saveJobResult(resultsParamName, oldResults + " Updated");

	// ~~As of 2.2, you~~ can save multiple results at a time as a convenience.		// You can save multiple results at a time as a convenience.
	context.saveMultipleJobResults("file", Arrays.asList("first", "second"));		context.saveMultipleJobResults("file", Arrays.asList("first", "second"));

	// ~~As of 3.6, you~~ can replace job results.		// You can replace job results.
	context.replaceJobResult(resultsParamName, "replace old value");		context.replaceJobResult(resultsParamName, "replace old value");
	context.replaceMultipleJobResults("file", Arrays.asList("third", "fourth"));		context.replaceMultipleJobResults("file", Arrays.asList("third", "fourth"));
Line 353:		Line 352:
	[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableJob.html InterruptableJob Javadoc]		[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableJob.html InterruptableJob Javadoc]

	[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableContextJob.html InterruptableContextJob Javadoc] ~~(since 3.2)~~		[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableContextJob.html InterruptableContextJob Javadoc]

	~~As of Obsidian 1.5.1, it~~ is possible to '''terminate''' a running job on a best effort basis. ~~As of Obsidian 3.6.0,~~ [[Job_Forking\|Forked Jobs]] can also be interrupted.		It is possible to '''terminate''' a running job on a best effort basis. [[Job_Forking\|Forked Jobs]] can also be interrupted.

	In some exceptional cases, it may be necessary or desirable to force termination of a job. Since exposing this functionality for all jobs could result in unexpected and even dangerous results, Obsidian provides two Java interfaces that are used specifically for this function.		In some exceptional cases, it may be necessary or desirable to force termination of a job. Since exposing this functionality for all jobs could result in unexpected and even dangerous results, Obsidian provides two Java interfaces that are used specifically for this function.
Line 382:		Line 381:

	== JVM Forking ==		== JVM Forking ==
	~~Obsidian 3.0 introduced~~ [[Job_Forking\|Job Forking]] ~~which~~ runs each job in its own JVM instance which is started for each execution. This enables hot-swapping of JARs so that jobs can be updated without restarts. By default, this feature works on standalone instances, but other modes can be supported with minor customization.		[[Job_Forking\|Job Forking]] runs each job in its own JVM instance which is started for each execution. This enables hot-swapping of JARs so that jobs can be updated without restarts. By default, this feature works on standalone instances, but other modes can be supported with minor customization.

	= Classpath Scanning =		= Classpath Scanning =
Line 398:		Line 397:


			You can also configure how often Obsidian will check "packageScannerPrefix" for changes, which results in a re-scan of available jobs. This is done via the "classpathScanFrequency" parameter in the "Job" category in [[Admin_Scheduler Settings\|scheduler settings]].
	~~As of 3.0.1, you~~ can also configure how often Obsidian will check "packageScannerPrefix" for changes, which results in a re-scan of available jobs. This is done via the "classpathScanFrequency" parameter in the "Job" category in [[Admin_Scheduler Settings\|scheduler settings]].

	If you are using Spring and wish to integrate Obsidian and [[Spring_Integration\|Spring]], you will likely not need to use this distinct classpath scanning functionality, since jobs found in the Spring context will be available in the [[Admin_Jobs#Adding_.26_Editing_Jobs\|job edit screen]] automatically.		If you are using Spring and wish to integrate Obsidian and [[Spring_Integration\|Spring]], you will likely not need to use this distinct classpath scanning functionality, since jobs found in the Spring context will be available in the [[Admin_Jobs#Adding_.26_Editing_Jobs\|job edit screen]] automatically.

	= Initializing Jobs on Startup =		= Initializing Jobs on Startup =
	If you're interested in initializing your jobs into Obsidian on startup without having to write and execute code or manually configure them using the UI, you can use the [[Initializing and Restoring]] functionality ~~available as of Obsidian 3.0.0~~.		If you're interested in initializing your jobs into Obsidian on startup without having to write and execute code or manually configure them using the UI, you can use the [[Initializing and Restoring]] functionality.

	= Best Practices =		= Best Practices =

Craig at 19:58, 24 May 2023

2023-05-24T19:58:11Z

← Older revision		Revision as of 19:58, 24 May 2023
Line 12:		Line 12:
	[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.html SchedulableJob Javadoc]		[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.html SchedulableJob Javadoc]

	'''Note:''' If you need to set up a development environment to create Obsidian jobs, see the [[Implementing_Jobs#~~Classpath_for_Building_and_Deploying~~\|Classpath]] section.		'''Note:''' If you need to set up a development environment to create Obsidian jobs, see the [[Implementing_Jobs#Classpath_for_Building\|Classpath]] section.

	Implementing jobs in Obsidian is very straightforward for most cases. At its most basic, implementing a job simply requires implementing the <code>SchedulableJob</code> interface which has a single method, as shown below.<br/>		Implementing jobs in Obsidian is very straightforward for most cases. At its most basic, implementing a job simply requires implementing the <code>SchedulableJob</code> interface which has a single method, as shown below.<br/>
Line 365:		Line 365:
	It is possible that the job completes either successfully or with failure before the interrupt can proceed. If the interrupt proceeds, the job will be marked as '''Error''' and the interruption details will be made available for review in both the [[Admin_Job_Activity\|Job Activity]] and [[Admin_Logs\|Log]] views.		It is possible that the job completes either successfully or with failure before the interrupt can proceed. If the interrupt proceeds, the job will be marked as '''Error''' and the interruption details will be made available for review in both the [[Admin_Job_Activity\|Job Activity]] and [[Admin_Logs\|Log]] views.

	'''Note''': After invoking <code>void beforeInterrupt()</code>, Obsidian will invoke <code>Thread.interrupt()</code> to try to get the job to abort. Note that <code>Thread.interrupt()</code> does not forcibly terminate a thread in most cases, and it is up to the job itself to support aborting at an appropriate time when an interrupt is received. This [~~http~~://docs.oracle.com/javase/tutorial/essential/concurrency/interrupt.html tutorial] explains the details of thread interrupts.		'''Note''': After invoking <code>void beforeInterrupt()</code>, Obsidian will invoke <code>Thread.interrupt()</code> to try to get the job to abort. Note that <code>Thread.interrupt()</code> does not forcibly terminate a thread in most cases, and it is up to the job itself to support aborting at an appropriate time when an interrupt is received. This [https://docs.oracle.com/javase/tutorial/essential/concurrency/interrupt.html tutorial] explains the details of thread interrupts.

	= Classpath for Building =		= Classpath for Building =

Craig at 17:34, 3 May 2023

2023-05-03T17:34:49Z

Show changes

Craig at 16:49, 3 May 2023

2023-05-03T16:49:03Z

← Older revision		Revision as of 16:49, 3 May 2023
Line 3:		Line 3:
	We recommend you review this page fully before implementing your own jobs. Obsidian provides you features that are not available in other schedulers which greatly improve re-usability and help ensure reliable execution. Reviewing this page and considering all available features will help you make the best choices for your needs.		We recommend you review this page fully before implementing your own jobs. Obsidian provides you features that are not available in other schedulers which greatly improve re-usability and help ensure reliable execution. Reviewing this page and considering all available features will help you make the best choices for your needs.

	You can also look at examples in our convenience [[Built-in_Jobs\|Built-in Jobs]] that have been open-sourced under the [[~~http~~://opensource.org/~~licenses~~/~~MIT~~ MIT License]] as of Obsidian 2.7.0. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.		You can also look at examples in our convenience [[Built-in_Jobs\|Built-in Jobs]] that have been open-sourced under the [[https://opensource.org/license/mit/ MIT License]] as of Obsidian 2.7.0. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

	In addition, you can check out our [~~http~~://obsidianscheduler.com/obsidianapi/ Javadoc] which documents the features you'll need to write your own Obsidian jobs. We recommend you consult with the Javadoc in combination with this page to understand the best way to use Obsidian's job functionality.		In addition, you can check out our [https://web.obsidianscheduler.com/obsidianapi/ Javadoc] which documents the features you'll need to write your own Obsidian jobs. We recommend you consult with the Javadoc in combination with this page to understand the best way to use Obsidian's job functionality.

Carfey: /* Classpath Scanning */

2019-11-12T17:29:03Z

Classpath Scanning

← Older revision		Revision as of 17:29, 12 November 2019
Line 386:		Line 386:
	= Classpath Scanning =		= Classpath Scanning =

	Obsidian supports classpath scanning to find your jobs for display in the [[Admin_Jobs#Adding_.26_Editing_Jobs\|job edit screen]].		Obsidian supports classpath scanning to find your jobs for display in the [[Admin_Jobs#Adding_.26_Editing_Jobs\|job edit screen]]. If you deploy the scheduler separately from the web application, the scheduler node will scan its classpath for available jobs, and the web application will have access to these results.

	All classes that implement <code>com.carfey.ops.job.SchedulableJob</code> or use the <code>com.carfey.ops.job.SchedulableJob.Schedulable</code> and <code>com.carfey.ops.job.SchedulableJob.ScheduledRun</code> annotations will be included, provided they are on the classpath.		All classes that implement <code>com.carfey.ops.job.SchedulableJob</code> or use the <code>com.carfey.ops.job.SchedulableJob.Schedulable</code> and <code>com.carfey.ops.job.SchedulableJob.ScheduledRun</code> annotations will be included, provided they are on the classpath.

Craig: /* Parameterization */

2019-05-01T03:04:30Z

Parameterization

← Older revision		Revision as of 03:04, 1 May 2019
Line 134:		Line 134:
	public String description() default ""; // as of 4.0.2		public String description() default ""; // as of 4.0.2
	public String[] urls() default {}; //as of 4.9.0		public String[] urls() default {}; //as of 4.9.0
			public boolean requireUniqueSelection() default false; //as of 4.10.0
	}		}
	</pre>		</pre>
Line 142:		Line 143:

	''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI's inline help for the parameter. This is useful for linking to additional documentation regarding your parameter.		''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI's inline help for the parameter. This is useful for linking to additional documentation regarding your parameter.

			''As of Obsidian 4.10.0'', Parameters support validation of multiple values to be unique via <code>boolean requireUniqueSelection</code> which defaults to false. Only in play when <code>allowMultiple</code> is <code>true</code>.

	== List Parameterization ==		== List Parameterization ==

Craig: /* Parameterization */

2019-02-12T04:29:55Z

Parameterization

← Older revision		Revision as of 04:29, 12 February 2019
Line 141:		Line 141:
	''As of Obsidian 3.7.0'', a parameter can be defined as <code>requiredAtRuntime</code>. This allows the job to be configured without a parameter, but ensures a parameter value is set with one-time submissions. Of course, if it is configured with a parameter value, one-time submissions will not require a value.		''As of Obsidian 3.7.0'', a parameter can be defined as <code>requiredAtRuntime</code>. This allows the job to be configured without a parameter, but ensures a parameter value is set with one-time submissions. Of course, if it is configured with a parameter value, one-time submissions will not require a value.

	''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI. This is useful for linking to additional documentation regarding your parameter.		''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI's inline help for the parameter. This is useful for linking to additional documentation regarding your parameter.

	== List Parameterization ==		== List Parameterization ==

Craig: /* SchedulableJob Interface */

2019-02-12T04:29:33Z

SchedulableJob Interface

← Older revision		Revision as of 04:29, 12 February 2019
Line 51:		Line 51:

	'''As of Obsidian 4.3.0''', descriptions support [[Description_%26_Parameter_Formatting \| formatting]] for rendering in the UI.		'''As of Obsidian 4.3.0''', descriptions support [[Description_%26_Parameter_Formatting \| formatting]] for rendering in the UI.

			'''As of Obsidian 4.9.0''', Description supports providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI's inline help for the job. This is useful for linking to additional documentation regarding your job class.

	== Async Jobs ==		== Async Jobs ==

Craig: /* Parameterization */

2019-02-12T04:27:17Z

Parameterization

← Older revision		Revision as of 04:27, 12 February 2019
Line 94:		Line 94:

	'''As of Obsidian 4.3.0''', Parameter descriptions support [[Description_%26_Parameter_Formatting \| formatting]] for rendering in the UI.		'''As of Obsidian 4.3.0''', Parameter descriptions support [[Description_%26_Parameter_Formatting \| formatting]] for rendering in the UI.


	If you are running parameterized jobs, these parameters are very easy to access. Both defined and custom parameters are accessed in the same way. Example:		If you are running parameterized jobs, these parameters are very easy to access. Both defined and custom parameters are accessed in the same way. Example:
Line 130:		Line 129:
	public String defaultValue() default "";		public String defaultValue() default "";
	public Class<? extends ListProvider> listProvider() default StaticListProvider.class; // as of 3.3.0		public Class<? extends ListProvider> listProvider() default StaticListProvider.class; // as of 3.3.0
	String[] listArgs() default {}; // as of 3.3.0		public String[] listArgs() default {}; // as of 3.3.0
	public String description() default ""; // as of 4.0.2		public String description() default ""; // as of 4.0.2
			public String[] urls() default {}; //as of 4.9.0
	}		}
	</pre>		</pre>
Line 138:		Line 138:

	''As of Obsidian 3.7.0'', a parameter can be defined as <code>requiredAtRuntime</code>. This allows the job to be configured without a parameter, but ensures a parameter value is set with one-time submissions. Of course, if it is configured with a parameter value, one-time submissions will not require a value.		''As of Obsidian 3.7.0'', a parameter can be defined as <code>requiredAtRuntime</code>. This allows the job to be configured without a parameter, but ensures a parameter value is set with one-time submissions. Of course, if it is configured with a parameter value, one-time submissions will not require a value.

			''As of Obsidian 4.9.0'', Parameters support providing an optional array of <code>urls</code>. Any provided URLs are displayed in the UI. This is useful for linking to additional documentation regarding your parameter.

	== List Parameterization ==		== List Parameterization ==

Craig: /* Parameterization */

2019-01-09T15:33:44Z

Parameterization

← Older revision		Revision as of 15:33, 9 January 2019
Line 86:		Line 86:

	@Configuration(knownParameters={		@Configuration(knownParameters={
	@Parameter(name="url", required=true, type=Type.STRING, listArgs={"~~http~~://google.com","~~http~~://obsidianscheduler.com"}),		@Parameter(name="url", required=true, type=Type.STRING, listArgs={"https://google.com","https://obsidianscheduler.com"}),
	@Parameter(name="saveResultsParam", required=false, allowMultiple=true, type=Type.STRING),		@Parameter(name="saveResultsParam", required=false, allowMultiple=true, type=Type.STRING),
	@Parameter(name="compressResults", required=false, defaultValue="false", type=Type.BOOLEAN)		@Parameter(name="compressResults", required=false, defaultValue="false", type=Type.BOOLEAN)