Obsidian Scheduler - User contributions [en]

Release Notes

2026-08-12T21:58:16Z

Craig: /* Bug Fixes */

Please review our [[Upgrading_Obsidian|Upgrade Instructions]].

Read about our [[Planned_Releases|Planned Releases]].

Looking for old release notes? See [[Release_Notes_-_Older_Releases|Release Notes - Older Releases]].

<div class="toclimit-2">__TOC__</div>

== Obsidian 7.0.2 ==

Released August 2026

=== Bug Fixes ===

* '''Scheduler startup on JDK 17''' — Fixed an issue where JDK 17 required Unsafe for GSON deserialization. Unsafe is globally disabled now.
* '''Startup / shutdown job modes on Postgres and SQL Server''' — Job column for modes was too short for some mode values.

== Obsidian 7.0.1 ==

Released August 2026

=== Bug Fixes ===

* Fixed site and hardware-linked licence verification on Obsidian 7.0.0. Workaround for 7.0.0 available on request.

== Obsidian 7.0.0 ==

Released July 2026

=== Features / Enhancements ===

* '''OAuth 2.0 / OIDC Single Sign-On''' — Obsidian now supports OAuth 2.0 / OIDC SSO authentication via [[Authenticator#OAuthAuthenticator_(OIDC_SSO)|OAuthAuthenticator]]. Configure any OIDC-compliant identity provider (Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC) as the login provider. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|OAuth/OIDC Authentication Properties]] for full configuration details.

* '''Bearer JWT authentication for the REST API''' — REST clients can now authenticate using a signed JWT access token in the ''Authorization: Bearer'' header. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|OAuth/OIDC Authentication Properties]] for configuration.

* '''Embedded Tomcat quick start''' — Evaluation and local runs use an Apache Tomcat 10.1.x embedded runtime (Jakarta Servlet). The bundled sample is '''h2-tomcat-quick-start.xml'''. ''webObsidian'' scripts start/stop embedded Tomcat for scheduler or admin-only profiles — see [[Installation_Guide#Deployment_options|Deployment options]] and [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].
** On Linux, embedded Tomcat packs also install optional user-level systemd and desktop integration — see [[Installation_Guide#Linux_desktop_and_systemd_integration|the installer option]] and [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

* '''Global parameter autocomplete and tooltips''' — While editing a job, typing ''{{'' in a parameter value opens suggestions for global parameter names (subject to visibility settings). On job view, hover over values containing ''Name'' to see resolved global values when your user's permissions allow. Administration screens for defining global parameters are unchanged. See [[Advanced_Configuration|Advanced Configuration]] for visibility settings.

* '''Install-time dependency resolution''' — The published installer download does not embed public open-source JARs. Libraries are fetched (or read from a pre-staged cache) when you run the installer. See [[Installation_Guide#Offline_or_restricted-network_install|Offline install]] for air-gapped preparation steps.

* '''Installer upgrade (IzPack 5)''' — Obsidian 7.0.0 ships an IzPack 5-based installer. GUI and headless installs behave as in Obsidian 6 for standard flows. Customers with saved Obsidian 6 automated install XML must run the migrate helper included in the download before headless install. See [[Upgrading_Obsidian#Migrating_saved_automated_install_XML_.28Obsidian_6_.E2.86.92_7.29|Upgrading Obsidian]].

* '''Modular Groovy and Flexmark libraries''' — Obsidian no longer ships '''apache-groovy-all-4.0.24.jar''' or '''flexmark-util-0.62.2.jar''' uber archives. Scripting and UI documentation rendering use the modular JAR sets documented in [[Advanced_Configuration#Dependent_Libraries|Dependent Libraries]].

=== Removals ===

* '''Remember Me login option removed''' — The Remember Me checkbox and associated session-cookie mechanism have been removed. The ''USER_COOKIE'' table and ''allowRememberMe'' system parameter are removed automatically during the upgrade to 7.0.0; no operator action is required.

=== Bug Fixes ===

* '''User logout''' - Fixed an issue where users were not fully logged out in certain session states.
* '''Job edit screen accessible to users with no roles''' — Users with no assigned roles could previously access the job edit screen but not make changes; this has been fixed.
* '''Firefox UI icons''' — Fixed icons not rendering correctly in Firefox.
* Jakarta emails sent with both text and HTML would drop HTML portion; this has been fixed.

== Obsidian 6.4.0 ==
Released December 2025

=== Enhancements ===
* New [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] and built in [[Admin_Job_Stats|UI]] and [[Embedded_API#List_Stats|Embedded API]] and [[REST_Endpoints#GET_a_list_of_job_execution_statistics|REST API]]

=== Bug Fixes ===

* Fixed issue preventing [[Admin_Jobs#Deleting|job deletion]] when resubmissions of failed executions existed. Bug existed in UI and APIs.
* Fixed UI styling issue for [[Admin_Jobs#Deleting|job deletion]] where checkbox label did not appear.

== Obsidian 6.3.3 ==
Released November 2025

=== Enhancements ===
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html LDAPAuthenticator] supports configurable check user active override - com.carfey.suite.security.LdapAuthenticator.checkActiveAttribute
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] visibility increased to protected to allow for functionality override in subclasses.

=== Bug Fixes ===

* Correct LdapAuthenticator case with delimited configuration where active check wasn't applied.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] javadoc added for isUserActive fully detailing the implementation.

== Obsidian 6.3.2 ==
Released October 2025

=== Enhancements ===
* Notification failures now trigger Dispatch category Error level event on first failure. For use in log alerts and Event Hooks.

=== Bug Fixes ===

* Notification failures no longer log on every failure reducing chatty failure logs.
* No-arg constructors added to multiple JSON serializable candidate POJOs missing them. Addresses GSON's workaround use of sun.misc.Unsafe.

== Obsidian 6.3.1 ==
Released August 2025

=== Bug Fixes ===

* Fix failure response codes on [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST health endpoint]]
* Fix automatic upgrade issue from 6.1.0 to any of 6.2.0, 6.2.1, 6.3.0
* Fix auth issue when [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA]] is enabled that allows REST access when account has been locked out due to MFA not being setup. [[Contact_the_Obsidian_Scheduler_Team|Contact us]] if you need workaround details for earlier versions.
* Fix native auth issue that allows REST access when account has been flagged as inactive.

== Obsidian 6.3.0 ==
Released July 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|~]]
* Annotation based job and chain configuration [[Initializing_and_Restoring#Annotation_Initialization|initialization]]
* Health endpoint with details for Job Queuer and Job Spawner - [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST API]] or Embedded API [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(java.lang.String) by hostname] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(long) by host id]
* JDBC URL construction from parts [[Advanced_Configuration#Database_Properties|host/port/databaseName/dbType/oracleSid]]

== Obsidian 6.2.1 ==
Released June 2025

=== Bug Fixes ===

* Certain recoveries greater than 24 hours using new day of month proximity patterns introduced in 6.2.0 would result in no jobs spawning.
* Migrations targeting 6.0.0 and greater that start earlier than 5.0.0 skip the 5.0.0 migration. Migrating to any 5.x version first and then to 6.0.0 or later works around this issue.

== Obsidian 6.2.0 ==
Released May 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|< > ≥ ≤]]
* Cron day of month expansion for [[Cron#Special_Character_Usage|weekday proximity]] using [[Cron#Examples|< > ≥ ≤]]
* [[Admin_Global_Parameters#Using_Global_Parameters_in_Jobs|Global Parameters]] reference in job edit page support mouseover/title display of actual value when permissions allow
* Host time displayed in [[Admin_Host_Status|hosts status]] in UI
* [[Admin_Job_Runtime_Preview|Runtime Preview]] optimizations for large date ranges in both UI and APIs.

=== Bug Fixes ===

* Combination of table prefix, sorting by clob column and Oracle metadata load failure no longer results in sql error. This occurred in the UI when viewing raw job history results and in API calls for job runtime results.

== Obsidian 6.1.1 ==
Released March 2025

=== Features / Enhancements ===

* [[Authenticator#Implementation_of_a_Custom_Authenticator|Authenticator]] supports optional <code>authenticateREST()</code> method.

=== Bug Fixes ===

* Native authentication REST logins do not apply 'last login' timestamps. Avoids noisy error that was appearing in logs.

== Obsidian 6.1.0 ==
Released March 2025

=== Features / Enhancements ===

* Native authentication now disables users after 4 invalid login attempts, either password or MFA code if applicable. Invalid attempts threshold is configurable.
* Native authentication last login datetime displayed on list user screen.
* Stronger licensing controls. Site and hardware licenses as of this version must be regenerated by Carfey Software and every 2 years. Contact us at licensing [[Image:atSymbol.png]] obsidianscheduler.com.

=== Bug Fixes ===

* Native authentication password complexity pattern properly created and no longer overwritten on restart.

== Obsidian 6.0.1 ==
Released February 2025

=== Features / Enhancements ===

* [[Built-in_Jobs#File_Archive_Job|File Archive Job]] and [[Built-in_Jobs#File_Scanner_Job|File Scanner Job]] both now support min/max file sizes and minimum age.

=== Bug Fixes ===

* Native authentication user updates now support long passwords.

== Obsidian 6.0.0 ==
Released December 27, 2024

=== Features / Enhancements ===

* Jakarta Servlet 5.0
** Servlet container for Web Admin must support Jakarta Servlet 5.0 (e.g. Tomcat 10, Jetty 11)
* [[Micronaut_Integration|Micronaut]] integration support
* [[Advanced_Configuration#Dependent_Libraries|Groovy 4]] support
* [[Advanced_Configuration#Properties.2FYaml_File|Yaml]] configuration support<ref>

If you are using automated installer files from previous releases, you will need to add an additional configuration item to choose between yaml and properties formats in UserInputPanel.0.
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.0">
<userInput>
......snip......
<entry key="config.format" value="yaml" />
OR
<entry key="config.format" value="properties" />
......snip......
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre></ref>
* Native authentication supports customizable [[Admin_Login#Password_Complexity|password complexity]] requirements
* XML support deprecated across the product including XML UI downloads, XML runner configurations and XML license leases.
** '''Starting January 1st 2027, XML license lease requests will stop being processed. All Obsidian instances running using internet-verified licenses (including licence key proxies) will be required to use release 6.0.0 or later as of January 1st 2027.'''
** Above noted XML support will be removed in the first Obsidian version released in 2027.
* License leases use JSON payloads.

== Obsidian 5.5.1 ==
Released December 16, 2024

=== Bug Fixes ===

* Admin only (no scheduler) UI no longer generates event hook errors while running nor during shutdown
* Quick start installer file no longer generates errors during installation
* A few small web UI enhancements

== Obsidian 5.5.0 ==
Released October 2024

=== Features / Enhancements ===

* Event Hooks management available in [[Admin_Host_Status#Event_Hook_Status|UI]], [[Embedded_API#Event_Hook_Resume_or_Pause|Embedded API]] and [[REST_Endpoints#POST_event_hook_pause_or_resume|REST API]].
* [[Installation_Guide#Additional_configuration_items|Installer]] supports custom add on configurations '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 5.5.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.17 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.18">
<userInput>
<entry key="extra.log4j2.properties.1" value=""/>
<entry key="extra.log4j2.properties.2" value=""/>
<entry key="extra.log4j2.properties.3" value=""/>
<entry key="extra.log4j2.properties.4" value=""/>
<entry key="extra.log4j2.properties.5" value=""/>
<entry key="extra.log4j2.properties.6" value=""/>
<entry key="extra.log4j2.properties.7" value=""/>
<entry key="extra.log4j2.properties.8" value=""/>
<entry key="extra.log4j2.properties.9" value=""/>
<entry key="extra.log4j2.properties.10" value=""/>
<entry key="extra.log4j2.properties.11" value=""/>
<entry key="extra.log4j2.properties.12" value=""/>
<entry key="extra.log4j2.properties.13" value=""/>
<entry key="extra.log4j2.properties.14" value=""/>
<entry key="extra.log4j2.properties.15" value=""/>
<entry key="extra.log4j2.properties.16" value=""/>
<entry key="extra.log4j2.properties.17" value=""/>
<entry key="extra.log4j2.properties.18" value=""/>
<entry key="extra.log4j2.properties.19" value=""/>
<entry key="extra.log4j2.properties.20" value=""/>
<entry key="extra.carfey.properties.1" value=""/>
<entry key="extra.carfey.properties.2" value=""/>
<entry key="extra.carfey.properties.3" value=""/>
<entry key="extra.carfey.properties.4" value=""/>
<entry key="extra.carfey.properties.5" value=""/>
<entry key="extra.carfey.properties.6" value=""/>
<entry key="extra.carfey.properties.7" value=""/>
<entry key="extra.carfey.properties.8" value=""/>
<entry key="extra.carfey.properties.9" value=""/>
<entry key="extra.carfey.properties.11" value=""/>
<entry key="extra.carfey.properties.10" value=""/>
<entry key="extra.carfey.properties.12" value=""/>
<entry key="extra.carfey.properties.13" value=""/>
<entry key="extra.carfey.properties.14" value=""/>
<entry key="extra.carfey.properties.15" value=""/>
<entry key="extra.carfey.properties.16" value=""/>
<entry key="extra.carfey.properties.17" value=""/>
<entry key="extra.carfey.properties.18" value=""/>
<entry key="extra.carfey.properties.19" value=""/>
<entry key="extra.carfey.properties.20" value=""/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>

=== Bug Fixes ===

* Certain Cron expressions that fail to generate text descriptions no longer impact scheduling.
* Text database columns were previously restricted to maximum length of MySQL implementation. Corrected to validate length via DB implementation.

== Obsidian 5.4.0 ==
Released June 2024

=== Features / Enhancements ===

* Event Hooks available in [[Embedded_API#List_Event_Hooks|Embedded API]] and [[REST_Endpoints#GET_event_hooks|REST API]].
* [[Advanced_Configuration#Dependent_Libraries|GSON library]] upgrade to support Java 21

=== Bug Fixes ===

* Oracle identifier no longer too long when using prefixes.

== Obsidian 5.3.0 ==
Released March 2024

=== Features / Enhancements ===

* New [[Admin_Host_Status#Event_Hook_Status| Event Hooks Status]] available in the UI.

=== Bug Fixes ===

* Some improvements throughout the [[Admin_Web_Application_Guide|Admin Web Application]] for autofocus of fields.
* Additional classes and interfaces added to [https://web.obsidianscheduler.com/obsidianapi/ javadoc].
* Some cleanup in [https://web.obsidianscheduler.com/obsidianapi/ javadoc] documenation.

== Obsidian 5.2.1 ==
Released January 2024

=== Features / Enhancements ===

* [[Built-in_Jobs#Maintenance_Jobs|Maintenance Jobs]] are now scheduled by default in new installations. Can be disabled via [[Advanced_Configuration#Miscellaneous_Properties|Configuration]] property.
* New [[Event_Hooks#Standard_Output.2FError_Streams_Event_Hook | Standard Output/Error Streams Event Hook]].

=== Bug Fixes ===

* Schedule descriptions are now updated after edits are applied in all UI screens and APIs.

== Obsidian 5.2.0 ==
Released December 2023

=== Features / Enhancements ===

* [[Cron]] & [[Cron#Recurrence|Recur]] patterns along with any use of [[Admin_Schedule_Aliases|Schedule Aliases]] now support plain language description of the patterns throughout the [[Admin_Web_Application_Guide|UI]], visible while hovering patterns, and in [[REST_Endpoints|REST]] and [[Embedded_API|Embedded]] API responses.
* All screens supporting UI exports now support JSON ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]], [[Admin_Custom_Calendars#Calendar_Listing|Calendars]])
* All screens supporting UI exports and search criteria and/or inline filters now include any specified search criteria and filter text in Excel, XML and JSON downloads ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]])
* Support for [[Installation_Guide#Choosing_Email_Support|Jakarta EE mail]] '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases and had email configured, you will need to add a new section of xml as of Obsidian 5.2.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.16 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.17">
<userInput>
<entry key="mail.type.selection" value="javax"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>
* New [[Event_Hooks#REST_Endpoint_Event_Hook|REST Endpoint Event Hook]]
* [[Key_Server_Proxy|Key Server proxy]] artifact obtained via web download during installation

=== Bug Fixes ===

* Time picker buttons (hour, minute, AM/PM) in [[Admin_Job_Activity#Filtering|Job Activity filtering]] no longer change other elements of the selected time.
* Cron pattern with [[Cron#Special_Character_Usage|LW]] and any other non-L value in day position no longer also incorrectly evaluates to last day.

== Obsidian 5.1.1 ==
Released June 2023

=== Bug Fixes ===

* [[Authenticator|Native authentication]] no longer fails when user deletes are attempted from the UI.
* Built in maintenance job [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup]] no longer leaves deletion candidate CHAIN SKIPPED records in the JOB_HISTORY table in rare circumstances.

== Obsidian 5.1.0 ==
Released April 2023

=== Features / Enhancements ===

* [[Admin_Schedule_Aliases#Schedule_Alias_Fragments|Schedule Aliases]] now support fragments for configuration-time substitutions.
* New convenience job [[Built-in_Jobs#Database_File_Export_Job|Database File Export Job]] for generating basic file extracts from database queries.
* New convenience job [[Built-in_Jobs#REST_Invocation_Job|REST Invocation Job]] for making simple REST calls and storing results.
* Performance improvements in job failure handling.

== Obsidian 5.0.4 ==
Released February 2022

=== Features / Enhancements ===
* Log4j2 2.17.1 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.1 RCE vulnerability] where attackers can modify log4j configuration.
* Restore missing default log4j2 configuration in installation artifacts.

== Obsidian 5.0.3 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.17.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.0 DOS vulnerability]
* Fix native login issue showing as inactive on some databases.

== Obsidian 5.0.2 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.16.0 as permanent fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.16.0 RCE vulnerability]

== Obsidian 5.0.1 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.15.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.15.0 RCE vulnerability]

=== Bug Fixes ===
* Fix sporadic native login issue on some databases.
* Formatting fix in quick installer file

== Obsidian 5.0.0 ==
Released August 2021.

=== Features / Enhancements ===
* Java 11 (minimum Java version)
* [[Admin_Schedule_Aliases|Schedule Aliases]] including support in [[REST_Endpoints#Schedule_Alias_Endpoints|REST API]] and [[Embedded_API#ScheduleAliasManager_API|Embedded API]]
* [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA Support]] for UI logins
* New [[Admin_User_Management#User_Rights|Author and Operator]] roles
* Convention-based role permissions by [[Admin_User_Management#Job_Folder_Rights|root job folder]] for Write, Author and Operator.<ref>
There is a possibility of a breaking change to Embedded or REST API use due to the need to change the [[Embedded_API#Enumerations|User Role enumeration]] from a Java enum to an enum-style class to support this feature. Bringing in the upgraded Obsidian library and compiling should reveal any such broken use of these enumerations. Needed changes should be minor and self-explanatory.</ref>
* Bundled Jetty 10.0.2
* Legacy Embedded API (from Obsidian 1.5) dropped
* Signal handler disabled by default. Enabled only via [[Advanced_Configuration#Miscellaneous_Properties|configuration]].
* Many [[Advanced_Configuration#Dependent_Libraries|library upgrades]].
* UI javascript library updates.

== Footnotes ==
<references/>

Release Notes

2026-08-12T21:57:42Z

Craig: Wiki update

Please review our [[Upgrading_Obsidian|Upgrade Instructions]].

Read about our [[Planned_Releases|Planned Releases]].

Looking for old release notes? See [[Release_Notes_-_Older_Releases|Release Notes - Older Releases]].

<div class="toclimit-2">__TOC__</div>

== Obsidian 7.0.2 ==

Released August 2026

=== Bug Fixes ===

* '''Scheduler startup on JDK 17''' — Fixed an issue where JDK 17 required Unsafe for GSON deserialization. Unsafe is globally disabled now.
* '''Startup / shutdown job modes on Postgres and SQL Server''' — Job column for modes was too short some values.

== Obsidian 7.0.1 ==

Released August 2026

=== Bug Fixes ===

* Fixed site and hardware-linked licence verification on Obsidian 7.0.0. Workaround for 7.0.0 available on request.

== Obsidian 7.0.0 ==

Released July 2026

=== Features / Enhancements ===

* '''OAuth 2.0 / OIDC Single Sign-On''' — Obsidian now supports OAuth 2.0 / OIDC SSO authentication via [[Authenticator#OAuthAuthenticator_(OIDC_SSO)|OAuthAuthenticator]]. Configure any OIDC-compliant identity provider (Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC) as the login provider. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|OAuth/OIDC Authentication Properties]] for full configuration details.

* '''Bearer JWT authentication for the REST API''' — REST clients can now authenticate using a signed JWT access token in the ''Authorization: Bearer'' header. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|OAuth/OIDC Authentication Properties]] for configuration.

* '''Embedded Tomcat quick start''' — Evaluation and local runs use an Apache Tomcat 10.1.x embedded runtime (Jakarta Servlet). The bundled sample is '''h2-tomcat-quick-start.xml'''. ''webObsidian'' scripts start/stop embedded Tomcat for scheduler or admin-only profiles — see [[Installation_Guide#Deployment_options|Deployment options]] and [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].
** On Linux, embedded Tomcat packs also install optional user-level systemd and desktop integration — see [[Installation_Guide#Linux_desktop_and_systemd_integration|the installer option]] and [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

* '''Global parameter autocomplete and tooltips''' — While editing a job, typing ''{{'' in a parameter value opens suggestions for global parameter names (subject to visibility settings). On job view, hover over values containing ''Name'' to see resolved global values when your user's permissions allow. Administration screens for defining global parameters are unchanged. See [[Advanced_Configuration|Advanced Configuration]] for visibility settings.

* '''Install-time dependency resolution''' — The published installer download does not embed public open-source JARs. Libraries are fetched (or read from a pre-staged cache) when you run the installer. See [[Installation_Guide#Offline_or_restricted-network_install|Offline install]] for air-gapped preparation steps.

* '''Installer upgrade (IzPack 5)''' — Obsidian 7.0.0 ships an IzPack 5-based installer. GUI and headless installs behave as in Obsidian 6 for standard flows. Customers with saved Obsidian 6 automated install XML must run the migrate helper included in the download before headless install. See [[Upgrading_Obsidian#Migrating_saved_automated_install_XML_.28Obsidian_6_.E2.86.92_7.29|Upgrading Obsidian]].

* '''Modular Groovy and Flexmark libraries''' — Obsidian no longer ships '''apache-groovy-all-4.0.24.jar''' or '''flexmark-util-0.62.2.jar''' uber archives. Scripting and UI documentation rendering use the modular JAR sets documented in [[Advanced_Configuration#Dependent_Libraries|Dependent Libraries]].

=== Removals ===

* '''Remember Me login option removed''' — The Remember Me checkbox and associated session-cookie mechanism have been removed. The ''USER_COOKIE'' table and ''allowRememberMe'' system parameter are removed automatically during the upgrade to 7.0.0; no operator action is required.

=== Bug Fixes ===

* '''User logout''' - Fixed an issue where users were not fully logged out in certain session states.
* '''Job edit screen accessible to users with no roles''' — Users with no assigned roles could previously access the job edit screen but not make changes; this has been fixed.
* '''Firefox UI icons''' — Fixed icons not rendering correctly in Firefox.
* Jakarta emails sent with both text and HTML would drop HTML portion; this has been fixed.

== Obsidian 6.4.0 ==
Released December 2025

=== Enhancements ===
* New [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] and built in [[Admin_Job_Stats|UI]] and [[Embedded_API#List_Stats|Embedded API]] and [[REST_Endpoints#GET_a_list_of_job_execution_statistics|REST API]]

=== Bug Fixes ===

* Fixed issue preventing [[Admin_Jobs#Deleting|job deletion]] when resubmissions of failed executions existed. Bug existed in UI and APIs.
* Fixed UI styling issue for [[Admin_Jobs#Deleting|job deletion]] where checkbox label did not appear.

== Obsidian 6.3.3 ==
Released November 2025

=== Enhancements ===
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html LDAPAuthenticator] supports configurable check user active override - com.carfey.suite.security.LdapAuthenticator.checkActiveAttribute
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] visibility increased to protected to allow for functionality override in subclasses.

=== Bug Fixes ===

* Correct LdapAuthenticator case with delimited configuration where active check wasn't applied.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] javadoc added for isUserActive fully detailing the implementation.

== Obsidian 6.3.2 ==
Released October 2025

=== Enhancements ===
* Notification failures now trigger Dispatch category Error level event on first failure. For use in log alerts and Event Hooks.

=== Bug Fixes ===

* Notification failures no longer log on every failure reducing chatty failure logs.
* No-arg constructors added to multiple JSON serializable candidate POJOs missing them. Addresses GSON's workaround use of sun.misc.Unsafe.

== Obsidian 6.3.1 ==
Released August 2025

=== Bug Fixes ===

* Fix failure response codes on [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST health endpoint]]
* Fix automatic upgrade issue from 6.1.0 to any of 6.2.0, 6.2.1, 6.3.0
* Fix auth issue when [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA]] is enabled that allows REST access when account has been locked out due to MFA not being setup. [[Contact_the_Obsidian_Scheduler_Team|Contact us]] if you need workaround details for earlier versions.
* Fix native auth issue that allows REST access when account has been flagged as inactive.

== Obsidian 6.3.0 ==
Released July 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|~]]
* Annotation based job and chain configuration [[Initializing_and_Restoring#Annotation_Initialization|initialization]]
* Health endpoint with details for Job Queuer and Job Spawner - [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST API]] or Embedded API [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(java.lang.String) by hostname] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(long) by host id]
* JDBC URL construction from parts [[Advanced_Configuration#Database_Properties|host/port/databaseName/dbType/oracleSid]]

== Obsidian 6.2.1 ==
Released June 2025

=== Bug Fixes ===

* Certain recoveries greater than 24 hours using new day of month proximity patterns introduced in 6.2.0 would result in no jobs spawning.
* Migrations targeting 6.0.0 and greater that start earlier than 5.0.0 skip the 5.0.0 migration. Migrating to any 5.x version first and then to 6.0.0 or later works around this issue.

== Obsidian 6.2.0 ==
Released May 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|< > ≥ ≤]]
* Cron day of month expansion for [[Cron#Special_Character_Usage|weekday proximity]] using [[Cron#Examples|< > ≥ ≤]]
* [[Admin_Global_Parameters#Using_Global_Parameters_in_Jobs|Global Parameters]] reference in job edit page support mouseover/title display of actual value when permissions allow
* Host time displayed in [[Admin_Host_Status|hosts status]] in UI
* [[Admin_Job_Runtime_Preview|Runtime Preview]] optimizations for large date ranges in both UI and APIs.

=== Bug Fixes ===

* Combination of table prefix, sorting by clob column and Oracle metadata load failure no longer results in sql error. This occurred in the UI when viewing raw job history results and in API calls for job runtime results.

== Obsidian 6.1.1 ==
Released March 2025

=== Features / Enhancements ===

* [[Authenticator#Implementation_of_a_Custom_Authenticator|Authenticator]] supports optional <code>authenticateREST()</code> method.

=== Bug Fixes ===

* Native authentication REST logins do not apply 'last login' timestamps. Avoids noisy error that was appearing in logs.

== Obsidian 6.1.0 ==
Released March 2025

=== Features / Enhancements ===

* Native authentication now disables users after 4 invalid login attempts, either password or MFA code if applicable. Invalid attempts threshold is configurable.
* Native authentication last login datetime displayed on list user screen.
* Stronger licensing controls. Site and hardware licenses as of this version must be regenerated by Carfey Software and every 2 years. Contact us at licensing [[Image:atSymbol.png]] obsidianscheduler.com.

=== Bug Fixes ===

* Native authentication password complexity pattern properly created and no longer overwritten on restart.

== Obsidian 6.0.1 ==
Released February 2025

=== Features / Enhancements ===

* [[Built-in_Jobs#File_Archive_Job|File Archive Job]] and [[Built-in_Jobs#File_Scanner_Job|File Scanner Job]] both now support min/max file sizes and minimum age.

=== Bug Fixes ===

* Native authentication user updates now support long passwords.

== Obsidian 6.0.0 ==
Released December 27, 2024

=== Features / Enhancements ===

* Jakarta Servlet 5.0
** Servlet container for Web Admin must support Jakarta Servlet 5.0 (e.g. Tomcat 10, Jetty 11)
* [[Micronaut_Integration|Micronaut]] integration support
* [[Advanced_Configuration#Dependent_Libraries|Groovy 4]] support
* [[Advanced_Configuration#Properties.2FYaml_File|Yaml]] configuration support<ref>

If you are using automated installer files from previous releases, you will need to add an additional configuration item to choose between yaml and properties formats in UserInputPanel.0.
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.0">
<userInput>
......snip......
<entry key="config.format" value="yaml" />
OR
<entry key="config.format" value="properties" />
......snip......
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre></ref>
* Native authentication supports customizable [[Admin_Login#Password_Complexity|password complexity]] requirements
* XML support deprecated across the product including XML UI downloads, XML runner configurations and XML license leases.
** '''Starting January 1st 2027, XML license lease requests will stop being processed. All Obsidian instances running using internet-verified licenses (including licence key proxies) will be required to use release 6.0.0 or later as of January 1st 2027.'''
** Above noted XML support will be removed in the first Obsidian version released in 2027.
* License leases use JSON payloads.

== Obsidian 5.5.1 ==
Released December 16, 2024

=== Bug Fixes ===

* Admin only (no scheduler) UI no longer generates event hook errors while running nor during shutdown
* Quick start installer file no longer generates errors during installation
* A few small web UI enhancements

== Obsidian 5.5.0 ==
Released October 2024

=== Features / Enhancements ===

* Event Hooks management available in [[Admin_Host_Status#Event_Hook_Status|UI]], [[Embedded_API#Event_Hook_Resume_or_Pause|Embedded API]] and [[REST_Endpoints#POST_event_hook_pause_or_resume|REST API]].
* [[Installation_Guide#Additional_configuration_items|Installer]] supports custom add on configurations '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 5.5.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.17 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.18">
<userInput>
<entry key="extra.log4j2.properties.1" value=""/>
<entry key="extra.log4j2.properties.2" value=""/>
<entry key="extra.log4j2.properties.3" value=""/>
<entry key="extra.log4j2.properties.4" value=""/>
<entry key="extra.log4j2.properties.5" value=""/>
<entry key="extra.log4j2.properties.6" value=""/>
<entry key="extra.log4j2.properties.7" value=""/>
<entry key="extra.log4j2.properties.8" value=""/>
<entry key="extra.log4j2.properties.9" value=""/>
<entry key="extra.log4j2.properties.10" value=""/>
<entry key="extra.log4j2.properties.11" value=""/>
<entry key="extra.log4j2.properties.12" value=""/>
<entry key="extra.log4j2.properties.13" value=""/>
<entry key="extra.log4j2.properties.14" value=""/>
<entry key="extra.log4j2.properties.15" value=""/>
<entry key="extra.log4j2.properties.16" value=""/>
<entry key="extra.log4j2.properties.17" value=""/>
<entry key="extra.log4j2.properties.18" value=""/>
<entry key="extra.log4j2.properties.19" value=""/>
<entry key="extra.log4j2.properties.20" value=""/>
<entry key="extra.carfey.properties.1" value=""/>
<entry key="extra.carfey.properties.2" value=""/>
<entry key="extra.carfey.properties.3" value=""/>
<entry key="extra.carfey.properties.4" value=""/>
<entry key="extra.carfey.properties.5" value=""/>
<entry key="extra.carfey.properties.6" value=""/>
<entry key="extra.carfey.properties.7" value=""/>
<entry key="extra.carfey.properties.8" value=""/>
<entry key="extra.carfey.properties.9" value=""/>
<entry key="extra.carfey.properties.11" value=""/>
<entry key="extra.carfey.properties.10" value=""/>
<entry key="extra.carfey.properties.12" value=""/>
<entry key="extra.carfey.properties.13" value=""/>
<entry key="extra.carfey.properties.14" value=""/>
<entry key="extra.carfey.properties.15" value=""/>
<entry key="extra.carfey.properties.16" value=""/>
<entry key="extra.carfey.properties.17" value=""/>
<entry key="extra.carfey.properties.18" value=""/>
<entry key="extra.carfey.properties.19" value=""/>
<entry key="extra.carfey.properties.20" value=""/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>

=== Bug Fixes ===

* Certain Cron expressions that fail to generate text descriptions no longer impact scheduling.
* Text database columns were previously restricted to maximum length of MySQL implementation. Corrected to validate length via DB implementation.

== Obsidian 5.4.0 ==
Released June 2024

=== Features / Enhancements ===

* Event Hooks available in [[Embedded_API#List_Event_Hooks|Embedded API]] and [[REST_Endpoints#GET_event_hooks|REST API]].
* [[Advanced_Configuration#Dependent_Libraries|GSON library]] upgrade to support Java 21

=== Bug Fixes ===

* Oracle identifier no longer too long when using prefixes.

== Obsidian 5.3.0 ==
Released March 2024

=== Features / Enhancements ===

* New [[Admin_Host_Status#Event_Hook_Status| Event Hooks Status]] available in the UI.

=== Bug Fixes ===

* Some improvements throughout the [[Admin_Web_Application_Guide|Admin Web Application]] for autofocus of fields.
* Additional classes and interfaces added to [https://web.obsidianscheduler.com/obsidianapi/ javadoc].
* Some cleanup in [https://web.obsidianscheduler.com/obsidianapi/ javadoc] documenation.

== Obsidian 5.2.1 ==
Released January 2024

=== Features / Enhancements ===

* [[Built-in_Jobs#Maintenance_Jobs|Maintenance Jobs]] are now scheduled by default in new installations. Can be disabled via [[Advanced_Configuration#Miscellaneous_Properties|Configuration]] property.
* New [[Event_Hooks#Standard_Output.2FError_Streams_Event_Hook | Standard Output/Error Streams Event Hook]].

=== Bug Fixes ===

* Schedule descriptions are now updated after edits are applied in all UI screens and APIs.

== Obsidian 5.2.0 ==
Released December 2023

=== Features / Enhancements ===

* [[Cron]] & [[Cron#Recurrence|Recur]] patterns along with any use of [[Admin_Schedule_Aliases|Schedule Aliases]] now support plain language description of the patterns throughout the [[Admin_Web_Application_Guide|UI]], visible while hovering patterns, and in [[REST_Endpoints|REST]] and [[Embedded_API|Embedded]] API responses.
* All screens supporting UI exports now support JSON ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]], [[Admin_Custom_Calendars#Calendar_Listing|Calendars]])
* All screens supporting UI exports and search criteria and/or inline filters now include any specified search criteria and filter text in Excel, XML and JSON downloads ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]])
* Support for [[Installation_Guide#Choosing_Email_Support|Jakarta EE mail]] '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases and had email configured, you will need to add a new section of xml as of Obsidian 5.2.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.16 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.17">
<userInput>
<entry key="mail.type.selection" value="javax"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>
* New [[Event_Hooks#REST_Endpoint_Event_Hook|REST Endpoint Event Hook]]
* [[Key_Server_Proxy|Key Server proxy]] artifact obtained via web download during installation

=== Bug Fixes ===

* Time picker buttons (hour, minute, AM/PM) in [[Admin_Job_Activity#Filtering|Job Activity filtering]] no longer change other elements of the selected time.
* Cron pattern with [[Cron#Special_Character_Usage|LW]] and any other non-L value in day position no longer also incorrectly evaluates to last day.

== Obsidian 5.1.1 ==
Released June 2023

=== Bug Fixes ===

* [[Authenticator|Native authentication]] no longer fails when user deletes are attempted from the UI.
* Built in maintenance job [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup]] no longer leaves deletion candidate CHAIN SKIPPED records in the JOB_HISTORY table in rare circumstances.

== Obsidian 5.1.0 ==
Released April 2023

=== Features / Enhancements ===

* [[Admin_Schedule_Aliases#Schedule_Alias_Fragments|Schedule Aliases]] now support fragments for configuration-time substitutions.
* New convenience job [[Built-in_Jobs#Database_File_Export_Job|Database File Export Job]] for generating basic file extracts from database queries.
* New convenience job [[Built-in_Jobs#REST_Invocation_Job|REST Invocation Job]] for making simple REST calls and storing results.
* Performance improvements in job failure handling.

== Obsidian 5.0.4 ==
Released February 2022

=== Features / Enhancements ===
* Log4j2 2.17.1 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.1 RCE vulnerability] where attackers can modify log4j configuration.
* Restore missing default log4j2 configuration in installation artifacts.

== Obsidian 5.0.3 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.17.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.0 DOS vulnerability]
* Fix native login issue showing as inactive on some databases.

== Obsidian 5.0.2 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.16.0 as permanent fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.16.0 RCE vulnerability]

== Obsidian 5.0.1 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.15.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.15.0 RCE vulnerability]

=== Bug Fixes ===
* Fix sporadic native login issue on some databases.
* Formatting fix in quick installer file

== Obsidian 5.0.0 ==
Released August 2021.

=== Features / Enhancements ===
* Java 11 (minimum Java version)
* [[Admin_Schedule_Aliases|Schedule Aliases]] including support in [[REST_Endpoints#Schedule_Alias_Endpoints|REST API]] and [[Embedded_API#ScheduleAliasManager_API|Embedded API]]
* [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA Support]] for UI logins
* New [[Admin_User_Management#User_Rights|Author and Operator]] roles
* Convention-based role permissions by [[Admin_User_Management#Job_Folder_Rights|root job folder]] for Write, Author and Operator.<ref>
There is a possibility of a breaking change to Embedded or REST API use due to the need to change the [[Embedded_API#Enumerations|User Role enumeration]] from a Java enum to an enum-style class to support this feature. Bringing in the upgraded Obsidian library and compiling should reveal any such broken use of these enumerations. Needed changes should be minor and self-explanatory.</ref>
* Bundled Jetty 10.0.2
* Legacy Embedded API (from Obsidian 1.5) dropped
* Signal handler disabled by default. Enabled only via [[Advanced_Configuration#Miscellaneous_Properties|configuration]].
* Many [[Advanced_Configuration#Dependent_Libraries|library upgrades]].
* UI javascript library updates.

== Footnotes ==
<references/>

Main Page

2026-08-12T21:57:34Z

Craig: Wiki update

'''[[Obsidian]]''' is a fully-featured Java-based scheduling application which supports load balancing, failover and job workflow. It is designed for [[Deployment Diagram|high availability]], and it is specially built for demanding scheduling environments.

'''[[Release_Notes#Obsidian_7.0.2|Version 7.0.2]]''' is the latest release, and was released in August 2026.

Check out '''[[Getting Started]]''' if you are looking to set up Obsidian.

The '''[[User Guide]]''' will provide all the information you need to use all of Obsidian's functionality, and provides a quick view of the features Obsidian supports.

Our '''[[FAQ]]''' is also worth checking out if you have questions about Obsidian or want more context about what it does.

== Full Administration Capabilities ==

Obsidian features a rich administration web interface, allowing easy monitoring and management. See the '''[[Admin Web Application Guide]]''' for details.

[[Image:ObsidianNav 4.0.png]]

Installation Guide

2026-08-02T02:26:32Z

Craig: /* Offline or restricted-network install */

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.x.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== SAML 2.0 Configuration ====

If you selected '''SAML 2.0''' as the authentication type, the installer displays additional panels that configure the Service Provider identity, SAML signing credentials, federation metadata, attribute options, and group→role mapping.

===== Service Provider =====

* '''SP Entity ID''' — HTTPS URI registered as the SAML SP entity (must match IdP registrations).
* '''Assertion Consumer Service URL''' — HTTPS ACS endpoint where SAML responses arrive (HTTP-POST); aligns with the ACS in ''/saml/metadata''.
* '''SP Single Logout Service URL''' — Optional HTTPS URL for IdP-initiated SLO when logout mode targets IdP-mediated logout.
* '''SSO button label''' — Required label shown on '''Sign in with …'''.
* '''Logout mode''' — '''Local''' (Obsidian-only) or '''IdP / SLO''' (participates in SAML single logout when advertised).
* '''Post-logout redirect URI''' — Optional HTTPS landing URI after ''LogoutResponse''.
* '''Keystore path / alias / passwords''' — Required when signing SAML requests (password field is dual-entry validated).
* '''Sign SAML authentication requests''' — Toggle (installer default '''true''').
* '''Require signed SAML assertions''' — Toggle (recommended '''true''' for production).

===== Identity Provider =====

Choose the IdP type: Microsoft Entra ID (Azure AD), AD FS (on-premises), Okta, Auth0, or Generic SAML 2.0 (covers Keycloak ''/protocol/saml/descriptor'', Ping, Google Workspace, and similar). Follow-on screens seed example metadata URLs and default attribute names.

Provide '''either''' an HTTPS federation metadata URL '''or''' a local federation XML absolute path — choose exactly one. Later panels cover attribute options (''friendlyName'', ''valuePath'', ''stripPrefix'', ''attribute.user'', ''attribute.displayName'', ''ForceAuthn'', ''RequestedAuthnContext'', NameID format).

===== Group → Role Mapping =====

The closing panels map IdP group attribute values to Obsidian roles, including '''Require role assignment''' (default yes) and optional ''dynamicRole.prefix'' / ''suffix''. At least one mapping to the '''Admin''' role is required. See [[Advanced_Configuration#SAML_Authentication_Properties|SAML Authentication Properties]] for the full property reference.

===== SP metadata artefacts =====

During install the tooling writes '''sp-metadata.xml''' under the Obsidian deployment directory; the same metadata is available live at '''/saml/metadata''' after startup. Register whichever artefact your IdP admin prefers.

===== Before you complete install =====

* Ensure ACS and Entity ID '''https''' URLs are reachable from IdPs (align with reverse proxies).
* For Entra '''150+''' group memberships in SAML assertions, expect attribute suppression — filter groups or map assigned app roles instead. (OIDC uses a '''200''' group threshold; the numbers differ by protocol.)

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.x.x resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.x.x.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.x.x.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.x.x.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Installation Guide

2026-08-02T02:26:07Z

Craig: /* Offline or restricted-network install */

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.x.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== SAML 2.0 Configuration ====

If you selected '''SAML 2.0''' as the authentication type, the installer displays additional panels that configure the Service Provider identity, SAML signing credentials, federation metadata, attribute options, and group→role mapping.

===== Service Provider =====

* '''SP Entity ID''' — HTTPS URI registered as the SAML SP entity (must match IdP registrations).
* '''Assertion Consumer Service URL''' — HTTPS ACS endpoint where SAML responses arrive (HTTP-POST); aligns with the ACS in ''/saml/metadata''.
* '''SP Single Logout Service URL''' — Optional HTTPS URL for IdP-initiated SLO when logout mode targets IdP-mediated logout.
* '''SSO button label''' — Required label shown on '''Sign in with …'''.
* '''Logout mode''' — '''Local''' (Obsidian-only) or '''IdP / SLO''' (participates in SAML single logout when advertised).
* '''Post-logout redirect URI''' — Optional HTTPS landing URI after ''LogoutResponse''.
* '''Keystore path / alias / passwords''' — Required when signing SAML requests (password field is dual-entry validated).
* '''Sign SAML authentication requests''' — Toggle (installer default '''true''').
* '''Require signed SAML assertions''' — Toggle (recommended '''true''' for production).

===== Identity Provider =====

Choose the IdP type: Microsoft Entra ID (Azure AD), AD FS (on-premises), Okta, Auth0, or Generic SAML 2.0 (covers Keycloak ''/protocol/saml/descriptor'', Ping, Google Workspace, and similar). Follow-on screens seed example metadata URLs and default attribute names.

Provide '''either''' an HTTPS federation metadata URL '''or''' a local federation XML absolute path — choose exactly one. Later panels cover attribute options (''friendlyName'', ''valuePath'', ''stripPrefix'', ''attribute.user'', ''attribute.displayName'', ''ForceAuthn'', ''RequestedAuthnContext'', NameID format).

===== Group → Role Mapping =====

The closing panels map IdP group attribute values to Obsidian roles, including '''Require role assignment''' (default yes) and optional ''dynamicRole.prefix'' / ''suffix''. At least one mapping to the '''Admin''' role is required. See [[Advanced_Configuration#SAML_Authentication_Properties|SAML Authentication Properties]] for the full property reference.

===== SP metadata artefacts =====

During install the tooling writes '''sp-metadata.xml''' under the Obsidian deployment directory; the same metadata is available live at '''/saml/metadata''' after startup. Register whichever artefact your IdP admin prefers.

===== Before you complete install =====

* Ensure ACS and Entity ID '''https''' URLs are reachable from IdPs (align with reverse proxies).
* For Entra '''150+''' group memberships in SAML assertions, expect attribute suppression — filter groups or map assigned app roles instead. (OIDC uses a '''200''' group threshold; the numbers differ by protocol.)

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.x.x resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.x.x.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Installation Guide

2026-08-02T02:25:43Z

Craig: /* Provider-Specific Settings */

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.x.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== SAML 2.0 Configuration ====

If you selected '''SAML 2.0''' as the authentication type, the installer displays additional panels that configure the Service Provider identity, SAML signing credentials, federation metadata, attribute options, and group→role mapping.

===== Service Provider =====

* '''SP Entity ID''' — HTTPS URI registered as the SAML SP entity (must match IdP registrations).
* '''Assertion Consumer Service URL''' — HTTPS ACS endpoint where SAML responses arrive (HTTP-POST); aligns with the ACS in ''/saml/metadata''.
* '''SP Single Logout Service URL''' — Optional HTTPS URL for IdP-initiated SLO when logout mode targets IdP-mediated logout.
* '''SSO button label''' — Required label shown on '''Sign in with …'''.
* '''Logout mode''' — '''Local''' (Obsidian-only) or '''IdP / SLO''' (participates in SAML single logout when advertised).
* '''Post-logout redirect URI''' — Optional HTTPS landing URI after ''LogoutResponse''.
* '''Keystore path / alias / passwords''' — Required when signing SAML requests (password field is dual-entry validated).
* '''Sign SAML authentication requests''' — Toggle (installer default '''true''').
* '''Require signed SAML assertions''' — Toggle (recommended '''true''' for production).

===== Identity Provider =====

Choose the IdP type: Microsoft Entra ID (Azure AD), AD FS (on-premises), Okta, Auth0, or Generic SAML 2.0 (covers Keycloak ''/protocol/saml/descriptor'', Ping, Google Workspace, and similar). Follow-on screens seed example metadata URLs and default attribute names.

Provide '''either''' an HTTPS federation metadata URL '''or''' a local federation XML absolute path — choose exactly one. Later panels cover attribute options (''friendlyName'', ''valuePath'', ''stripPrefix'', ''attribute.user'', ''attribute.displayName'', ''ForceAuthn'', ''RequestedAuthnContext'', NameID format).

===== Group → Role Mapping =====

The closing panels map IdP group attribute values to Obsidian roles, including '''Require role assignment''' (default yes) and optional ''dynamicRole.prefix'' / ''suffix''. At least one mapping to the '''Admin''' role is required. See [[Advanced_Configuration#SAML_Authentication_Properties|SAML Authentication Properties]] for the full property reference.

===== SP metadata artefacts =====

During install the tooling writes '''sp-metadata.xml''' under the Obsidian deployment directory; the same metadata is available live at '''/saml/metadata''' after startup. Register whichever artefact your IdP admin prefers.

===== Before you complete install =====

* Ensure ACS and Entity ID '''https''' URLs are reachable from IdPs (align with reverse proxies).
* For Entra '''150+''' group memberships in SAML assertions, expect attribute suppression — filter groups or map assigned app roles instead. (OIDC uses a '''200''' group threshold; the numbers differ by protocol.)

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.0.0.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Installation Guide

2026-08-02T02:25:20Z

Craig: /* Deployment options */

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.0.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== SAML 2.0 Configuration ====

If you selected '''SAML 2.0''' as the authentication type, the installer displays additional panels that configure the Service Provider identity, SAML signing credentials, federation metadata, attribute options, and group→role mapping.

===== Service Provider =====

* '''SP Entity ID''' — HTTPS URI registered as the SAML SP entity (must match IdP registrations).
* '''Assertion Consumer Service URL''' — HTTPS ACS endpoint where SAML responses arrive (HTTP-POST); aligns with the ACS in ''/saml/metadata''.
* '''SP Single Logout Service URL''' — Optional HTTPS URL for IdP-initiated SLO when logout mode targets IdP-mediated logout.
* '''SSO button label''' — Required label shown on '''Sign in with …'''.
* '''Logout mode''' — '''Local''' (Obsidian-only) or '''IdP / SLO''' (participates in SAML single logout when advertised).
* '''Post-logout redirect URI''' — Optional HTTPS landing URI after ''LogoutResponse''.
* '''Keystore path / alias / passwords''' — Required when signing SAML requests (password field is dual-entry validated).
* '''Sign SAML authentication requests''' — Toggle (installer default '''true''').
* '''Require signed SAML assertions''' — Toggle (recommended '''true''' for production).

===== Identity Provider =====

Choose the IdP type: Microsoft Entra ID (Azure AD), AD FS (on-premises), Okta, Auth0, or Generic SAML 2.0 (covers Keycloak ''/protocol/saml/descriptor'', Ping, Google Workspace, and similar). Follow-on screens seed example metadata URLs and default attribute names.

Provide '''either''' an HTTPS federation metadata URL '''or''' a local federation XML absolute path — choose exactly one. Later panels cover attribute options (''friendlyName'', ''valuePath'', ''stripPrefix'', ''attribute.user'', ''attribute.displayName'', ''ForceAuthn'', ''RequestedAuthnContext'', NameID format).

===== Group → Role Mapping =====

The closing panels map IdP group attribute values to Obsidian roles, including '''Require role assignment''' (default yes) and optional ''dynamicRole.prefix'' / ''suffix''. At least one mapping to the '''Admin''' role is required. See [[Advanced_Configuration#SAML_Authentication_Properties|SAML Authentication Properties]] for the full property reference.

===== SP metadata artefacts =====

During install the tooling writes '''sp-metadata.xml''' under the Obsidian deployment directory; the same metadata is available live at '''/saml/metadata''' after startup. Register whichever artefact your IdP admin prefers.

===== Before you complete install =====

* Ensure ACS and Entity ID '''https''' URLs are reachable from IdPs (align with reverse proxies).
* For Entra '''150+''' group memberships in SAML assertions, expect attribute suppression — filter groups or map assigned app roles instead. (OIDC uses a '''200''' group threshold; the numbers differ by protocol.)

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.0.0.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Main Page

2026-08-02T02:24:52Z

Craig:

'''[[Obsidian]]''' is a fully-featured Java-based scheduling application which supports load balancing, failover and job workflow. It is designed for [[Deployment Diagram|high availability]], and it is specially built for demanding scheduling environments.

'''[[Release_Notes#Obsidian_7.0.1|Version 7.0.1]]''' is the latest release, and was released in August 2026.

Check out '''[[Getting Started]]''' if you are looking to set up Obsidian.

The '''[[User Guide]]''' will provide all the information you need to use all of Obsidian's functionality, and provides a quick view of the features Obsidian supports.

Our '''[[FAQ]]''' is also worth checking out if you have questions about Obsidian or want more context about what it does.

== Full Administration Capabilities ==

Obsidian features a rich administration web interface, allowing easy monitoring and management. See the '''[[Admin Web Application Guide]]''' for details.

[[Image:ObsidianNav 4.0.png]]

Release Notes

2026-08-02T02:24:21Z

Craig:

Please review our [[Upgrading_Obsidian|Upgrade Instructions]].

Read about our [[Planned_Releases|Planned Releases]].

Looking for old release notes? See [[Release_Notes_-_Older_Releases|Release Notes - Older Releases]].

<div class="toclimit-2">__TOC__</div>

== Obsidian 7.0.1 ==

Released August 2026

=== Bug Fixes ===

* Fixed site and hardware-linked licence verification on Obsidian 7.0.0. Workaround for 7.0.0 available on request.

== Obsidian 7.0.0 ==

Released July 2026

=== Features / Enhancements ===

* '''OAuth 2.0 / OIDC Single Sign-On''' — Obsidian now supports OAuth 2.0 / OIDC SSO authentication via [[Authenticator#OAuthAuthenticator_(OIDC_SSO)|OAuthAuthenticator]]. Configure any OIDC-compliant identity provider (Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC) as the login provider. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|OAuth/OIDC Authentication Properties]] for full configuration details.

* '''Bearer JWT authentication for the REST API''' — REST clients can now authenticate using a signed JWT access token in the ''Authorization: Bearer'' header. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|OAuth/OIDC Authentication Properties]] for configuration.

* '''Embedded Tomcat quick start''' — Evaluation and local runs use an Apache Tomcat 10.1.x embedded runtime (Jakarta Servlet). The bundled sample is '''h2-tomcat-quick-start.xml'''. ''webObsidian'' scripts start/stop embedded Tomcat for scheduler or admin-only profiles — see [[Installation_Guide#Deployment_options|Deployment options]] and [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].
** On Linux, embedded Tomcat packs also install optional user-level systemd and desktop integration — see [[Installation_Guide#Linux_desktop_and_systemd_integration|the installer option]] and [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

* '''Global parameter autocomplete and tooltips''' — While editing a job, typing ''{{'' in a parameter value opens suggestions for global parameter names (subject to visibility settings). On job view, hover over values containing ''Name'' to see resolved global values when your user's permissions allow. Administration screens for defining global parameters are unchanged. See [[Advanced_Configuration|Advanced Configuration]] for visibility settings.

* '''Install-time dependency resolution''' — The published installer download does not embed public open-source JARs. Libraries are fetched (or read from a pre-staged cache) when you run the installer. See [[Installation_Guide#Offline_or_restricted-network_install|Offline install]] for air-gapped preparation steps.

* '''Installer upgrade (IzPack 5)''' — Obsidian 7.0.0 ships an IzPack 5-based installer. GUI and headless installs behave as in Obsidian 6 for standard flows. Customers with saved Obsidian 6 automated install XML must run the migrate helper included in the download before headless install. See [[Upgrading_Obsidian#Migrating_saved_automated_install_XML_.28Obsidian_6_.E2.86.92_7.29|Upgrading Obsidian]].

* '''Modular Groovy and Flexmark libraries''' — Obsidian no longer ships '''apache-groovy-all-4.0.24.jar''' or '''flexmark-util-0.62.2.jar''' uber archives. Scripting and UI documentation rendering use the modular JAR sets documented in [[Advanced_Configuration#Dependent_Libraries|Dependent Libraries]].

=== Removals ===

* '''Remember Me login option removed''' — The Remember Me checkbox and associated session-cookie mechanism have been removed. The ''USER_COOKIE'' table and ''allowRememberMe'' system parameter are removed automatically during the upgrade to 7.0.0; no operator action is required.

=== Bug Fixes ===

* '''User logout''' - Fixed an issue where users were not fully logged out in certain session states.
* '''Job edit screen accessible to users with no roles''' — Users with no assigned roles could previously access the job edit screen but not make changes; this has been fixed.
* '''Firefox UI icons''' — Fixed icons not rendering correctly in Firefox.
* Jakarta emails sent with both text and HTML would drop HTML portion; this has been fixed.

== Obsidian 6.4.0 ==
Released December 2025

=== Enhancements ===
* New [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] and built in [[Admin_Job_Stats|UI]] and [[Embedded_API#List_Stats|Embedded API]] and [[REST_Endpoints#GET_a_list_of_job_execution_statistics|REST API]]

=== Bug Fixes ===

* Fixed issue preventing [[Admin_Jobs#Deleting|job deletion]] when resubmissions of failed executions existed. Bug existed in UI and APIs.
* Fixed UI styling issue for [[Admin_Jobs#Deleting|job deletion]] where checkbox label did not appear.

== Obsidian 6.3.3 ==
Released November 2025

=== Enhancements ===
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html LDAPAuthenticator] supports configurable check user active override - com.carfey.suite.security.LdapAuthenticator.checkActiveAttribute
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] visibility increased to protected to allow for functionality override in subclasses.

=== Bug Fixes ===

* Correct LdapAuthenticator case with delimited configuration where active check wasn't applied.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/security/LdapAuthenticator.html#isUserActive(javax.naming.directory.DirContext,java.lang.String) LDAPAuthenticator.isUserActive(DirContext,String)] javadoc added for isUserActive fully detailing the implementation.

== Obsidian 6.3.2 ==
Released October 2025

=== Enhancements ===
* Notification failures now trigger Dispatch category Error level event on first failure. For use in log alerts and Event Hooks.

=== Bug Fixes ===

* Notification failures no longer log on every failure reducing chatty failure logs.
* No-arg constructors added to multiple JSON serializable candidate POJOs missing them. Addresses GSON's workaround use of sun.misc.Unsafe.

== Obsidian 6.3.1 ==
Released August 2025

=== Bug Fixes ===

* Fix failure response codes on [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST health endpoint]]
* Fix automatic upgrade issue from 6.1.0 to any of 6.2.0, 6.2.1, 6.3.0
* Fix auth issue when [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA]] is enabled that allows REST access when account has been locked out due to MFA not being setup. [[Contact_the_Obsidian_Scheduler_Team|Contact us]] if you need workaround details for earlier versions.
* Fix native auth issue that allows REST access when account has been flagged as inactive.

== Obsidian 6.3.0 ==
Released July 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|~]]
* Annotation based job and chain configuration [[Initializing_and_Restoring#Annotation_Initialization|initialization]]
* Health endpoint with details for Job Queuer and Job Spawner - [[REST_Endpoints#GET_health_details_on_an_existing_scheduling_host|REST API]] or Embedded API [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(java.lang.String) by hostname] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHealth(long) by host id]
* JDBC URL construction from parts [[Advanced_Configuration#Database_Properties|host/port/databaseName/dbType/oracleSid]]

== Obsidian 6.2.1 ==
Released June 2025

=== Bug Fixes ===

* Certain recoveries greater than 24 hours using new day of month proximity patterns introduced in 6.2.0 would result in no jobs spawning.
* Migrations targeting 6.0.0 and greater that start earlier than 5.0.0 skip the 5.0.0 migration. Migrating to any 5.x version first and then to 6.0.0 or later works around this issue.

== Obsidian 6.2.0 ==
Released May 2025

=== Features / Enhancements ===

* Cron day of month expansion for [[Cron#Special_Character_Usage|day of week proximity]] using [[Cron#Examples|< > ≥ ≤]]
* Cron day of month expansion for [[Cron#Special_Character_Usage|weekday proximity]] using [[Cron#Examples|< > ≥ ≤]]
* [[Admin_Global_Parameters#Using_Global_Parameters_in_Jobs|Global Parameters]] reference in job edit page support mouseover/title display of actual value when permissions allow
* Host time displayed in [[Admin_Host_Status|hosts status]] in UI
* [[Admin_Job_Runtime_Preview|Runtime Preview]] optimizations for large date ranges in both UI and APIs.

=== Bug Fixes ===

* Combination of table prefix, sorting by clob column and Oracle metadata load failure no longer results in sql error. This occurred in the UI when viewing raw job history results and in API calls for job runtime results.

== Obsidian 6.1.1 ==
Released March 2025

=== Features / Enhancements ===

* [[Authenticator#Implementation_of_a_Custom_Authenticator|Authenticator]] supports optional <code>authenticateREST()</code> method.

=== Bug Fixes ===

* Native authentication REST logins do not apply 'last login' timestamps. Avoids noisy error that was appearing in logs.

== Obsidian 6.1.0 ==
Released March 2025

=== Features / Enhancements ===

* Native authentication now disables users after 4 invalid login attempts, either password or MFA code if applicable. Invalid attempts threshold is configurable.
* Native authentication last login datetime displayed on list user screen.
* Stronger licensing controls. Site and hardware licenses as of this version must be regenerated by Carfey Software and every 2 years. Contact us at licensing [[Image:atSymbol.png]] obsidianscheduler.com.

=== Bug Fixes ===

* Native authentication password complexity pattern properly created and no longer overwritten on restart.

== Obsidian 6.0.1 ==
Released February 2025

=== Features / Enhancements ===

* [[Built-in_Jobs#File_Archive_Job|File Archive Job]] and [[Built-in_Jobs#File_Scanner_Job|File Scanner Job]] both now support min/max file sizes and minimum age.

=== Bug Fixes ===

* Native authentication user updates now support long passwords.

== Obsidian 6.0.0 ==
Released December 27, 2024

=== Features / Enhancements ===

* Jakarta Servlet 5.0
** Servlet container for Web Admin must support Jakarta Servlet 5.0 (e.g. Tomcat 10, Jetty 11)
* [[Micronaut_Integration|Micronaut]] integration support
* [[Advanced_Configuration#Dependent_Libraries|Groovy 4]] support
* [[Advanced_Configuration#Properties.2FYaml_File|Yaml]] configuration support<ref>

If you are using automated installer files from previous releases, you will need to add an additional configuration item to choose between yaml and properties formats in UserInputPanel.0.
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.0">
<userInput>
......snip......
<entry key="config.format" value="yaml" />
OR
<entry key="config.format" value="properties" />
......snip......
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre></ref>
* Native authentication supports customizable [[Admin_Login#Password_Complexity|password complexity]] requirements
* XML support deprecated across the product including XML UI downloads, XML runner configurations and XML license leases.
** '''Starting January 1st 2027, XML license lease requests will stop being processed. All Obsidian instances running using internet-verified licenses (including licence key proxies) will be required to use release 6.0.0 or later as of January 1st 2027.'''
** Above noted XML support will be removed in the first Obsidian version released in 2027.
* License leases use JSON payloads.

== Obsidian 5.5.1 ==
Released December 16, 2024

=== Bug Fixes ===

* Admin only (no scheduler) UI no longer generates event hook errors while running nor during shutdown
* Quick start installer file no longer generates errors during installation
* A few small web UI enhancements

== Obsidian 5.5.0 ==
Released October 2024

=== Features / Enhancements ===

* Event Hooks management available in [[Admin_Host_Status#Event_Hook_Status|UI]], [[Embedded_API#Event_Hook_Resume_or_Pause|Embedded API]] and [[REST_Endpoints#POST_event_hook_pause_or_resume|REST API]].
* [[Installation_Guide#Additional_configuration_items|Installer]] supports custom add on configurations '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 5.5.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.17 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.18">
<userInput>
<entry key="extra.log4j2.properties.1" value=""/>
<entry key="extra.log4j2.properties.2" value=""/>
<entry key="extra.log4j2.properties.3" value=""/>
<entry key="extra.log4j2.properties.4" value=""/>
<entry key="extra.log4j2.properties.5" value=""/>
<entry key="extra.log4j2.properties.6" value=""/>
<entry key="extra.log4j2.properties.7" value=""/>
<entry key="extra.log4j2.properties.8" value=""/>
<entry key="extra.log4j2.properties.9" value=""/>
<entry key="extra.log4j2.properties.10" value=""/>
<entry key="extra.log4j2.properties.11" value=""/>
<entry key="extra.log4j2.properties.12" value=""/>
<entry key="extra.log4j2.properties.13" value=""/>
<entry key="extra.log4j2.properties.14" value=""/>
<entry key="extra.log4j2.properties.15" value=""/>
<entry key="extra.log4j2.properties.16" value=""/>
<entry key="extra.log4j2.properties.17" value=""/>
<entry key="extra.log4j2.properties.18" value=""/>
<entry key="extra.log4j2.properties.19" value=""/>
<entry key="extra.log4j2.properties.20" value=""/>
<entry key="extra.carfey.properties.1" value=""/>
<entry key="extra.carfey.properties.2" value=""/>
<entry key="extra.carfey.properties.3" value=""/>
<entry key="extra.carfey.properties.4" value=""/>
<entry key="extra.carfey.properties.5" value=""/>
<entry key="extra.carfey.properties.6" value=""/>
<entry key="extra.carfey.properties.7" value=""/>
<entry key="extra.carfey.properties.8" value=""/>
<entry key="extra.carfey.properties.9" value=""/>
<entry key="extra.carfey.properties.11" value=""/>
<entry key="extra.carfey.properties.10" value=""/>
<entry key="extra.carfey.properties.12" value=""/>
<entry key="extra.carfey.properties.13" value=""/>
<entry key="extra.carfey.properties.14" value=""/>
<entry key="extra.carfey.properties.15" value=""/>
<entry key="extra.carfey.properties.16" value=""/>
<entry key="extra.carfey.properties.17" value=""/>
<entry key="extra.carfey.properties.18" value=""/>
<entry key="extra.carfey.properties.19" value=""/>
<entry key="extra.carfey.properties.20" value=""/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>

=== Bug Fixes ===

* Certain Cron expressions that fail to generate text descriptions no longer impact scheduling.
* Text database columns were previously restricted to maximum length of MySQL implementation. Corrected to validate length via DB implementation.

== Obsidian 5.4.0 ==
Released June 2024

=== Features / Enhancements ===

* Event Hooks available in [[Embedded_API#List_Event_Hooks|Embedded API]] and [[REST_Endpoints#GET_event_hooks|REST API]].
* [[Advanced_Configuration#Dependent_Libraries|GSON library]] upgrade to support Java 21

=== Bug Fixes ===

* Oracle identifier no longer too long when using prefixes.

== Obsidian 5.3.0 ==
Released March 2024

=== Features / Enhancements ===

* New [[Admin_Host_Status#Event_Hook_Status| Event Hooks Status]] available in the UI.

=== Bug Fixes ===

* Some improvements throughout the [[Admin_Web_Application_Guide|Admin Web Application]] for autofocus of fields.
* Additional classes and interfaces added to [https://web.obsidianscheduler.com/obsidianapi/ javadoc].
* Some cleanup in [https://web.obsidianscheduler.com/obsidianapi/ javadoc] documenation.

== Obsidian 5.2.1 ==
Released January 2024

=== Features / Enhancements ===

* [[Built-in_Jobs#Maintenance_Jobs|Maintenance Jobs]] are now scheduled by default in new installations. Can be disabled via [[Advanced_Configuration#Miscellaneous_Properties|Configuration]] property.
* New [[Event_Hooks#Standard_Output.2FError_Streams_Event_Hook | Standard Output/Error Streams Event Hook]].

=== Bug Fixes ===

* Schedule descriptions are now updated after edits are applied in all UI screens and APIs.

== Obsidian 5.2.0 ==
Released December 2023

=== Features / Enhancements ===

* [[Cron]] & [[Cron#Recurrence|Recur]] patterns along with any use of [[Admin_Schedule_Aliases|Schedule Aliases]] now support plain language description of the patterns throughout the [[Admin_Web_Application_Guide|UI]], visible while hovering patterns, and in [[REST_Endpoints|REST]] and [[Embedded_API|Embedded]] API responses.
* All screens supporting UI exports now support JSON ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]], [[Admin_Custom_Calendars#Calendar_Listing|Calendars]])
* All screens supporting UI exports and search criteria and/or inline filters now include any specified search criteria and filter text in Excel, XML and JSON downloads ([[Admin_Job_Activity#Exporting_Results|Job Activity]], [[Admin_Jobs#Exporting_Results|Jobs]], [[Admin_Job_Runtime_Preview#Exporting_Results|Runtime Previews]], [[Admin_Job_Chains#Job_Chain_Listing|Job Chains]], [[Admin_Logs#Exporting_Results|Logs]], [[Admin_Notifications#Exporting_Results|Sent Notifications]], [[Admin_User_Management#Exporting_Results|Users]])
* Support for [[Installation_Guide#Choosing_Email_Support|Jakarta EE mail]] '''Potential breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases and had email configured, you will need to add a new section of xml as of Obsidian 5.2.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.16 closing brace, add the following:
<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.17">
<userInput>
<entry key="mail.type.selection" value="javax"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
</ref>
* New [[Event_Hooks#REST_Endpoint_Event_Hook|REST Endpoint Event Hook]]
* [[Key_Server_Proxy|Key Server proxy]] artifact obtained via web download during installation

=== Bug Fixes ===

* Time picker buttons (hour, minute, AM/PM) in [[Admin_Job_Activity#Filtering|Job Activity filtering]] no longer change other elements of the selected time.
* Cron pattern with [[Cron#Special_Character_Usage|LW]] and any other non-L value in day position no longer also incorrectly evaluates to last day.

== Obsidian 5.1.1 ==
Released June 2023

=== Bug Fixes ===

* [[Authenticator|Native authentication]] no longer fails when user deletes are attempted from the UI.
* Built in maintenance job [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup]] no longer leaves deletion candidate CHAIN SKIPPED records in the JOB_HISTORY table in rare circumstances.

== Obsidian 5.1.0 ==
Released April 2023

=== Features / Enhancements ===

* [[Admin_Schedule_Aliases#Schedule_Alias_Fragments|Schedule Aliases]] now support fragments for configuration-time substitutions.
* New convenience job [[Built-in_Jobs#Database_File_Export_Job|Database File Export Job]] for generating basic file extracts from database queries.
* New convenience job [[Built-in_Jobs#REST_Invocation_Job|REST Invocation Job]] for making simple REST calls and storing results.
* Performance improvements in job failure handling.

== Obsidian 5.0.4 ==
Released February 2022

=== Features / Enhancements ===
* Log4j2 2.17.1 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.1 RCE vulnerability] where attackers can modify log4j configuration.
* Restore missing default log4j2 configuration in installation artifacts.

== Obsidian 5.0.3 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.17.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.17.0 DOS vulnerability]
* Fix native login issue showing as inactive on some databases.

== Obsidian 5.0.2 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.16.0 as permanent fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.16.0 RCE vulnerability]

== Obsidian 5.0.1 ==
Released December 2021

=== Features / Enhancements ===
* Log4j2 2.15.0 as fix for [https://logging.apache.org/log4j/2.x/security.html#log4j-2.15.0 RCE vulnerability]

=== Bug Fixes ===
* Fix sporadic native login issue on some databases.
* Formatting fix in quick installer file

== Obsidian 5.0.0 ==
Released August 2021.

=== Features / Enhancements ===
* Java 11 (minimum Java version)
* [[Admin_Schedule_Aliases|Schedule Aliases]] including support in [[REST_Endpoints#Schedule_Alias_Endpoints|REST API]] and [[Embedded_API#ScheduleAliasManager_API|Embedded API]]
* [[Admin_User_Management#Multi-Factor_Authentication_.28MFA.29|MFA Support]] for UI logins
* New [[Admin_User_Management#User_Rights|Author and Operator]] roles
* Convention-based role permissions by [[Admin_User_Management#Job_Folder_Rights|root job folder]] for Write, Author and Operator.<ref>
There is a possibility of a breaking change to Embedded or REST API use due to the need to change the [[Embedded_API#Enumerations|User Role enumeration]] from a Java enum to an enum-style class to support this feature. Bringing in the upgraded Obsidian library and compiling should reveal any such broken use of these enumerations. Needed changes should be minor and self-explanatory.</ref>
* Bundled Jetty 10.0.2
* Legacy Embedded API (from Obsidian 1.5) dropped
* Signal handler disabled by default. Enabled only via [[Advanced_Configuration#Miscellaneous_Properties|configuration]].
* Many [[Advanced_Configuration#Dependent_Libraries|library upgrades]].
* UI javascript library updates.

== Footnotes ==
<references/>

Advanced Configuration

2026-07-31T17:15:44Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# You can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# You can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# You can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# This is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# This determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# If anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# We support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# We support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# You can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# If you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# You can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

You may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian requires a number of third-party libraries for the scheduler and the web administration application. Unless noted, libraries in a category are required for that deployment profile. The installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]] and can omit unused optional stacks. License attribution for shipped artifacts is in the product <code>NOTICE</code>.

=== Overview ===

{| class="wikitable"
! Category !! Required when !! Notes
|-
| Core || Always || Scheduler and shared runtime
|-
| Database drivers || Matching database engine || Unused drivers may be omitted at install
|-
| Mail || Email notifications enabled || Choose the javax '''or''' Jakarta stack
|-
| Scripting || Matching script job type || Groovy is modular (see Scripting table)
|-
| Web Admin || Web administration UI || Includes Markdown rendering (Flexmark)
|-
| Authentication (OAuth / OIDC) || ''OAuthAuthenticator'' active || Installer can remove when unused
|-
| Authentication (SAML 2.0) || ''SAMLAuthenticator'' active || Installer removes when SAML is not selected
|-
| Embedded Tomcat || Embedded Tomcat pack selected || Present under <code>embed-tomcat-lib/</code>
|}

=== Core ===

{| class="wikitable"
! Component !! Artifacts !! Purpose
|-
| Obsidian || <code>obsidian.jar</code> || Core library
|-
| Gson || <code>gson-2.10.1.jar</code> || REST API and web administration JSON
|-
| JMustache || <code>jmustache-1.15.jar</code> || Email templating
|-
| Log4j 2 || <code>log4j-api-2.26.0.jar</code>, <code>log4j-core-2.26.0.jar</code> || Logging (<code>log4j-slf4j2-impl-2.26.0.jar</code> ships with the SAML stack)
|-
| SnakeYAML || <code>snakeyaml-2.3.jar</code> || YAML configuration
|}

=== Database drivers ===

{| class="wikitable"
! Component !! Artifacts !! Required when
|-
| H2 || <code>h2-1.4.200.jar</code> || Running against H2
|-
| MariaDB / MySQL || <code>mariadb-java-client-2.7.2.jar</code> || Running against MySQL or MariaDB
|-
| SQL Server || <code>mssql-jdbc-9.2.1.jre11.jar</code> || Running against SQL Server
|-
| Oracle || <code>ojdbc11-21.1.0.0.jar</code> || Running against Oracle
|-
| PostgreSQL || <code>postgresql-42.2.19.jar</code> || Running against PostgreSQL
|}

=== Mail ===

{| class="wikitable"
! Stack !! Artifacts !! Use
|-
| JavaMail (javax) || <code>activation-1.1.jar</code>, <code>javax.mail-1.6.2.jar</code> || Classic JavaMail notifications
|-
| Jakarta Mail || <code>jakarta.activation-api-2.1.2.jar</code>, <code>jakarta.mail-api-2.1.2.jar</code>, optional <code>angus-activation-2.0.1.jar</code>, <code>angus-mail-2.0.2.jar</code> || Jakarta EE email notifications
|}

=== Scripting ===

{| class="wikitable"
! Component !! Artifacts !! Purpose
|-
| BeanShell || <code>bsh-2.0b5.jar</code> || BeanShellJob only
|-
| JRuby || <code>jruby-9.2.17.0.jar</code> || RubyJob only
|-
| Jython || <code>jython-standalone-2.7.2.jar</code> || PythonJob only
|-
| Groovy 4 || Modular set (17 JARs) — see list below || GroovyJob; all omitted when Groovy is disabled at install
|}

Groovy modular artifacts (13 runtime modules + 4 owned transitives):

<code>groovy-4.0.24.jar</code>, <code>groovy-astbuilder-4.0.24.jar</code>, <code>groovy-datetime-4.0.24.jar</code>, <code>groovy-dateutil-4.0.24.jar</code>, <code>groovy-json-4.0.24.jar</code>, <code>groovy-jsr223-4.0.24.jar</code>, <code>groovy-macro-4.0.24.jar</code>, <code>groovy-macro-library-4.0.24.jar</code>, <code>groovy-nio-4.0.24.jar</code>, <code>groovy-sql-4.0.24.jar</code>, <code>groovy-templates-4.0.24.jar</code>, <code>groovy-typecheckers-4.0.24.jar</code>, <code>groovy-xml-4.0.24.jar</code>, <code>asm-analysis-9.7.1.jar</code>, <code>asm-tree-9.7.1.jar</code>, <code>asm-util-9.7.1.jar</code>, <code>javaparser-core-3.26.2.jar</code>

=== Web Admin ===

{| class="wikitable"
! Component !! Artifacts !! Purpose
|-
| dom4j || <code>dom4j-2.1.3.jar</code> || XML utilities
|-
| Flexmark || Modular set (12 JARs) — see list below || Markdown for job and parameter descriptions
|-
| JXL || <code>jxl-2.6.12.jar</code> || Excel utilities (web administration)
|-
| OpenCSV || <code>opencsv-5.4.jar</code> || CSV downloads in the UI
|}

Flexmark modular artifacts:

<code>flexmark-0.62.2.jar</code>, <code>flexmark-util-ast-0.62.2.jar</code>, <code>flexmark-util-builder-0.62.2.jar</code>, <code>flexmark-util-collection-0.62.2.jar</code>, <code>flexmark-util-data-0.62.2.jar</code>, <code>flexmark-util-dependency-0.62.2.jar</code>, <code>flexmark-util-format-0.62.2.jar</code>, <code>flexmark-util-html-0.62.2.jar</code>, <code>flexmark-util-misc-0.62.2.jar</code>, <code>flexmark-util-options-0.62.2.jar</code>, <code>flexmark-util-sequence-0.62.2.jar</code>, <code>flexmark-util-visitor-0.62.2.jar</code>

=== Authentication (OAuth / OIDC) ===

Required only when ''OAuthAuthenticator'' is active.

{| class="wikitable"
! Component !! Artifacts !! Purpose
|-
| Nimbus OAuth / OIDC || <code>oauth2-oidc-sdk-11.23.1.jar</code>, <code>nimbus-jose-jwt-10.0.2.jar</code>, <code>content-type-2.3.jar</code>, <code>lang-tag-1.7.jar</code>, <code>json-smart-2.5.2.jar</code>, <code>accessors-smart-2.5.2.jar</code>, <code>jcip-annotations-1.0-1.jar</code>, <code>asm-9.7.1.jar</code> || OIDC SSO and JOSE+JWT (ASM is also used by Groovy when scripting is enabled)
|}

=== Authentication (SAML 2.0) ===

Required only when ''SAMLAuthenticator'' is active. The installer removes this stack when SAML is not the selected authentication type.

{| class="wikitable"
! Component !! Artifacts !! Purpose
|-
| OpenSAML 4 || Modular set — see list below || SAML 2.0 messages, metadata, and signatures
|-
| Supporting stack || <code>java-support-8.4.2.jar</code>, <code>xmlsec-2.3.4.jar</code>, <code>cryptacular-1.2.5.jar</code>, <code>bcprov-jdk18on-1.85.jar</code>, <code>bcpkix-jdk18on-1.85.jar</code>, <code>bcutil-jdk18on-1.85.jar</code>, <code>velocity-engine-core-2.3.jar</code>, <code>commons-lang3-3.20.0.jar</code>, <code>commons-codec-1.15.jar</code>, <code>httpclient-4.5.14.jar</code>, <code>httpcore-4.4.16.jar</code>, <code>guava-32.1.3-jre.jar</code>, <code>failureaccess-1.0.1.jar</code>, <code>listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar</code>, <code>metrics-core-4.2.25.jar</code>, <code>slf4j-api-2.0.12.jar</code>, <code>log4j-slf4j2-impl-2.26.0.jar</code> || Crypto, HTTP metadata fetch, Guava, metrics, and SLF4J→log4j2 bridge for OpenSAML diagnostics
|}

OpenSAML modules:

<code>opensaml-core-4.3.2.jar</code>, <code>opensaml-saml-api-4.3.2.jar</code>, <code>opensaml-saml-impl-4.3.2.jar</code>, <code>opensaml-security-api-4.3.2.jar</code>, <code>opensaml-security-impl-4.3.2.jar</code>, <code>opensaml-xmlsec-api-4.3.2.jar</code>, <code>opensaml-xmlsec-impl-4.3.2.jar</code>, <code>opensaml-messaging-api-4.3.2.jar</code>, <code>opensaml-profile-api-4.3.2.jar</code>, <code>opensaml-soap-api-4.3.2.jar</code>, <code>opensaml-soap-impl-4.3.2.jar</code>, <code>opensaml-storage-api-4.3.2.jar</code>

=== Embedded Tomcat ===

Present only when an Embedded Tomcat pack is selected (<code>embed-tomcat-lib/</code>).

{| class="wikitable"
! Component !! Artifacts !! Purpose
|-
| Apache Tomcat embed || <code>tomcat-embed-core-10.1.39.jar</code>, <code>tomcat-embed-el-10.1.39.jar</code> || Embedded servlet runtime (Apache License 2.0)
|}

=== Embedded API classpath ===

To use the [[Embedded_API|Embedded API]], import the resources below (newer compatible versions already on your application classpath may be used). JARs are typically under the <code>standalone</code> directory. The <code>com.carfey.properties</code> / <code>com.carfey.yaml</code> file can be taken from <code>obsidian-properties-configuration.jar</code> / <code>obsidian-yaml-configuration.jar</code>, or from an Obsidian WAR under <code>WEB-INF/classes</code>.

{| class="wikitable"
! Needed for !! Artifacts
|-
| Always || Configuration file (or configuration JAR); <code>obsidian.jar</code>; <code>dom4j-2.1.3.jar</code>; Flexmark modular set (see Web Admin); <code>gson-2.10.1.jar</code>; <code>log4j-api-2.26.0.jar</code>, <code>log4j-core-2.26.0.jar</code>; appropriate JDBC driver
|-
| Notifications || <code>jmustache-1.15.jar</code> plus the javax '''or''' Jakarta mail stack from the Mail table
|-
| Scripting jobs || BeanShell, JRuby, Jython, and/or Groovy modular set as used by your jobs
|}

=== Library coordinates in Obsidian 5.x and 6.x ===

Current coordinates are listed above. The table below records notable library coordinates used in Obsidian 5.x and 6.x before they were replaced. Pre-5.0.0 history is not kept on this page (see page history if needed).

{| class="wikitable"
! Replaced in !! Component !! Artifacts then in use
|-
| 7.0.0 || Log4j || <code>log4j-api-2.17.1.jar</code>, <code>log4j-core-2.17.1.jar</code>. Within 5.0.x patch releases before 5.0.3: 2.14.1 (5.0.0), 2.15.0 (5.0.1), 2.16.0 (5.0.2)
|-
| 7.0.0 || Groovy || <code>apache-groovy-all-4.0.24.jar</code> (6.x). Before 6.0.0: <code>groovy-all-3.0.7.jar</code>
|-
| 7.0.0 || Flexmark || <code>flexmark-0.62.2.jar</code>, <code>flexmark-util-0.62.2.jar</code> (uber util JAR)
|-
| 7.0.0 || OAuth / OIDC, SAML 2.0, Embedded Tomcat || Not shipped before 7.0.0
|-
| 5.4.0 || Gson || <code>gson-2.8.6.jar</code>
|-
| 5.2.0 || Jakarta Activation || <code>jakarta.activation-1.2.1.jar</code>
|-
| 5.0.0 || Mail, scripting, JDBC, and related || Baseline 5.0.0 set included <code>javax.mail-1.5.5.jar</code>, <code>dom4j-1.6.1.jar</code>, <code>gson-2.7.jar</code>, <code>bsh-2.0b4.jar</code>, <code>groovy-all-2.4.14.jar</code>, <code>jython-standalone-2.7.0.jar</code>, <code>jruby-complete-9.2.7.0.jar</code>, <code>jmustache-1.12.jar</code>, <code>h2-1.4.192.jar</code>, <code>log4j-1.2.9.jar</code>, <code>mariadb-java-client-1.4.5.jar</code>, <code>jtds-1.3.1.jar</code>, <code>ojdbc7-12.1.0.1.jar</code>, <code>postgresql-9.4.1208.jre7.jar</code>, <code>opencsv-3.8.jar</code>, and (from 4.3.0) Flexmark 0.19.6
|}

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Installation Guide

2026-07-31T15:37:28Z

Craig:

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7.0.0 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.0.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== SAML 2.0 Configuration ====

If you selected '''SAML 2.0''' as the authentication type, the installer displays additional panels that configure the Service Provider identity, SAML signing credentials, federation metadata, attribute options, and group→role mapping.

===== Service Provider =====

* '''SP Entity ID''' — HTTPS URI registered as the SAML SP entity (must match IdP registrations).
* '''Assertion Consumer Service URL''' — HTTPS ACS endpoint where SAML responses arrive (HTTP-POST); aligns with the ACS in ''/saml/metadata''.
* '''SP Single Logout Service URL''' — Optional HTTPS URL for IdP-initiated SLO when logout mode targets IdP-mediated logout.
* '''SSO button label''' — Required label shown on '''Sign in with …'''.
* '''Logout mode''' — '''Local''' (Obsidian-only) or '''IdP / SLO''' (participates in SAML single logout when advertised).
* '''Post-logout redirect URI''' — Optional HTTPS landing URI after ''LogoutResponse''.
* '''Keystore path / alias / passwords''' — Required when signing SAML requests (password field is dual-entry validated).
* '''Sign SAML authentication requests''' — Toggle (installer default '''true''').
* '''Require signed SAML assertions''' — Toggle (recommended '''true''' for production).

===== Identity Provider =====

Choose the IdP type: Microsoft Entra ID (Azure AD), AD FS (on-premises), Okta, Auth0, or Generic SAML 2.0 (covers Keycloak ''/protocol/saml/descriptor'', Ping, Google Workspace, and similar). Follow-on screens seed example metadata URLs and default attribute names.

Provide '''either''' an HTTPS federation metadata URL '''or''' a local federation XML absolute path — choose exactly one. Later panels cover attribute options (''friendlyName'', ''valuePath'', ''stripPrefix'', ''attribute.user'', ''attribute.displayName'', ''ForceAuthn'', ''RequestedAuthnContext'', NameID format).

===== Group → Role Mapping =====

The closing panels map IdP group attribute values to Obsidian roles, including '''Require role assignment''' (default yes) and optional ''dynamicRole.prefix'' / ''suffix''. At least one mapping to the '''Admin''' role is required. See [[Advanced_Configuration#SAML_Authentication_Properties|SAML Authentication Properties]] for the full property reference.

===== SP metadata artefacts =====

During install the tooling writes '''sp-metadata.xml''' under the Obsidian deployment directory; the same metadata is available live at '''/saml/metadata''' after startup. Register whichever artefact your IdP admin prefers.

===== Before you complete install =====

* Ensure ACS and Entity ID '''https''' URLs are reachable from IdPs (align with reverse proxies).
* For Entra '''150+''' group memberships in SAML assertions, expect attribute suppression — filter groups or map assigned app roles instead. (OIDC uses a '''200''' group threshold; the numbers differ by protocol.)

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.0.0.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Installation Guide

2026-07-31T15:34:09Z

Craig:

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7.0.0 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.0.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.0.0.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Installation Guide

2026-07-31T15:30:53Z

Craig:

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7.0.0 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. Select ''Native (Database)'', ''LDAP'', ''OAuth (OIDC)'', ''SAML 2.0'', or ''Other'' (custom). ''Native (Database)'' requires no additional configuration and is what most users will select at least to start.

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. ''Native (Database)'' authentication requires no additional configuration and is what most users will select. Select ''Other'' if you have implemented your own authentication mechanism, OAuth (OIDC), SAML or LDAP according to your desired mechanism.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.0.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.0.0.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Release Notes - Older Releases

2026-07-31T15:14:43Z

Craig:

<div class="toclimit-2">__TOC__</div>

== Obsidian 4.10.6 ==
Released April 2021.

=== Bug Fixes ===
* Correct issue where PostgreSQL database connection validation exceptions are masked.
* Fix UI styling issues in Firefox browser.

== Obsidian 4.10.5 ==
Released October 2020.

=== Features / Enhancements ===
* New ''LW'' instruction for day-of-month field in [[Cron#Special_Character_Usage|Cron]] to indicate last weekday of month.

=== Bug Fixes ===
* Fix for ''W'' day-of-month field in [[Cron#Special_Character_Usage|Cron]] skipping months where ordinal is last ordinal of the month and falls on the last Sunday of the month.

== Obsidian 4.10.4 ==
Released July 2020.

=== Bug Fixes ===
* Fix UTF-8 handling in [[REST_API|REST API]] calls.

== Obsidian 4.10.3 ==
Released March 2020.

=== Features / Enhancements ===
* Introduce better handling for edge case where a long running job that loses connectivity to the Obsidian database gets marked as Died while it is still running and then eventually reconnects to the database and its heartbeat updates resume. Heartbeat updates will now be prevented and new special events are triggered when this case is detected and when the job finally terminates.

=== Bug Fixes ===
* Fix JobIds parameter in [[Embedded_API#List_Job_Dashboard_.28Latest_Scheduled_Runtime_by_Job.29|Embedded]] API for Job Dashboard (Last Occurrence of Jobs)

== Obsidian 4.10.2 ==
Released October 2019.

=== Features / Enhancements ===
* [[REST_Endpoints#GET_a_list_of_the_latest_scheduled_runtime_by_job_.28supports_multiple_jobs.29|REST]] and [[Embedded_API#List_Job_Dashboard_.28Latest_Scheduled_Runtime_by_Job.29|Embedded]] API for Job Dashboard (Last Occurrence of Jobs)
* Timezone now included when dates are in event messages.

== Obsidian 4.10.1 ==
Released June 2019.

==== Bug Fixes ====
* [[Recovery_%26_Failover#Startup_.2F_Shutdown_Mode|Startup/Shutdown]] configuration of jobs not being applied in UI.
* [[Admin_Scheduler_Settings|Scheduler setting]] jobShutdownWaitTimeSeconds in Job category could not be set to -1 in the UI.

== Obsidian 4.10.0 ==
Released April 2019.

=== Features / Enhancements ===
* Support for automated [[Recovery_%26_Failover#Startup_.2F_Shutdown_Mode|Startup/Shutdown]] invocation of jobs.
* [[Implementing_Jobs#Parameterization|Parameters]] now have optional support for validation of list values to be unique.
* Formalized support for [[Scripting_Jobs|Ruby Script jobs]] via JRuby.
* Enhanced [[Installation_Guide#Selecting_Script_Libraries|installer]] to allow selectivity of desired script libraries/jobs. '''Breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 4.10.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.15 closing brace, add the following:<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.16">
<userInput>
<entry key="script.beanshell" value="true"/>
<entry key="script.jruby" value="false"/>
<entry key="script.groovy" value="true"/>
<entry key="script.jython" value="true"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
You can change the parameter values as desired. The above reflects the options for all versions prior to Obsidian 4.10.0.
</ref>
* Formalized support for [[Getting_Started#Supported_Platforms|MS SQL 2016 & 2017]]

== Obsidian 4.9.1 ==
Released March 2019.

==== Bug Fixes ====
* ClasspathJobScanner fails on job classes with no [[Implementing_Jobs#SchedulableJob_Interface|@Description]] annotation
* In some cases, [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup Job]] was not deleting certain history and related records.

== Obsidian 4.9.0 ==
Released February 2019.

=== Features / Enhancements ===
* [[Implementing_Jobs#SchedulableJob_Interface|Description]]/[[Implementing_Jobs#Parameterization|Parameter]] annotation support optional URLs arrays
* New built-in maintenance job [[Built-in_Jobs#Notification_Cleanup_Job|Delete Notifications Job]]
* New subscribable event for first occurrence of a host not running a job due to not being one of the fixed hosts.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/Context.html Context] class expanded to include some additional helpful attributes.

==== Bug Fixes ====
* [[Admin_Jobs#Nickname.2C_Class_and_Folder|Folder]] Selection in UI fixed to allow intermediary folders selections
* [[Event_Hooks#Slack_Notifier|SlackEventHook]] fixed to include ERROR level
* Logout from My User page fixed to redirect to Login page
* Fixed an issue with PostgreSQL DDL that could report wrong exception on execution failures.

== Obsidian 4.8.0 ==
Released November 2018.

=== Features / Enhancements ===
* Improve performance of job activity view when retrieving large job errors.

==== Bug Fixes ====
* Corrected an issue where in some situations job conflict priority calculation was incorrect.
* Missed and Overlapped job events are now subscribable.

== Obsidian 4.7.1 ==
Released October 2018.

=== Features / Enhancements ===
* New LDAP [[Advanced_Configuration#Authentication_Properties|Configuration Parameter]] to support additional group membership attributes.

==== Bug Fixes ====
* Correct Non-English Locale issues in database DDL/DML.

== Obsidian 4.7.0 ==
Released September 2018.

=== Features / Enhancements ===
* Optimized [[Built-in_Jobs#Job_History_Cleanup_Job|JobHistoryCleanupJob]] for better performance and reduced locking
* New [[REST_Endpoints#DELETE_a_future_scheduled_runtime|REST]] and [[Embedded_API#Delete_a_Future_Scheduled_Runtime_for_a_Job|Embedded]] API function for targeted deletion of a single future one time submission including its parameters.
* Modified job_state index to improve job listing performance in cases where there are a large of future-dated [[Job_Features#Resubmission_.26_Ad_Hoc_Runs|ad-hoc submissions]].
* PostgreSQL 10 Support
* Oracle 12c support

==== Bug Fixes ====
* Add missing job_history index on PostgreSQL installations
* Corrected issue where Get Schedules [[Embedded_API#List_a_Job.27s_Schedules|Embedded]] and [[REST_Endpoints#GET_a_list_of_an_existing_job.27s_schedules|REST]] APIs were setting all parameters to the ordinal of the last parameter.

== Obsidian 4.6.2 ==
Released August 2018.

=== Features / Enhancements ===
* Reduce locking in certain cases of job delete.

==== Bug Fixes ====
* Corrected NPE when performing recovery on a job that has transitioned from Disabled to Enabled state.

== Obsidian 4.6.1 ==
Released July 2018.

=== Features / Enhancements ===
* Performance improvements related to Job Result loading.
* Added informational logging for cases where licence key configuration will not applied.

==== Bug Fixes ====
* Corrected issue where stale admin_only hosts were not cleaned from database.
* Corrected issue where licence release failures were never logged due to shutdown state.

== Obsidian 4.6.0 ==
Released June 2018.

=== Features / Enhancements ===
* [[Advanced_Configuration#Miscellaneous_Properties|Support]] for starting a scheduler node in paused state.
* Several performance improvements for [[Admin_Job_Activity|Job Activity]] view.

==== Bug Fixes ====
* Removed class reference that was causing failures running Obsidian against Java 10.

== Obsidian 4.5.1 ==
Released April 2018.

=== Features / Enhancements ===
* Upgrade of [[Advanced_Configuration#Dependent_Libraries|bundled Groovy library]] which addresses known Groovy memory leaks.
* [[Getting_Started#Standalone_Scheduler|Standalone mode]] now attempts graceful shut down when SIGTERM is issued.

==== Bug Fixes ====
* [[Authenticator#Customizing_our_LDAP_Authenticator|LDAPAuthenticator]] no longer fails when combining delimited base.dn with search user.
* Defensively protect against possible stack overflow in [[Spring_Integration#Dependency_Injection_via_Spring|SpringContextAware]] for cyclical annotation hierarchies.

== Obsidian 4.5.0 ==
Released March 2018.

=== Features / Enhancements ===
* [[Event_Hooks|Custom Event Hooks]] allow for custom triggers on Obsidian events for things such as instant messaging, customized logging, etc.
* [[Event_Hooks#Slack_Notifier|Slack Notifier]] implemented as an [[Event_Hooks|Event Hook]]
* [[Implementing_Jobs#Async_Jobs|Async job]] support
* [[Implementing_Jobs#Dynamic_List_Providers|Dynamic List Provider]] support
* LDAP [[Authenticator|Authenticator]] to support delimited value [[Advanced_Configuration#Authentication_Properties|configurations]] for dn.base and Obsidian role/group mapping.
* Directory/File classes now provide folder/file in question throwing underlying filesystem exceptions.

==== Bug Fixes ====
* [[Recovery_%26_Failover#Configurable_Job_Recovery|Last recovery]] cron patterns no longer fail crossing some boundaries
* Not all job attributes were being applied in Obsidian [[Initializing_and_Restoring#Startup_Initialization|initialization file]]. Pickup buffer minutes wasn't being used in both create and update cases, job folder wasn't being used in update cases.
* Correct invalid Oracle index name

== Obsidian 4.4.1 ==
Released January 2018.

=== Features / Enhancements ===
* Job Queuer, Spawn Locking, Last Recovery performance improvements, includes a new database index.

==== Bug Fixes ====
* Admin UI restores previous search filter settings. In cases where the last job with a given Job Folder was deleted, or for screens that filter by Job Nickname, the filter was still applied but not visible resulting in no results returned. Now, any invalid options are automatically removed.
* [[Recovery_%26_Failover#Configurable_Job_Recovery|Last Recovery]] in rare cases would recover too far back.

== Obsidian 4.4.0 ==
Released October 2017.

=== Features / Enhancements ===
* Fixed Hosts now support [[Admin_Jobs#Advanced_Options | Blacklists]]
* Job Results now support [[Implementing_Jobs#Customizing_Job_Result_Serialization_and_Deserialization | Custom Serialization/Deserialization]] and default Gson JSON for complex objects.
* [[Advanced_Configuration#Properties_File|Configuration]] values may be specified as System Properties/Environment Variables.
* Obsidian upgrades now support [[Getting_Started#Disabling_DDL_Updates|data-only upgrades]] (structural changes are pre-applied offline).
* Job classes may now be partially introduced into the cluster and subsequently scheduled/executed without being attempted on missing hosts avoiding failures (via JobSpawner parameter ''skipSpawnAttemptsForUnavailableJobs'').
* [[Embedded API]] and [[REST API]]s now return basic audit values (created/updated user/time)

==== Bug Fixes ====
* Obsidian upgrades spanning multiple structural and data changes to a given table no longer fail.

== Obsidian 4.3.0 ==
Released June 2017.

=== Features / Enhancements ===
* [[REST_Endpoints#GET_licence_details_on_an_existing_scheduling_host |REST Endpoint]] and [[Embedded_API#Get_Licence_Health_by_Host|Embedded API]] for Licensing Health Check
* Support Markdown and customizable [[Description_%26_Parameter_Formatting|Formatting]] in Job description and Parameter description annotations
* Support timed wait as the new default on FOR UPDATE statements in Oracle - [[Advanced_Configuration#Database_Properties | Advanced Configuration - Database Properties]]. Old or customized behaviour possible via configuration properties.

==== Bug Fixes ====
* Fix issue in [[Built-in_Jobs#Disabled_Job_Cleanup_Job|DisabledJobCleanupJob]] that fails to delete disabled jobs with chained and/or resubmitted records.

== Obsidian 4.2.1 ==
Released May 2017.

==== Bug Fixes ====
* [[Cron#Recurrence|Recurrence]] schedules in server recovery will fail if last runtime doesn't exist.
* A job that is configured against a job class that has since been removed from the cluster can now be [[Admin_Jobs|loaded]]/[[Admin_Jobs#Deleting|deleted]] from the UI.
* [[Admin_Jobs#Deleting|Delete Job]] - If the delete operation fails for any reason and the operator leaves the modal and returns, the error from the previous operation was still visible.

== Obsidian 4.2.0 ==
Released March 2017.

=== Features / Enhancements ===
* Time Zone support in [[Cron|Cron]] patterns. Allows a cluster running in a single time zone to run jobs designated in different timezones.

==== Bug Fixes ====
* LAST [[Recovery_%26_Failover#Configurable_Job_Recovery|recovery mode]] wouldn't fire latest job on cluster recovery if the job had never fired or if the last runtime had been deleted by the maintenance job.
* ALL [[Recovery_%26_Failover#Configurable_Job_Recovery|recovery mode]] would fire first missed job, but the remaining ones wouldn't run and would be set as OVERLAPPED.
* When creating a new schedule that overlaps one or more previously configured future runtimes with parameters, parameters are now deleted from the database.

== Obsidian 4.1.0 ==
Released February 2017.

=== Features / Enhancements ===
* [[Admin_Jobs#Nickname.2C_Class_and_Folder|Folder]]/tag support for jobs including a [[REST_Endpoints#GET_a_list_of_job_folders|REST]] endpoint and [[Embedded_API#List_Job_Folders|Embedded]] method.

==== Bug Fixes ====
* UI issue in Job Execution Subscriptions and Templates - selected jobs now displaying correctly after save/refresh.
* [[Initializing_and_Restoring#Transfer_or_Restore_a_Configuration|UpdateConfigurationAction]] no longer fails in non-native Authentication mode if an empty Users element is provided.

== Obsidian 4.0.2 ==
Released October 2016.

=== Features / Enhancements ===
* [[Implementing_Jobs#Parameterization|Job Parameter]]s now support an optional <code>description</code> to be displayed in UI Help.

==== Bug Fixes ====
* Fixed an issue where [[Cron#Special_Character_Usage|Cron special character]] <code>L</code> would not work if specified as the only value in a field.
* Fixed 3.8.0 MySQL upgrade script.
* Fixed an issue where Obsidian continued to attempt regular licence verification after a valid site licence had been configured.
* Fixed an issue where table prefixes weren't used in all lookups.

== Obsidian 4.0.1 ==
Released August 2016.

==== Bug Fixes ====
* Fixed bug where a chained job that became conflicted would not evaluate chain conditions once it was no longer conflicted.
* Fixed catalina.base bug and dos line endings in jetty.sh script in bundled jetty server.
* Fixed job parameter edit box resizing bug.

== Obsidian 4.0.0 ==
Released July 2016.

=== Features / Enhancements ===
* All New User Interface
* Obsidian is now built using [[Getting_Started#Supported_Platforms|Java 7]]. No longer supports Java 6.
* [[Getting_Started#Really_Quick_Start_With_H2_and_Jetty|Quick Start]] now uses Jetty.
* Many [[Advanced_Configuration#Dependent_Libraries|updated libraries]] including some that had been updated to Java 7.
** ''Breaking Change'' New H2 library. If you're using the H2 database, you will want to look into [[Initializing_and_Restoring|exporting and restoring]] your Obsidian environment's configuration.
==== Bug Fixes ====
* [[REST_Endpoints#GET_a_system_restore_configuration|GetConfiguration]] filtering no longer fails when Templates/Subscriptions are job targeted.

== All Other Releases ==

=== Obsidian 3.8.0 ===
Released June 2016.

=== Features / Enhancements ===
* [[Job_Features#Resubmission_.26_Ad_Hoc_Runs|Ad Hoc]] runs now may be submitted multiple times per minute. [[Chaining|Chains]] may result in target jobs multiple times per minute. Existing behaviour of [[Admin_Jobs#Execution_.26_Pickup|Chain All]] job configuration remains unchanged.
* [[Built-in_Jobs#Script_Job|Script Job]] now supports best-effort interruption.
* APIs for GET System Restore Configuration support filtering for both [[REST_Endpoints#GET_a_system_restore_configuration|REST]] and [[Embedded_API#Get_System_Restore_Configuration|Embedded]].
* [[Implementing_Jobs#Parameterization|Context]] for job execution now supports retrieving the chain source job config, when applicable. See also the Javadoc for [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/Context.html#getSourceConfig() Context].
* [[Getting_Started#Setting_Host_Names|Host names]] maximum length increased to 255 characters from 50.

==== Bug Fixes ====
* Fixed an issue where [[Admin_Jobs#Execution_.26_Pickup|auto-interrupts]] were not firing.

=== Obsidian 3.7.1 ===
Released April 2016.

=== Features / Enhancements ===
* Job APIs windows now with improved locking/blocking on schedule modifications.

==== Bug Fixes ====
* [[REST_Endpoints#GET_a_system_restore_configuration|GET SystemRestoreConfiguration]] no longer fails when using non-native authentication.

=== Obsidian 3.7.0 ===
Released March 2016.
==== Features / Enhancements ====
* New maintenance job [[Built-in_Jobs#Disabled_Job_Cleanup_Job|Disabled Job Cleanup Job]].
* Support for parameters that are [[Implementing_Jobs#Parameterization|required at runtime]].
* Filter [[REST_Endpoints#GET_a_list_of_an_existing_job.27s_schedules|job schedules endpoint]] by start date and/or end date.
* Return [[REST_Endpoints#GET_details_of_an_existing_job|runtime parameters]] for schedule-based one-time runs.

==== Bug Fixes ====
* [[Embedded_API#Get_System_Restore_Configuration|SystemRestoreConfiguration]] export was only including the last schedule of a job.
* Admin-only hosts fail on startup if not in consistent timezone as cluster.

=== Obsidian 3.6.1 ===
Released February 2016.
==== Features / Enhancements ====
* Enhance JobQueuer to reduce execution time when dealing with large numbers of chain-only jobs.

==== Bug Fixes ====
* Fix issue where job that is scheduled and chained is scheduled late after being chained.

=== Obsidian 3.6.0 ===
Released January 2016.
==== Features / Enhancements ====
* [[Job_Forking|Forked Jobs]] offer jjdchinga tu mad[[Advanced_Configuration#Properties_File|Classpath com.carfey.properties]] no longer required. Applicable when using overrides.

==== Bug Fixes ====
* AutoInterrupt not being set on jobs from [[Initializing_and_Restoring#Jobs|System Restore]].
* RunningHostManager can, in rare cases, evaluate job metadata as a HostInformation entry.
* Schedule calculation on outage looks back one minute too far when considering pickup buffer.

=== Obsidian 3.5.2 ===
Released December 2015.

=== Bug Fixes ===
* With native authentication, at least one Admin User must still exist when making [[Admin_User_Management#Changing_Users|Role Changes]].
* Cleanup of some internal host management functionality.

=== Obsidian 3.5.1 ===
Released November 2015.

=== Features / Enhancements ===
* Obsidian nodes that are set to different timezones but have the same rules (functionally equivalent such as ''America/Los_Angeles'' and ''PST'') may now be run together.
* [[Authenticator|LDAPAuthenticator]] now supports [[Advanced_Configuration#Authentication_Properties|non-dn user attribute logins]].

==== Bug Fixes ====
* [[Admin_User_Management#Viewing_Rights_.26_Changing_Your_Password|My User]] screen would fail when using LDAPAuthenticator. Now shows authorized roles.
* Stale host and timezone records are predeleted on startup.

=== Obsidian 3.5.0 ===
Released November 2015.

=== Features / Enhancements ===
* Support for scanning and locating CGLIB-enhanced classes in [[Spring_Integration|Spring]] and Grails.
* Improved [[Admin_Job_Run_Time_Preview|runtime preview]] listing performance.
* Automatic logging of Obsidian version number no longer requires special configuration.
* [[Authenticator]] implementations including LDAP now support checking user validity when the "remember me" option is used to authenticate. (Remember Me feature removed in 7.0.0 - see [[Release_Notes#Obsidian_7.0.0|Release Notes]].)
* Runtime listing [[REST_Endpoints#GET_a_list_of_scheduled_runtimes_.28supports_multiple_jobs.29|REST endpoint]] and [[Embedded_API#List_Scheduled_Runtimes|Embedded API]] now support specifying a sort order, maximum quantity and parameter filtering, and now guarantee ordering by scheduled time.

=== Bug Fixes ===
* Capped [[Admin_Job_Run_Time_Preview|runtime preview]] results now respect ascending ordering.

=== Obsidian 3.4.1 ===
Released September 2015.

==== Bug Fixes ====
* Remove undesired field jobHistoryRunningId from runtime listing REST endpoint.
* Fixed standalone scripts that would not shutdown instance when hostname could not be determined.
* Shell scripts should always exit with non-zero code on error.
* Improve forked job shell script compatibility.

=== Obsidian 3.4.0 ===
Released September 2015.

==== Features / Enhancements ====
* [[Cron#Recurrence_Start_DateTime|Recurrence]] supports a start datetime.
* [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] support [[Job_Features#Expected_Length_Handling_.28job_execution_duration.29|Auto Interruption]] when maximum expected run length is exceeded.
* [[Implementing_Jobs#Global_Parameters|Global Parameters]] support [[Implementing_Jobs#Global_Substitution_Mode|Global Substitution Mode]].
* Added ''jobClass'' parameter to job search in REST and Embedded APIs.
* Performance improvements in cron and recurrence calculations.
* Add database index for recovery performance.
* Support for [[Advanced_Configuration#Database_Properties|disabling internal connection pool]].
* Support [[Advanced_Configuration#Miscellaneous_Properties|base HREF overrides]] for load balancers, etc.
* JobHistoryCleanupJob always cleans up expired schedules according to <code>maxAgeDays</code> parameter.

==== Bug Fixes ====
* Default sequence_manager pool to 10% of connections with min of 2.
* Fix issue where parameter order is not maintained consistently on PostgreSQL
* Fix issue where JobHistoryCleanupJob misses cleaning up jobs that are in MISSED state.
* JobHistoryCleanupJob leaves latest runtime record to ensure Recurrence schedules fire at correct time.

=== Obsidian 3.3.3 ===
Released August 2015.

==== Bug Fixes ====
* Chain Skipped and Conflict Missed job runtime enum values corrected to use underscores in REST/Embedded API when listing runtimes.
* In rare cases, outages or queuing delays could prevent first job history from ever being queued.
* Job initial schedule end time not editable via text entry when cloned.

=== Obsidian 3.3.2 ===
Released June 2015.

==== Bug Fixes ====
* Restore missing fields on Runtime and RuntimeError classes for REST/Embedded API.
* Defensive handling of missing JOB_STATE records in chaining.
* Job class field in job edit screen loses content if enter is pressed without match.
* Obsidian version added to dispatcher logs.

=== Obsidian 3.3.1 ===
Released June 2015.
==== Features / Enhancements ====
* Case-sensitive collation support for SQL Server.
* Unicode support on SQL Server (please note that existing schemas will not be upgraded automatically).
* Unicode fixes for all platforms.
* Whitespace characters permitted in between delimited schedules.
* Improved logging on warning and error conditions.

==== Bug Fixes ====
* JobSearch not working on Oracle since 3.3.0.

=== Obsidian 3.3.0 ===
Released May 2015.
==== Features / Enhancements ====
* [[Implementing_Jobs#List_Parameterization|Job parameterization]] support for picklists of valid values.
* [[Implementing_Jobs#Dynamic_File_Lists|Server-side file listing]] support.
* Support for multiple [[Cron#Basic_Format|Cron]] schedule patterns.
* [[Admin_Job_Chains#Chain_Tree_View|Tree visualization of chains]].
* [[Admin_Job_Chains#Conditional_Chaining_Configuration|Conditional chains]] now support text ordinal comparisons.
* Added optional [[Admin_Job_Chains#Adding_or_Updating_a_Job_Chain|chain description]].
* Spawning and queuing performance improvements.

==== Bug Fixes ====
* Expired job schedules are no longer deleted when new schedules are applied. A patch is introduced in this release to find and create placeholder schedules for these jobs.
* [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup Job]] allowed configuration of maxAgeScheduleDays to be lower than maxAgeDays resulting in schedules being deleted for which there is still job history.

=== Obsidian 3.2.0 ===
Released April 2015.
==== Features / Enhancements ====
* [[Cron#Recurrence|Recurrence]] job schedules.
* Upgrade to latest Java mail library.
* Support for determining user that initiated a [[Implementing_Jobs#Interruptable_Jobs|job interrupt]].
* Pickup time in [[Job Forking|forked jobs]] now reflects JVM startup to more accurately report execution times.

==== Bug Fixes ====
* Adding new schedule with outstanding auto-retry execution no longer fails.
* Prevent license checks making extra calls.
* Ensure auto retries with 0 interval are executed as soon as possible, instead of after at least one minute.

=== Obsidian 3.1.1 ===
Released April 2015.
==== Bug Fixes ====
* Fix critical bug where successful job runs after failures would be marked as failed due to job recovery handling.

=== Obsidian 3.1.0 ===
Released March 2015.
==== Features / Enhancements ====
* SQL Server 2008-2014 support.
* Improve event log messages.
* "?" now equivalent to "*" in cron schedules.

==== Bug Fixes ====
* Prevent event log messages being dispatched before commit of source data.
* Fix delayed result set cleanup in job queuer in rare cases.

=== Obsidian 3.0.1 ===
Released February 2015.
==== Features / Enhancements ====
* Job schedule preview and update performance improvements.
* Job delete performance improvements for jobs with large number of history records.
* [[Implementing_Jobs#Classpath_Scanning|Classpath scanning]] interval now configurable (useful for job forking).
* [[Built-in_Jobs#Job_History_Cleanup_Job|JobHistoryCleanupJob]] now supports deleting old schedules.

==== Bug Fixes ====
* Jobs running on hosts that are disabled during execution will now flag them as FAILED or COMPLETED as expected.
* Ensure identical job schedule states which butt against each other are merged.
* Set catalina.base property at Winstone startup so default log configuration works.

=== Obsidian 3.0.0 ===
Released February 2015.
==== Features / Enhancements ====
* [[Job Forking|Job forking]] added to support distinct JVM instances for each job execution.
* Full API expansion. APIs now support all functionality exposed by the admin web application. See [[REST Endpoints|REST API]] and [[Embedded API]] for details.
* Pretty URLs and login redirects in admin web application, including bookmark support.
* [[Clustering#Host_Preference|Host preference]] support.
* Full [[Initializing and Restoring|initialization and restoration]] support for Obsidian instances.
* Auto-polling for job history, logs and sent notifications views in admin web application.
* [[Admin_Custom_Calendars#Deleting|Custom calendar delete]] support. Also available in APIs.
* Convenience database [[Upgrading_Obsidian#Database_Upgrade_Scripts|upgrade]] and [[Getting_Started#Database_Creation_Scripts|create]] scripts included in installation bundle. Automatic version upgrades still supported.
* Better [[Implementing_Jobs#Inheritance|inheritance options]] for defined job parameters.

==== Bug Fixes ====
* Fix LAST recovery type when job left in READY state.
* Redirect to proper 404 and error pages.
* Optimize persistence calls to better handle large number of schedules per job.
* Fix LDAPAuthenticator group membership attribute lookup.
* Explicitly shut down daemon connection reaper thread at Obsidian shutdown.
* Fix minor bugs with schedule merges and splits.
* Fix warning shown in rare cases on job history listing.
* Minor help user interface fixes.
* Minor job chain user interface fixes.
* Prevent system parameter sort order changing on updates.
* Fix record duplicates in job history and corresponding APIs caused by multiple chains which have the same source and target jobs.

=== Obsidian 2.9.1 ===
Released November 2014.
==== Bug Fixes ====
* Fixed issue where auto retry caused failure during a Disabled window.
* Fixed filenames on screen data downloads.
* Fixed issue with Last recovery when last executed time to current time spanned a Disabled window.
* Graceful handling of host designator update interruptions.

=== Obsidian 2.9.0 ===
Released November 2014.
==== Features / Enhancements ====
* [[Conflicts#Jobs_in_Multiple_Conflict_Sets|Jobs in multiple conflict sets]].
* Add ad hoc flag to Context object supplied to SchedulableJob instances.
* Improved [[Admin_Job_Chains#Conditional_Chaining_Configuration|chain detail]] messages in [[Admin_Job_History_(3.x.x and earlier)#Job_History_Details|job history details]] table.
* Ability to set the host designator for multiple Obsidian instances in the same JVM via <code>com.carfey.obsidian.schedulerDesignation</code> in the [[Advanced Configuration|properties file]].
* Job queuing performance improvements

==== Bug Fixes ====
* Ensure license check multiple is at least 2 in [[Admin_System_(3.x.x and earlier)|System]] tab.
* When recovering jobs which had died, new jobs were flagged as Overlapped instead of Missed.
* All recovery type resulting in Abandoned jobs incorrectly.
* Breadcrumbs incorrect when cloning a job.
* JNDI cannot be used when the key does not start with "java:" prefix. <ref>

If you are using automated installer files from previous releases and are using JNDI, you may add <pre><entry key="database.jndi.name" value="yourJNDIPath"/></pre> anywhere under the userInput element of UserInputPanel.3 and empty out the value for '''database.url'''. For example,
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.3">
<userInput>
<entry key="db.schema" value=""/>
'''''<entry key="database.url" value=""/>'''''
<entry key="database.password" value=""/>
<entry key="database.table.prefix" value=""/>
<entry key="database.connection.timeout" value="2000"/>
<entry key="database.username" value=""/>
'''''<entry key="database.jndi.name" value="java:comp/env/jdbc/obsidianJNDI"/>'''''
<entry key="database.max.connections" value="40"/>
<entry key="include.all.jdbc" value="false"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>

</ref>
* Database connections not rolled back just before close when removed from the pool, resulting in warning log messages.
* Sanitize HTTP headers, email subjects, etc. to prevent injection issues.

=== Obsidian 2.8.1 ===
Released September 2014.
==== Features / Enhancements ====
* New connection pool reaper to draw down pool size if usage allows.

==== Bug Fixes ====
* More explicit handling of connection pool emptying on Obsidian shutdown.

=== Obsidian 2.8.0 ===
Released September 2014.
==== Features / Enhancements ====
* Login popup when session expires in [[Admin_Web_Application_Guide|admin web application]]. Users can now log back in without losing their changes.
* Support for using [[Advanced_Configuration|context classloader]] via configuration property ''com.carfey.jdk.useContextClassLoader''.
* Reduced number of connections required for normal operation. Previously, up to 1 connection per job per minute was required.
* Minor user interface improvements.
* Support for re-queuing jobs rejected from the job thread pool (via parameter ''queueJobsOnPoolRejection'').
* Improved default log4j rolling file appender configuration.

==== Bug Fixes ====
* Fix NullPointerException on job recovery when last job was rejected by the thread pool.
* Fix rare instances of licenses not being released due to token file issues
* Fix poor validation message on saving if invalid boolean system parameter.

=== Obsidian 2.7.1 ===
Released August 2014.
==== Features / Enhancements ====
* [[REST_API#Authentication_.26_Authorization|REST authentication]] can be configured to be optional.
* Cron pattern expansion. Support range increments (e.g. 3-20/5)

==== Bug Fixes ====
* Fix NullPointerException in handling mdoodood..dkididkdkd
IP changes.
* Upgraded to TLD 2.0 fixing Obsidian WAR deployment in JBoss 6.

=== Obsidian 2.7.0 ===
Released July 2014.
==== Features / Enhancements ====
* [[Admin_Notifications#Job_Execution_Subscriptions|Re-tooled job execution notifications]], including [[Admin_Notifications#Conditional_Job_Notification_Configuration|conditional notifications]]
* We have open-sourced all of our [[Built-in_Jobs | built-in jobs]]!
* File-based job [[Implementing_Jobs#Initializing_Job_Schedules|initialization]].

==== Bug Fixes ====
* Fix page jumping when modifying job chain conditions on long pages.

=== Obsidian 2.6.1 ===
Released June 2014.
==== Features / Enhancements ====
* Cygwin support in startup/shutdown scripts.
* Run parameters override configured parameters.

==== Bug Fixes ====
* Oracle CLOB field storage fix.
* Fix single-node mode on host with no recognizable NIC.
* Prevent currently or soon to be running jobs from being deleted.
* Fix multiple job history parameters failing on H2.

=== Obsidian 2.6.0 ===
Released May 2014.
==== Features / Enhancements ====
* [[Implementing_Jobs#Classpath_for_Building_and_Deploying|Job implementation metadata stored in database]]. Admin UI deployments no longer require Job Implementations on the classpath in order to schedule and configure.
* Delete Chain support in [[Admin_Job_Chains#Deleting|UI]], [[Embedded_API#Delete_a_Job_Chain|Embedded API]] and [[REST_Endpoints#DELETE_an_existing_job_chain|REST API]]
* Hardware-linked licensing supported in public Obsidian bundle.

==== Bug Fixes ====
* Fixed [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] to work in WebLogic 12c.
* Fixed chain recovery date ranges being overly broad.
* Ensure any stale timezone records are cleaned up.
* Removed some libraries stored multiple times in installer.

=== Obsidian 2.5.1 ===
Released April 2014.
==== Features / Enhancements ====
* Expose convenience JobId and Nickname getters in [[Implementing_Jobs#SchedulableJob_Interface|Context]].
* Improved performance of chaining recovery.
* [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|JarJar]] bytecode modification support now includes gson.<ref>

If you are using automated installer files from previous releases, you may add <pre><entry key="jarjar.gson" value="true"/></pre> or <pre><entry key="jarjar.gson" value="false"/></pre> according to your desired usage anywhere under the userInput element of UserInputPanel.14. For example,
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.14">
<userInput>
'''''<entry key="jarjar.gson" value="false"/>'''''
<entry key="jarjar.jxl" value="false"/>
<entry key="jarjar.dom4j" value="false"/>
<entry key="jarjar.jmustache" value="false"/>
<entry key="jarjar.opencsv" value="false"/>
<entry key="jarjar.h2" value="false"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>

</ref>
* Introduced support for having a scheduler and non-scheduler instance running in same class-space.

==== Bug Fixes ====
* Improved failure messaging when a scheduler node is started in a different time zone than the current nodes in the cluster.
* Chain search filters aren't saved.
* Exclude unneeded web jars from standalone installations.

=== Obsidian 2.5.0 ===
Released March 2014.
==== Features / Enhancements ====
* [[Admin_Jobs#Execution_.26_Pickup|Retry Interval]] support for Auto Retry of failed jobs.
* [[Admin_Global_Parameters|Global Job Parameter]] support.
* [[Installation_Guide#JNDI_Configuration|JNDI Support]] for Database Connections and Email Sessions.
* MariaDB 5.5 support.
* JBoss AS 7 support.
* Text filter on Job Chain View.
* [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|JarJar]] bytecode modification support during installation to avoid dependency conflicts.
* Embedded API Javadoc artifact included in installation.

==== Bug Fixes ====
* Support */2 cron expressions, [[Admin_Jobs#Edit.2C_View_.26_Change_Schedules|Schedule Inputs]] extended to 255 characters.
* REST API - [[REST_Endpoints#GET_a_list_of_jobs|JobListing]].<code>getJobs()</code> was returning <code>List<Job></code> instead of <code>List<JobState></code>.
* Support multiple keys in key server proxy.
* Support VFS URLs in [[Implementing_Jobs#Classpath_Scanning|Classpath Scanner]] for JBoss.
* Postgres failed on blank schema.
* Job resubmission validates that job isn't disabled for next minute instead of current minute.
* Embedded API - [[Embedded_API#Delete_a_Job|Delete Job]] would fail if job class has since been removed from classpath.
* [[Admin_Jobs#Job_Listing|Job Listing]] schedule/state defaults to next minute.
* Filters aren't saved consistently on search screens and never saved for runtime preview.
* Table settings aren't saved on [[Admin_Jobs#Job_Listing|Job Listing]].

=== Obsidian 2.4.1 ===
Released February 2014.
==== Bug Fixes ====
* Fix installer not working in console mode.
* Ensure that defined job parameters and their values are returned in the original configured order.

=== Obsidian 2.4.0 ===
Released February 2014.
==== Features / Enhancements ====
* New [[Getting_Started|graphical installer and simplified startup scripts]].
* Full support for job chaining and conflicts in the [[REST API]] and [[Embedded API]].
* Revamped WebSphere support (8.5).
* [[Scripting Jobs]] can now be configured with a script file path instead of the script itself.
* New [[Built-in_Jobs#MySqlBackupJob|MySqlBackupJob]] built-in job.
* Informational message logged when a new version of Obsidian is available.
* [[Admin_User_Management#Deleting_Users|Delete user]] support.

==== Bug Fixes ====
* Fixed job execution recovery not working in some cases when the database is temporarily unavailable.
* Fix PostgreSQL connections not released from pool properly when connection is invalid.
* Fix [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] on WebSphere.
* Fix UI rendering issue on Jobs screen on WebSphere.

=== Obsidian 2.3.1 ===
Released December 2013.
==== Features / Enhancements ====
* New [[Built-in_Jobs#Script_Job|Script File Job]]
* Improved responsiveness of job interrupts for built-in jobs.
* UI tweak to [[Jobs]] screen to avoid displaying custom calendars when not in use.

==== Bug Fixes ====
* Update default log configuration for Tomcat to use <code>catalina.base</code>, which works consistently on *nix platforms.
* Remove redundant event logging for job success and failure in the Job Spawner category.
* Handle releasing licenses even when temp directory is not writable, and attempt to use working directory as a fallback.
* Job names containing ampersands did not work as filters in search screens.
* Host designator assigned earlier in startup to ensure logging accurately reports the host.

=== Obsidian 2.3.0 ===
Released November 2013.
==== Features / Enhancements ====
* Fully unified [[Embedded API]] which contains same operations and has same semantics as the [[REST API]]. The previous Legacy API is now deprecated.
* [[REST API]] bean classes bundled in <code>obsidian.jar</code> for simplified Java integration.
* Submission of [[Admin_Jobs#Ad_Hoc_.26_One-Time_Run_Submission|one-time job runs]] via the UI now allows specifying exact minutes instead of 5 minute intervals.
* [[Chaining]] evaluation is now fully recoverable. Processing of chaining now processed independently of job execution.
* Dozens of UI tweaks and improvements.
* Stale hosts in [[Systems|Systems tab]] now are pruned after about an hour of inactivity. Host disabling is preserved if the node is restored.
* Graceful shutdown in Winstone for [[Getting Started|quick start]] method.
* [[Jobs#Custom_Calendars|Custom Calendars]] can now be specified with multiple delimiters, including new lines and spaces.
* [[Email Templates]] can now include the event category.
* Track most recent upgraded version in the database.
* Job runtime [[REST_Endpoints#GET_a_list_of_scheduled_runtimes_.28supports_multiple_jobs.29|REST endpoint]] now defaults to a more useful previous 24-hour window.

==== Bug Fixes ====
* Chain All setting not shown correctly when editing existing [[Jobs]].
* Abandoned, Missed and Conflict Missed chaining never fires.
* Current scheduled state not shown correctly for existing jobs in [[Jobs]] in Winstone.
* Export on [[Logs]] contained extra text in ID column.
* Chained jobs now respect host restrictions.
* Correct custom calendar reversed PUT/POST for [[REST API]], and implement standardized date formatting.
* UI table listings no longer flash error message when quickly navigating away during a request.
* Legacy API calls no longer incorrectly start non-daemon threads for notifications and event logging.
* Lock issues when evaluating many [[Chaining|chained jobs]].

=== Obsidian 2.2.1 ===
Released October 2013.
==== Features / Enhancements ====
* Enhanced [[Spring_Integration|Spring Integration]] to remove need for distinct [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]]. Jobs can be auto detected from Spring context.
* Enhanced [[Job_Features#Host_Restrictions_or_Affinity|Running Hosts Restrictions]]. Now a configuration value can be used to determine if these restrictions apply to Ad Hoc jobs.
* Ability to [[Getting_Started#Disabling_Automatic_Database_Updates|disable database updates]] on startup.
* Add helpful text to job screen indicating you can type in a job class Obsidian
* Additional Spring support for [[Spring_Integration#Wiring_an_Embedded_Obsidian_Scheduler|embedded schedulers]].

==== Bug Fixes ====
* Corrected issue where classpath scanning configuration values were being overridden back to default on each restart (introducted in 2.1).
* Fix SchedulerStarter shutting down JVM in embedded mode.

=== Obsidian 2.2.0 ===
Released October 2013.
==== Features / Enhancements ====
* [[Spring_Integration|Spring]] Dependency Injection support.
* [[Built-in_Jobs#File_Scanner_Job|File scanner]] job.
* [[Advanced_Configuration#Dependent_Libraries|Python and Groovy]] libs updated. Python from jython.jar (version 2.5.2rc2) to jython-standalone-2.5.3.jar. Groovy from groovy-all-1.7.6.jar to groovy-all-2.1.8.jar.

==== Bug Fixes ====
* DBAuthenticator is now defaulted configuration. Improved handling of bad configuration on startup.
* Obsidian web app startup no longer attempts to start the scheduler with certain types of unrecoverable bad configuration.
* Fixed issue where classpath scanner only worked in Admin Web Application if running with an embedded scheduler.
* Fixed issue where Auto Failure Retry combined with triggered Job Chaining resulted in chaining failure.
* Cleaned up Job History Search Results File Export that could contain garbage characters.
* Fixed issue where job runtime preview fails when only disabled job state exists.
* Fixed TRACE logging level - No logging output if level explicitly set to TRACE.
* Remove unnecessary JAR files bundled with the installation package.

=== Obsidian 2.1.1 ===
Released September 2013.
==== Features / Enhancements ====
* [[Admin_Jobs#Run_Parameters|Ad Hoc / One-Time Run Job Parameterization]].
* Obsidian license purchases via Stripe.
* All Carfey Software libraries bundled into single obsidian.jar.

==== Bug Fixes ====
* Postgres schema support - only supported public schema.
* LogCleanupJob does not validate specified LEVEL attribute.
* LDAPAuthenticator assumed ''cn'' in building ''dn'' for authentication. Now configurable - see [[Advanced_Configuration#Configuration_Details|Advanced Configuration]].
* LDAPAuthenticator assumed only ''uniqueMember'' for group membership. Now also checks other common attributes, supporting ActiveDirectory. See [[Authenticator#Customizing_our_LDAP_Authenticator|LDAP Authenticator]].
* ''run.obsidian'' target execution classpath included in Obsidian bundle includes non-jar/non-resource files.
* Site license verification runs once on startup instead of every lease cycle.
* Date parsing issue related to Locales on retrieving and refreshing license. Fixed in [http://sourceforge.net/projects/carfeydate/ release 1.2 of carfey-date].
* In rare cases, job results in Job History listing could be mangled.
* Proxy key server would fail on requests when run from time zones different from the master key server.
* Oracle job results limited to 2000 characters - now unlimited on all platforms.

=== Obsidian 2.1 ===
Released July 2013.
==== Features / Enhancements ====
* [[Obsidian_Tables|Table name prefix]] support.
* [[Licenses & Nodes|Site license]] support in public Obsidian bundle.
* [[Advanced_Configuration#Properties_File|Programmatic properties]] override support.
* Alternate [[Advanced_Configuration#Configuration_Details|schema user/owner]] support. Additional Oracle details [[Obsidian_Tables#Oracle_Privileges|here]].
* [[Admin_Notifications#Deleting_a_Subscriber|Delete subscriber]] support.

==== Bug Fixes ====
* Ensure all [[Admin_Logs|Event Log]] messaging to always use Display Name for enums.
* Expand script job disabling to disable all potentially dangerous jobs.
* Ensure internal class AnnotatedSchedulableJob is always excluded from available class listing in [[Admin_Jobs#Job_Nickname_and_Class|Job Admin]].
* Upgraded to more recent Oracle JDBC driver (11.2.0.3)
* Various database metadata optimizations
* [[Implementing_Jobs#Classpath_Scanning|Classpath scanner]] rescans on parameter changes.

=== Obsidian 2.0 ===
Released June 2013.
==== Features / Enhancements ====
* [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] to automatically populate Job UI with available jobs.
* Fully customizable [[Email_Templates|Email Templates]].
* New [[Embedded_API|Embedded API]] operations exposed so job configuration can be manipulated without REST API or UI.
* [[Admin_Jobs#Custom_Calendars|Custom Calendar]] support to add date-based exclusions to job schedules (e.g. holidays).
* New [[Admin_User_Management#User_Rights|Limited Read]] role which restricts access to potentially sensitive configuration.
* New [[Built-in_Jobs|Built-in Jobs]] - file archival and file clean up.
* Easy [[Admin_Jobs#Job_Listing|job cloning]] in UI.
* [[Built-in_Jobs#Shell_Script_Jobs|Shell scripting]] job support.
* Additional [[Admin_Jobs#Job_Edit_Screen|job execution options]] - auto-retries on failure and new "Chain All" chaining mode.

==== Bug Fixes ====
* Improve logging of some trapped exceptions.
* Improve handling of spawn locks to reduce contention.
* Fix standalone execution from Ant script.

=== Obsidian 1.5.2 ===
Released May 2013.
==== Features / Enhancements ====
* Job nickname lengthened from 50 to 255 characters to allow more specific nicknames.
* Database metadata loading restricted to known Obsidian application tables.
* Add support in [[REST_Endpoints#Job_Endpoints|job listing endpoint]] for nickname and job custom parameter tag search.

==== Bug Fixes ====
* Fixed JobHistoryCleanupJob failures that occurred when a record to be cleaned up had been interrupted.
* Disallow failed job resubmission if the job is currently running. This prevents these resubmissions from potentially being ABANDONED due to execution duration exceeding pickup buffer minutes specified on the job. Job is available for resubmission once currently running job completes.

=== Obsidian 1.5.1 ===
Released February 2013.
==== Features / Enhancements ====
* [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]], including new [[REST_API|REST API]] endpoint.
* Spawning improvements to seek minute boundaries more consistently.
* Runtime preview now defaults to start time to current time.
* Improved license handling for paid licenses to increase reliability in case of outages.
* A handful of minor UI tweaks and additions.

==== Bug Fixes ====
* Fix connection handling when database connectivity is lost in spawner or queuer threads.
* Fix criteria causing some running conflicts to be not found resulting in conflicted jobs running concurrently.
* Improve messaging and details when failing to connect to MySQL.
* Various UI fixes.
* Events for jobs would sometimes be dispatched for the wrong target.

=== Obsidian 1.5 ===
Released January 2013.
==== Features / Enhancements ====
* [[REST_API|REST API]] for a complete range of job, scheduling and host management features.
* Export support in Excel, CSV and XML in [[Admin_Job_History_(3.x.x and earlier)#Exporting_Results|Job History]], [[Admin_Jobs#Exporting_Results|Job]], [[Admin_Job_Run_Time_Preview|Job Runtimes]], [[Admin_Logs#Exporting_Results|Log]] and [[Admin_Notifications#Sent_Notifications_Screen|Sent Notifications]] views.
* Expected job run time parameters - [[Admin_Jobs#Execution_.26_Pickup|See Expected Length]]. Events trigger in cases where execution duration is outside of defined threshold.
* Display actual run duration in job history view
* Enhance run once future date pattern to match actual future date. Contributes to consistency in job state absorption in new overlapping state ranges.
* Allow single node to run without valid lease
* Add 90/120 minutes pickup buffer option

==== Bug Fixes ====
* Ad hoc submission validation text inconsistent
* Job set to ad hoc active state would not allow one-time immediate submissions.
* Workaround String indexoutofbounds issue with winstone server
* Read-only users can submit one-time job runs.
* Can't save unscheduled active job in postgresql
* After saving new user, help icon disappears
* MySQL - Audit columns hit truncation error when registered user is too long
* Various display bugs

=== Obsidian 1.4.2 ===
==== Bug Fixes ====
* Lock wait timeout fix

=== Obsidian 1.4.1 ===
==== Features / Enhancements ====
* Conditional [[Chaining]] support.
* [[Admin_Jobs#Deleting|Delete]] job support.
* [[Admin_Jobs#Job_Listing|Job]] view filter inclusivity those with only future states.
==== Bug Fixes ====
* Default initial sorts case insenstive
* Status scheduling allowed for gaps
* Failed conditional chain prevents scheduling of job
* Schedule preview isn't ordered by effective date
* JobHistory order by clause sometimes ignored

=== Obsidian 1.4 ===
==== Features / Enhancements ====
* View of saved job history [[Admin_Job_History_(3.x.x and earlier)#Job_History_Details|results]].
* Add schedule shortcut link on Job view
==== Bug Fixes ====
* Various display bugs

== Footnotes ==
<references/>

Getting Started

2026-07-31T15:11:41Z

Craig:

This Getting Started is for Obsidian 4.0 and newer versions.''

This guide will help you choose a deployment setup that works for you, and then get it running. Before reading this page, you may wish to review Obsidian's [[Deployment Models]] to understand the different parts of Obsidian or to find out what deployment model works for you.

If you've are looking to start writing your own Obsidian jobs, see [[Implementing Jobs]].

= Supported Platforms =

Please quickly review our supported platforms before continuing.

* Obsidian is OS-independent, and runs on the Java Virtual Machine. It works in a variety of environments, including Linux, OSX and Windows, and can be run inside virtual machines.
* Obsidian 5.x.x, 6.x.x and 7.x.x run on Java 11 or above (Obsidian 4.x.x runs on Java 1.7 or above). A JRE is sufficient — the embedded Tomcat runtime does not compile JSPs and needs no JDK.
* Obsidian's administration web application is a servlet application.
** 7.x.x has been tested on Tomcat 10.x
** 6.x.x has been tested on Tomcat 10.x and Jetty 11.x (Jakarta Servlet 5.0)
** 5.x.x has been tested on Tomcat 9.x and Jetty 10.x (Javax Servlet 4.0)
** 4.x.x has been tested on Tomcat 7, 8 & 8.5 and Jetty 9.x (Javax Servlet 4.0)
* It works on all modern browsers and is tested on recent versions of Chrome, Edge and Firefox.
* Obsidian requires one of the following fully-supported database platforms:
** MySQL 8.0.x (Obsidian 5.x and higher), 5.5-5.7 (excluding Galera)
** MariaDB 5.5
** Oracle 18c, 19c, 21c on Obsidian 5.x and higher
** Oracle 10g, 11.x, 12c on versions prior to Obsidian 5.0.0
** PostgreSQL 11-16 on Obsidian 5.x and higher
** PostgreSQL 9, 10
** MS SQL Server 2008-2019
** H2 1.4.
** ''Larger major versions are likely to work without issues but are not officially supported.''

'''Note:''' With some exceptions, clustered scheduler instances require access to contact license servers over the Internet, or access to an internal proxy license server. See [[Licenses & Nodes]] for more information.

== Hardware Requirements ==

We recommend the following minimum hardware for typical installations:

* 1 GHz processor
* 2 GB RAM
* 1 GB hard disk space (excluding accumulated logs)

Note that actual requirements may vary depending on job volume, clustering and other factors.

= Choose Your Installation Type =

Obsidian consists of two main processes:

* '''Scheduler''' - schedules and executes jobs, sends notifications, etc. Also exposes the [[Embedded API]].
* '''Admin Web Application''' - provides management and monitoring UI, plus the [[REST API]] and [[Embedded API]].

These can be run together or separately in the following configurations. You will pick one or more of these options together to provide both the scheduler and admin web application functionality.

# '''Standalone Scheduler''' - A Java process that performs job execution. A standalone scheduler installation is generated when you run the Obsidian installer, and may be customized by adding JAR files containing your job code. It is started and stopped by scripts included with the installation. Requires a separate admin web application to be deployed.
# '''Embedded Scheduler''' - Provides job execution like a standalone scheduler, but instead runs as a process embedded within and started from your application. This eliminates the need to customize and deploy a separate artifact which will perform job execution. Requires a separate admin web application to be deployed.
# '''Standalone Admin Web Application''' - A Java servlet application providing Obsidian's administration capabilities but no scheduling services. A standalone admin application WAR file is generated when you run the Obsidian installer, and may be customized by adding JAR files containing your job code. Requires a separate standalone, embedded or combined scheduler and web application to be deployed for job execution to be performed.
# '''Combined Scheduler and Admin Web Application''' - A version of the admin web application which also runs a scheduler service for job execution. A combined scheduler and admin application WAR file is generated when you run the Obsidian installer, and may be customized by adding JAR files containing your job code.

Regardless of the deployment configuration, any time you run more than one scheduler process operating against the same Obsidian database, they will automatically form a cluster and share in job execution.

Choosing which installation type works best for you depends on your specific needs. The setups which are suitable for most cases are, in order:

* Using an '''Embedded Scheduler''' (option 2), along with a '''Standalone Admin Web Application''' (option 3). This approach lets you embed Obsidian into your existing application without having to alter the Obsidian artifacts to include your job code. Instead, Obsidian's required libraries are included in your application and they are deployed together.
* Using a '''Combined Scheduler and Admin Web Application''' (option 4) alone or in a cluster. This is suitable if you don't have another application containing job code for Obsidian to execute, or if you simply want to use Obsidian's scripting support, which doesn't require deploying JAR files.

= Downloading Obsidian =
Just go to our [https://web.obsidianscheduler.com/download/ download page], and grab the latest Obsidian's installation zip file. There is no need to register or obtain a license before downloading.

Once you've downloaded the zip file, extract it to a directory of your choice.

If you are trying to upgrade to a newer version of Obsidian, see [[Upgrading_Obsidian|upgrade]] instructions.

= Quick Start for Evaluation Purposes =

If you wish to quickly try Obsidian without minimal setup required, follow these steps. Otherwise, skip ahead to [[#Initial Setup|Initial Setup]].

== Really Quick Method Using Embedded Database ==

''We do not recommend this setup for production use. ''

# Ensure you have a JDK (11 or up for Obsidian 6.x.x & 5.x.x, 1.7 or up for Obsidian 4.x.x) installed and that the <code>JAVA_HOME</code> environment variable is set to your JDK installation directory.
# Unzip the Obsidian download zip file to a directory of your choice.
# At the command line, in the zip extraction directory, run the [[Installation_Guide|installer]] using this command, substituting the appropriate Obsidian version number: <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>
# Start Obsidian using the command: <code>./webObsidian.sh start scheduler</code> for Linux or <code>webObsidian.bat start scheduler</code> for Windows.
# Go to http://localhost:8080 in your browser and check out your fully functional Obsidian web application and scheduler! You can log in to the admin web application with the default user ''admin'' and password ''changeme''.
# When you're done, stop Obsidian using the command: <code>./webObsidian.sh stop</code> or <code>webObsidian.bat stop</code> for Windows.

'''Note:''' If you restart the Quick Start installation and see "lock wait timeout" or similar errors in the log screen, you may have to delete your embedded H2 database lock file. By default, the file name is ''obsidian.lock.db'' and is located in the user home directory.

'''Note:''' If you see a <code>java.net.BindException: Permission denied</code> error on startup, you will need to use an alternate port. See [[Troubleshooting]] for details on how to change this.

== Quick Method Using Existing Database ==

If you wish to get Obsidian running quickly using a database platform you already have running, follow these steps:

# Ensure you have a JDK (11 or up for Obsidian 6.x.x and 5.x.x, 1.7 or up for Obsidian 4.x.x) installed and that the <code>JAVA_HOME</code> environment variable is set to your JDK installation directory.
# Unzip the Obsidian download zip file to a directory of your choice.
# At the command line, in the zip extraction directory, run the [[Installation_Guide|installer]] using this command, substituting the appropriate Obsidian version number: <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code>
# Start Obsidian using the command: <code>./webObsidian.sh start scheduler</code> for Linux or <code>webObsidian.bat start scheduler</code> for Windows.
# Go to http://localhost:8080 in your browser and check out your fully functional Obsidian web application and scheduler! You can log in to the admin web application with the default user ''admin'' and password ''changeme''.
# When you're done, stop Obsidian using the command: <code>./webObsidian.sh stop</code> or <code>webObsidian.bat stop</code> for Windows.

= Initial Setup =

This section covers the setup required after you've selected your [[#Choose_Your_Installation_Type|installation type]].

== Database ==

Obsidian requires a database which must be created before running Obsidian. Multiple [[#Supported Platforms|database platforms]] are supported. Obsidian can share a database/schema with another application.

Note that the database must exist before deployment, but by default Obsidian will automatically create all required tables.

Later, you will specify database connection parameters within Obsidian's installer to tell it how to connect. If you need to configure advanced settings or change settings directly after you've run run the installer, see [[Advanced Configuration]].

'''Note:''' Obsidian needs to create the tables in the target database. If the schema is shared with your application’s tables, please ensure there are no name conflicts. If there are conflicts, separate schemas/databases can be used, or a table prefix can be specified as shown in [[Advanced_Configuration#Database_Properties|Advanced Configuration]]. [[Obsidian Tables]] lists the tables Obsidian will created upon first deployment.

=== Manual Schema Creation ===

When you start Obsidian, it will automatically detect and create missing tables in your target database. However, if you wish to run Obsidian with a database user that does not have create privileges, or simply wish to prepare your database structure ahead of time, you can use the database scripts provided with your download zip file under the "db_scripts" directory.

First create your database, and locate the "complete.sql" file under the directory for the database you are using under the "db_scripts" directory. Statements within this file contain the token "$px$" to enable table prefixes. Before you run the SQL file, replace all instances of the token "$px$" (without quotes) with a table prefix 6 characters or shorter (letters and underscores supported), or with blank.

Then, in your SQL client of choice, execute the script and all the required Obsidian tables will be created.

=== Alternate Oracle Schemas ===

After allowing Obsidian to create all the required tables and initial data by deploying it a single time, Obsidian can be run with an alternate Oracle user by specifying the target schema on Oracle databases. See [[Advanced_Configuration#Database_Properties|Advanced Configuration]] for the property to set.

If you use a separate user from the schema owner, you must grant the user [[Obsidian_Tables#Oracle Privileges|certain privileges]] for Obsidian to function correctly.

=== MS SQL Server Snapshot Isolation ===

For maximum compatibility and to avoid deadlocks, MS SQL Server should be configured to use [https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/sql/snapshot-isolation-in-sql-server read committed snapshot isolation].

This can be enabled on your database by running the following commands:

<pre>
ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON
</pre>

== Authentication ==

By default, Obsidian manages its own set users and logins to restrict access to the admin web application and REST API. A default “admin” user is created when the scheduler is first deployed and no additional setup is required.

Alternatively, to use LDAP authentication, select the LDAP option in the installer and enter your LDAP details.

As of 7.0.0, you can also select OAuth / OIDC or SAML 2.0 authentication to enable Single Sign-On via an external identity provider. See [[Authenticator#OAuthAuthenticator_(OIDC_SSO)|OAuthAuthenticator]] and [[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|SAMLAuthenticator]] for details.

Finally, you may implement your own [[authenticator|custom authenticator]] Java class, which you also enter when running the installer.

= Running the Installer =

Now that you've chosen your installation type and performed initial setup of your database and authentication, you can run Obsidian's installer to configure and build a set of artifacts that you can either use to embed Obsidian, or deploy directly.

To run the installer, please follow our detailed [[Installation_Guide|installation guide]].

=== Installer-Created Artifacts ===

Once you've run the installer, your installation directory will look something like the following, depending on which artifacts you chose to generate.

<pre>
├───db_scripts
└───Obsidian-7.0.0
│ com.carfey.yaml.reference
│ obsidian.war
│ obsidian-builtin-job-src.jar
│ obsidianForkedJob.bat
│ obsidianForkedJob.sh
│ obsidian-javadoc.zip
│ standaloneObsidian.bat
│ standaloneObsidian.sh
│ standaloneObsidianAdmin.war
│ webObsidian.bat
│ webObsidian.sh
│
├───embed-tomcat-lib (present when an Embedded Tomcat pack is selected)
├───license
├───linux (present on Unix when an Embedded Tomcat pack is selected)
├───logs
└───standalone
(various JAR files...)
obsidian-yaml-configuration.jar
obsidian.jar
</pre>

The installer creates a top-level directory named '''Obsidian-n.n.n''' containing generated artifacts. The key files and directories are:

; com.carfey.yaml.reference or com.carfey.properties.reference
: Copy of the configuration file generated by the installer.
; obsidian.war
: Combined scheduler and admin web application WAR. Deploy directly to a servlet container, or run locally using the Embedded Tomcat pack (see below). Customise by adding your job code and dependencies as JARs to '''/WEB-INF/lib''' within the archive.
; standaloneObsidian.bat and standaloneObsidian.sh
: Windows and Linux scripts to start the standalone scheduler process with no web application. Customise by adding your job code and dependencies as JARs to the '''standalone''' directory.
; webObsidian.bat and webObsidian.sh
: Windows and Linux scripts to start Obsidian using the embedded Tomcat runtime (requires the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack). Use '''start scheduler''' to run the combined scheduler+admin WAR, or '''start adminOnly''' to run the standalone admin WAR. Stop with '''stop'''.
; standaloneObsidianAdmin.war
: Standalone admin web application WAR (no scheduler). Deploy directly to a servlet container or run via the embedded Tomcat pack.
; embed-tomcat-lib
: Present when an Embedded Tomcat pack is selected. Contains the embedded Tomcat runtime JARs used by the '''webObsidian''' scripts.
; linux
: Present on Unix when an Embedded Tomcat pack is selected. Optional user-level systemd unit and desktop-entry templates, plus '''install-embedded-linux-integration.sh''' and '''README-linux-integration.md'''. See [[#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].
; standalone
: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.

= Starting Obsidian with embedded Tomcat =

If you selected the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack during installation, use the '''webObsidian''' scripts to start and stop Obsidian.

From the Obsidian install directory:

webObsidian.bat start scheduler
(Unix: ./webObsidian.sh start scheduler)

For standalone admin only:

webObsidian.bat start adminOnly

Stop:

webObsidian.bat stop
(Unix: ./webObsidian.sh stop)

Default HTTP port is '''8080'''. To change ports, pass '''-Dembedded.tomcat.http.port''', '''-Dembedded.tomcat.stop.port''', and '''-Dembedded.tomcat.stop.key''' as JVM arguments before starting.

On Linux you can also run Obsidian as a user-level systemd service, or launch it from a desktop entry, instead of calling the script by hand — see [[#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]] below.

If you are deploying '''obsidian.war''' to your own external servlet container instead, refer to your container's deployment documentation.

= Running Obsidian as a Linux user service =

On Linux, an embedded Tomcat pack can install a user-level systemd unit and a desktop entry — see [[Installation_Guide#Linux_desktop_and_systemd_integration|Linux desktop and systemd integration]] for the installer option and the manual '''linux/install-embedded-linux-integration.sh''' script. Installing those files does not enable or start anything, so enable the service yourself:

systemctl --user enable --now obsidian-embedded@scheduler.service

Check and stop it with:

systemctl --user status obsidian-embedded@scheduler.service
systemctl --user stop obsidian-embedded@scheduler.service

''./webObsidian.sh stop'' also stops a service-started instance. Do '''not''' run ''./webObsidian.sh start scheduler'' by hand while the service is running — both bind the same HTTP and stop ports.

== Ports ==

The unit and the desktop entry both invoke '''webObsidian.sh''', so they use the script's ports: HTTP '''8080''' and stop port '''9597'''. Passing ''-Dembedded.tomcat.*'' on a ''java'' command line has no effect on the service — edit the values in '''webObsidian.sh''' before enabling it.

== Running without an active login session ==

This is a '''user''' service, so by default it runs only while that user has a login session and stops at logout. To keep Obsidian running after logout and start it at boot, enable lingering for the account:

loginctl enable-linger <nowiki><username></nowiki>

If you want Obsidian to run as a system service independent of any user account, write your own unit under ''/etc/systemd/system/'' using '''linux/obsidian-embedded@.service.in''' as a starting point.

== Standalone admin installs ==

The generated unit runs '''webObsidian.sh start scheduler'''. If you installed only the '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack, change ''ExecStart'' in ''~/.config/systemd/user/obsidian-embedded@scheduler.service'' to use '''start adminOnly''' before enabling the service.

== Removing the integration ==

systemctl --user disable --now obsidian-embedded@scheduler.service
rm ~/.config/systemd/user/obsidian-embedded@scheduler.service
rm ~/.local/share/applications/obsidian-embedded.desktop
systemctl --user daemon-reload

The same details ship as '''linux/README-linux-integration.md''' in your install directory.

= Embedding Obsidian & Customizing Artifacts =

The Obsidian scheduler process needs Java classpath access to your jobs so it can detect valid jobs and execute them. This requires a bit of customization before you are ready to run custom Java jobs. If you still haven't created your custom jobs, consult [[Implementing Jobs]] before proceeding. If you only intend to use [[Scripting Jobs]], customization will not be required and you can skip to [[#Deployment|Deployment]].

If you want to embed Obsidian into your application or need to deploy jobs and their dependent libraries to the generated Obsidian artifacts, follow the steps in the appropriate sections below.

Note that only Obsidian scheduler processes need to be customized to include your job code. The admin web application itself does not require classpath access to your jobs.

== Embedding Obsidian - Importing Libraries and Properties File ==

To embed Obsidian, you will need to update your application build to bring in the JAR files it requires, along with the Obsidian properties file. Simply follow these steps:

# Import all required [[Advanced_Configuration#Dependent_Libraries|Obsidian JAR files]] into your project and reference them in your build files.
#* These can be obtained from the <code>standalone</code> directory of your installation. Make sure you '''exclude''' <code>obsidian-(yaml/properties)-configuration.jar</code>
#* Ensure your Maven, Gradle or Ant files are updated to include all required libraries in your build, along with your IDE.
# Make a copy of <code>com.carfey.yaml.reference</code> or <code>com.carfey.properties.reference</code> from your installation with the <code>.reference</code> suffix removed, and add it to your project's classpath.
#* This is typically just a matter of adding it to your project's resources directory.
#* From now on, you can update this file to change the various configuration options such as database connection details.
#* You may wish to leave this file out of source control and let developers configure their own installations. However, any running Obsidian instance will need access to a valid [[Advanced_Configuration#Properties.2FYaml_File|properties file]].

'''Maven users:''' Note that we do not publish Maven artifacts for Obsidian, so you will not be able to include them by referencing a public repository.

== Adding Custom Jobs to Standalone Scheduler ==

In order for the standalone scheduler to detect and execute custom jobs written in Java, you will need to ensure Obsidian's classpath contains the compiled job code, along with its dependencies.

To do so, you need to perform just one step before starting the standalone scheduler:

# Copy JAR files containing custom Obsidian jobs and all runtime dependencies to the <code>standalone</code> directory in your installation.
#* These JARs should be alongside <code>obsidian.jar</code>.
#* All JAR files in this directory will be automatically added to the classpath when run via the <code>standaloneObsidian.sh</code> or <code>standaloneObsidian.bat</code> scripts.

== Adding Custom Jobs to Combined Scheduler and Admin Web Application ==

In order for the combined scheduler and admin web application to detect and execute custom jobs written in Java, you will need to ensure Obsidian's classpath contains the compiled job code, along with its dependencies.

To do so, you need to perform just one step before deploying the Obsidian WAR file:

# Copy JAR files containing custom Obsidian jobs and all runtime dependencies to the <code>WEB-INF/lib</code> directory within the WAR archive.
#* These JARs should be alongside <code>obsidian.jar</code>.
#* WAR files use the ZIP format and can be extracted and recompressed with normal ZIP tools or the JDK <code>jar</code> utility.

== Updating the Properties File in Admin Web Applications ==

''Note that updating the WAR artifact is not necessary to perform properties file changes when using an external properties file as described [[Advanced_Configuration#Properties_File|here]].''

If you need to change [[Advanced_Configuration#Properties_File|configuration properties]] for a standalone admin web application or combined scheduler and admin web application, follow these steps:

# Obtain the WAR artifact from your installation that requires changes. This is either <code>obsidian.war</code> or <code>standaloneObsidianAdmin.war</code>.
# Extract the WAR file to a clean directory.
# Edit the <code>com.carfey.(yaml/properties)</code> file within the subdirectory <code>WEB-INF/classes</code> and save your changes.
# Rebundled the WAR artifact using a zip utility or the JDK <code>jar</code> utility.
#* Some zip utilities such as 7Zip will allow you to edit files within an archive directly without the previous steps. It is generally safe to do so.

= Deployment =

You are now ready to deploy your scheduler and/or admin web application.

== Embedded Scheduler ==

When Obsidian is embedded, there is no separate deployment process. However, you will need to start and stop Obsidian with your application. If you are using Spring, we recommend you use our [[Spring Integration]] instead, which will automatically start and stop the scheduler for you.

During your application startup, once it is fully initialized (or as close as possible), start Obsidian, and save a reference to the returned result so you can shut it down later:
<pre>
// This will start the scheduler on the first call to get().

com.carfey.ops.job.SchedulerStarter starter = com.carfey.ops.job.SchedulerStarter.get(com.carfey.ops.job.SchedulerStarter.SchedulerMode.EMBEDDED);

// ...

// Later, we need to gracefully shut down the scheduler
starter.shutDown();

</pre>

This will run Obsidian's scheduler process, but will not include any of the web application or the REST API. This functionality is provided by the admin web application.

== Standalone Admin Web Application ==

To deploy the standalone admin web application, simply deploy the <code>standaloneObsidianAdmin.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war" or "obsidian.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.

'''Note:''' If you selected the '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack, you can use the '''webObsidian''' scripts included in your installation instead of deploying the WAR. This will make the application accessible at http://localhost:8080.

* To start
** Linux: <code>./webObsidian.sh start adminOnly</code>
** Windows: <code>webObsidian.bat start adminOnly</code>
* To stop
** Linux: <code>./webObsidian.sh stop</code>
** Windows: <code>webObsidian.bat stop</code>

'''Security Note:''' By default, the admin web application allows non-secure connections. If you wish to force secure connections through HTTPS, you can edit the web.xml in your war and uncomment the <security-constraint> element in the file. This will force all requests to redirect to an encrypted connection. For details on setting up SSL on your servlet container, refer to its documentation.

== Standalone Scheduler ==

To deploy and run the standalone scheduler, you may use the provided scripts in your installation directory:
* Linux: <code>./standaloneObsidian.sh start</code>
* Windows: <code>standaloneObsidian.bat start</code>

You should always stop Obsidian gracefully when possible by using:
* Linux: <code>./standaloneObsidian.sh stop</code>
* Windows: <code>standaloneObsidian.bat stop</code>

Both the start and stop commands may be supplied an additional argument to override the <code>listenerPort</code> which defaults to 10451.

Rather than use one of the provided scripts, you can invoke the equivalent Java command:

<pre>
java com.carfey.ops.job.SchedulerStarter start <listenerPort>
java com.carfey.ops.job.SchedulerStarter stop <listenerPort>
</pre>

== Combined Scheduler and Admin Web Application ==

To deploy the combined scheduler and admin web application, simply deploy the <code>obsidian.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.

'''Note:''' If you selected the '''Obsidian Embedded Tomcat JAR''' pack, you can use the '''webObsidian''' scripts included in your installation instead of deploying the WAR. This will make the web application accessible at the URL http://localhost:8080.

* To start
** Linux: <code>./webObsidian.sh start scheduler</code>
** Windows: <code>webObsidian.bat start scheduler</code>
* To stop
** Linux: <code>./webObsidian.sh stop</code>
** Windows: <code>webObsidian.bat stop</code>

'''Security Note:''' By default, the admin web application allows non-secure connections. If you wish to force secure connections through HTTPS, you can edit the web.xml in your war and uncomment the <security-constraint> element in the file. This will force all requests to redirect to an encrypted connection. For details on setting up SSL on your servlet container, refer to its documentation.

== Embedding the Obsidian Web Application in Another Web Application ==

We do not generally recommend attempting to merge the Obsidian admin web application with another servlet web application, but it can be done by following these steps:

To embed the full Obsidian web application in an existing web application, you will need to extract the necessary sections from the <code>WEB-INF/web.xml</code> file in the <code>obsidian.war</code> file and merge them into your application's <code>web.xml</code> file. This includes all "listener", "servlet", "servlet-mapping", "jsp-config", "filter", "filter-mapping" elements, and optionally "welcome-file-list" and "error-page" elements. Ensure that all servlet paths are maintained. If you are using a different servlet specification version, you may need to update the mappings to the appropriate format.

Note the use of our <code>com.carfey.ops.servlet.StartupShutdownListener</code> which takes care of starting up the scheduler instance and using the web container's default shutdown mechanism to ensure graceful shutdown. This listener will start Obsidian's scheduler process and initialize the Obsidian web application.

If you wish to embed Obsidian's web application without the scheduler running, include the following parameter element in your <code>web.xml</code>:

<pre>
<context-param>
<param-name>schedulerEnabled</param-name>
<param-value>false</param-value>
</context-param>
</pre>

== Additional Deployment Details ==

=== Classpath Notes ===

To run a scheduler with your custom code and jobs, you need to ensure the scheduler process classpath includes your code packaged into JAR files, as described [[#Embedding_Obsidian_.26_Customizing_Artifacts|above]].

If a compiled job is updated, you will have to restart your application or the servlet container after deploying updated jars, unless you are using [[Job Forking]].

=== Setting Host Names ===
Obsidian instances will automatically assign themselves host names if no host name is explicitly set, but you may wish to give them explicit names to make scheduling and monitoring simpler.

If you wish to assign explicit names, simply set the Java system property <code>schedulerDesignation</code> to the host name of your choice. For example, if starting an instance using the standalone scheduler using <code>java</code> directly, simply add the value <code>-DschedulerDesignation=myHostName</code> to the end of the command.

You may also use a properties file setting for the host name as detailed in [[Advanced Configuration]].

=== Disabling Automatic Database Updates ===

Obsidian automatically applies schema updates and data upgrades to its database on startup. In some cases, it may be desirable to disable this once the database has been fully initialized and upgrades to new versions are not going to be deployed. For example, you may wish to run Obsidian with a user who does not have privileges to modify the database schema.

To do so, you can either set a Java system property, or if you are using the admin web application WAR, you can add a setting to your <code>WEB-INF/web.xml</code> within the archive.

As a system property:

<pre>
-DstartupRunnerClass=com.carfey.ops.run.NullRunner
</pre>

In <code>WEB-INF/web.xml</code>, after any <code>listener</code> elements:
<pre>

<context-param>
<param-name>startupRunnerClass</param-name>
<param-value>com.carfey.ops.run.NullRunner</param-value>
</context-param>

</pre>

=== Disabling DDL Updates ===

It may also be helpful to apply schema updates (DDL) outside Obsidian through a privileged account, but allow Obsidian upgrades to make the necessary data initialization/modifications. This can be done using a '''skipDDL''' configuration property documented under [[Advanced_Configuration#Miscellaneous_Properties | Advanced Configuration]].

=== Disabling Job Scheduling in the Web Application ===

If you have combined scheduler and admin web application WAR already built, you can easily tweak it to disable the scheduler process.

Simply add the following to your <code>WEB-INF/web.xml</code> within the WAR archive after any <code>listener</code> elements:

<pre>

<context-param>
<param-name>schedulerEnabled</param-name>
<param-value>false</param-value>
</context-param>

</pre>

= You’re Good to Go! =

You're now ready to log into the web application and start scheduling jobs! The URL you use to access Obsidian will depend on how it's been deployed, but will typically be something like http://localhost/obsidian, or http://localhost/standadminObsidianAdmin.

'''Default User:''' Each Obsidian installation using native authentication starts with a single default user named ''admin'' with password ''changeme''. You should change this after your first log in. See [[Admin_User_Management|User Management]] for how to change a user's password.

At this point we suggest you play around with the admin web application. Many screens offer inline help. Otherwise, you can refer to our [[Admin Web Application Guide]].

To get started writing jobs that you can run in Obsidian, see [[Implementing_Jobs|Implementing Jobs]].

See the '''[[User Guide]]''' if you have questions or wish to explore what Obsidian offers.

Upgrading Obsidian

2026-07-31T15:02:38Z

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

There are a number of options available to you. Select the one that best suits your situation.

Note that you don't necessarily need to go through the installer UI again, although you're free to do so. Since the primary purpose of the installer is to provide fully configured Obsidian artifacts and your environment would already be configured, you really just need the updated artifacts (libraries and WAR files). Even if you want to take advantage of new configuration options, you could use the [[Advanced_Configuration|Configuration Reference]] to make the necessary changes.

=== Upgrading to 7.0.0 ===

==== Remember Me removal ====

The Remember Me feature has been removed. No operator action is required. On first startup after the upgrade, ''Release7Dot0Dot0Upgrader'' runs automatically and drops the ''USER_COOKIE'' table (if it exists) and removes the ''allowRememberMe'' system parameter. Users who had active Remember Me sessions will be prompted to log in on their next visit.

==== OAuth / OIDC authentication (optional) ====

Obsidian 7.0.0 adds an optional OAuth / OIDC authenticator. Existing installations continue to use their current authenticator (DB or LDAP) with no changes required. To switch to OAuth / OIDC: configure ''OAuthAuthenticator'' properties in the Obsidian configuration file (''com.carfey.properties'' or YAML equivalent) — see [[Authenticator#OAuthAuthenticator_(OIDC_SSO)]] and [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] — then restart Obsidian.

==== Migrating saved automated install XML (Obsidian 6 → 7) ====

If you use headless / automated install with an XML file saved from Obsidian 6 (IzPack 4.3.5), you must migrate that file before installing with Obsidian 7. Unzip the Obsidian 7.0.0 download and run the migrate helper (Windows: '''migrate-headless.bat --in my-old-config.xml --out my-config-izpack5.xml''', Unix: '''migrate-headless.sh''' with the same arguments, or '''java -jar Obsidian-Install-Migrate.jar --in my-old-config.xml --out my-config-izpack5.xml'''). Review '''my-config-izpack5.xml.migration-report.txt''' only if the tool creates one — if it lists unknown panels or keys, contact [[Contact_the_Obsidian_Scheduler_Team|Carfey support]]. Then install with the migrated file: '''java -jar Obsidian-Install-7.0.0.jar my-config-izpack5.xml'''. The migrate helper covers Obsidian's standard installer panels only and does not modify product installer descriptors or custom installers.

==== Upgrading evaluation installs (Jetty quick start → embedded Tomcat) ====

Obsidian 7.0.0 removes the Jetty quick-start pack and '''jetty-home''' distribution. If you previously installed with a Jetty-based quick start or embedded Jetty pack:

# Re-run the installer or edit your automated install XML to select '''Obsidian Embedded Tomcat JAR''' (scheduler) or '''Obsidian Standalone Admin Embedded Tomcat JAR''' (admin), '''and''' the matching WAR pack.
# Remove references to legacy Jetty pack names in any saved automated install XML. If the file is still IzPack 4 format, run the migrate helper first (see [[Upgrading_Obsidian#Migrating_saved_automated_install_XML_.28Obsidian_6_.E2.86.92_7.29|Migrating saved automated install XML]]).
# After install, use '''webObsidian start scheduler''' (or '''start adminOnly''') instead of the Jetty '''start.jar'''.

If the migrate helper produces a '''.migration-report.txt''' file, review it before running the install — it will flag any pack renames that need attention.

==== Installer breaking changes (Obsidian 6 → 7) ====

* Headless automated install XML must use IzPack 5 panel class names and ''id'' attributes — migrate saved Obsidian 6 files with the tooling above.
* GUI installer — same configuration panels and outcomes; underlying engine is IzPack 5.
* Release zip — adds migrate JAR/scripts.
* Groovy and Flexmark libraries are now modular — see [[Advanced_Configuration#Dependent_Libraries]].

== Automated Installer File ==
This section applies if you have saved an automated installer XML file from a previous version of Obsidian.

If the release notes do not document any installer incompatibility between source and target releases, this means there are no new configuration options available and you can use your automated installer file without modification.

You can see [[Installation_Guide#Completing_the_Installation|installation configuration]] for more information, but essentially all you need to do is run <code>java -jar Obsidian-Install-n-n-n.jar my-obsidian-install-config.xml</code>. You may wish to change the target installation path before proceeding.

If the release notes do document installer incompatibility between releases, follow the relevant instructions to update your installer configuration file and then follow the same procedure.

== Existing Configuration ==

You have a choice when it comes to upgrading an Obsidian environment that is already configured.

# You can rerun the installer UI to get the configured artifacts.
# Use the [[Installation_Guide#Running_the_Obsidian_Installer|quickstart]] installation mode to get the updated artifacts with the quickstart configuration.

==== Existing Configuration with QuickStart ====
If you are using [[Advanced_Configuration#Properties.2FYaml_File|overrides]] support to specify '''ALL''' your configuration items, you likely are ready to go as the default configuration items are being overridden.

Otherwise, you are relying at least partially on embedded configuration items. You will need to replace the quickstart configuration values with your existing configuration values. The Obsidian WAR files have the <code>com.carfey.(properties/yaml)</code> file inside at <code>WEB-INF/classes/com.carfey.(properties/yaml)</code> and the standalone installation has it at the root of ''obsidian-properties-configuration.jar'' or ''obsidian-yaml-configuration.jar''.

== Performing the Upgrade ==
We highly recommend performing a database backup and an installation backup (filesystem backup) prior to performing the upgrade with rollback strategies in place to restore the previous installation with its data.

Obsidian automatically applies any database modifications during the first deployment of the new version.

The simplest mechanism is to bring down all your Obsidian Scheduler nodes during a quiet scheduling period. Deploy the new artifacts and start the each node individually verifying its startup before proceeding to the next node.

== Database Upgrade Scripts ==

When you start Obsidian, it will automatically upgrade the schema in your target database. However, if you wish to run Obsidian with a database user without create and drop privileges, or simply wish to prepare your database structure ahead of time, you can use the database upgrade scripts provided with your download zip file under the "db_scripts" directory.

First locate all files named "*upgrade.sql" under the directory for the database you are using under the "db_scripts" directory. Statements within these files contain the token "$px$" to enable table prefixes. Before you run the SQL files, replace all instances of the token "$px$" (without quotes) with a table prefix 6 characters or shorter (letters and underscores supported), or with blank.

Then, in your SQL client of choice, execute the scripts in order of their version numbers. This will upgrade your schema to your target version.

You'll need to allow the data portion of the migrations to execute while preventing the DDL scripts to run. To do this, you need to [[Getting_Started#Disabling_DDL_Updates|disable DDL Updates]].

== Performing an Always On Cluster Upgrade ==

If you absolutely must maintain at least one node running, Obsidian should be able to continue scheduling and executing on a single node while the other(s) is/are upgraded although we make no assurances and recommend that you '''test out your specific upgrade scenario''' first. Depending on the content between source and target releases, we also recommend that you don't attempt to perform other changes such as job configuration changes, failure resubmissions, etc. during this time. Feel free to [[Contact_the_Obsidian_Scheduler_Team|contact us]] with questions about your specific upgrade scenario.

===== Always On Cluster Upgrade Steps =====
# Bring down all but one Obsidian Scheduler node.
# Target a downed node for upgrade.
# Deploy the upgraded artifacts to the targeted downed node.
# Startup the upgraded node.
# Verify successful startup.
# Bring down the still-running older Obsidian Scheduler node.
# Repeat steps 3-5 for each remaining downed node in the cluster.

Troubleshooting

2026-07-31T15:02:30Z

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

__FORCETOC__
The following are steps to troubleshooting common problems users have had in Obsidian. If you don't see your problem listed, [[Contact_Carfey_Software|contact us]] or use our Free Live Chat Support link on the left.

= My job isn't running when expected. Why not? =
This may be a case where your schedule isn't correct for the execution times you want, or the job may be failing.

# First, you should confirm that your job isn't actually running. You can check for the [[Admin_Job_Activity|Job Activity]] screen to see if there are any scheduled or completed jobs. You may see that a job failed; to see details on it, simply expand the row to see an exception stack trace and the option to resubmit the job. If your job is failing, you may wish to set up [[Admin_Notifications|notifications]] so that you know of future problems quickly.
# If you don't see any jobs listed there, you can confirm what execution times your schedule will result in. To see what times your job will execute, check the [[Admin_Job_Run_Time_Preview|Run Time Preview]] screen.
# Next, you can check for any general server health issues. To do so, first you can search the [[Admin_Logs|Logs]] screen for any errors or warnings that may indicate a server issue.
# Finally, check your application logs (e.g. Tomcat stdout logs, etc.). If there are database issues, these logs may be the only place where server issues are logged.
# If all else fails, [[Contact_Carfey_Software|contact us]] or use our Free Live Chat Support link on the left.

= When I try to enter my job's class name in the UI, I get the message "Could not locate the class [MyJob]". What's the problem? =

This problem is generally caused by one of these issues:

# If you are running a combined scheduler and web application, the JAR file containing the job is not on the classpath of the servlet container (Tomcat/Jetty/etc). JARs are placed under <code>WEB-INF/lib</code> in the web application.
# If you are running a standalone web application with no scheduler running, your other Obsidian instance which includes the scheduler has not had its [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] configuration set, or has not been started with the appropriate classpath required for it to save the job metadata the web application uses to validate jobs. See [[Implementing_Jobs#Classpath_for_Building|Classpath for Building]].
# Obsidian has not been restarted after updating the classpath with a new JAR.
# Job does not implement <code>com.carfey.ops.job.SchedulableJob</code>.
# Job dependencies (i.e. other JARs or classes) are not available on the classpath. These must be deployed with the job.
# User has entered the job class with leading or trailing whitespace, or the job class has been misspelled.
# User did not enter the fully qualified class name (e.g. MyJob instead of com.company.MyJob).

Just a note, you can use the [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] feature to automatically find your jobs so you won't need to type them in as they'll be added to the list of available jobs.

= Why isn't my job showing up? =

Out of the box, Obsidian will display any previously scheduled jobs and Obsidian's bundled jobs. You can type in your class name as described in [[Admin_Jobs#Nickname.2C_Class_and_Folder|Admin Jobs]].

If you are using Obsidian's [[Implementing_Jobs#Classpath_Scanning|classpath scanning]] and don't see your job pre-populated, make sure you set appropriate the "packageScannerPrefix" value in the [[Admin Scheduler Settings|scheduler settings]] screen, and ensure the user account running Obsidian has read privileges to the <code>WEB-INF</code> directory of Obsidian's deployment directory.

In addition, some users have had issues with classpath scanning not locating jobs in JARs created by tools which don't include directory entries, such as Eclipse. Scanning relies on these directory entries, so please ensure they are included. For example, in Eclipse, if you choose to export a JAR, make sure the ''Add Directory Entries'' option is selected.

= I'm trying to start Obsidian using the Quick Start method, but I'm seeing "java.net.BindException". =

<pre>
java.net.BindException: Permission denied
at java.net.PlainSocketImpl.socketBind(Native Method)
at java.net.PlainSocketImpl.bind(PlainSocketImpl.java:383)
at java.net.ServerSocket.bind(ServerSocket.java:328)
at java.net.ServerSocket.<init>(ServerSocket.java:194)
</pre>

This is a common error on *nix platforms, including OS X. On these platforms, ports 0-1023 are privileged. By default, only the root user will be able to bind to them. Obsidian's quick start uses port 8080 by default; the error also occurs if that port is already in use.

Changing the port as described below will fix the issue.

To resolve this, you have two options:
# Use the "sudo" command to elevate your privileges to bind on a privileged port.
# Change the port you use.

To change the port, edit the <code>-Dembedded.tomcat.http.port</code> value in <code>webObsidian.sh</code> or <code>webObsidian.bat</code>, or pass it as a JVM argument when starting Obsidian. The companion <code>-Dembedded.tomcat.stop.port</code> (default 9597) must also be free. If you run the Linux user systemd service, edit the script rather than the unit — the unit invokes the script. See [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

On Obsidian 5.x and 6.x, which bundled Jetty for the quick start instead of embedded Tomcat, change the port in the Jetty configuration or in the same <code>webObsidian</code> scripts.

= I'm trying to start Obsidian on Windows using the Quick Start method, but a window appears and then disappears quickly. What's going on? =

The quick start method runs Obsidian in a separate process to ensure you can gracefully stop it. Unfortunately, the separate process is failing before you can see what the problem is. To temporarily see the error and have it try to run in the same process, open the script in a text editor and find the line that launches Java: in <code>webObsidian.bat</code> it begins with <code>start "Obsidian" java</code>, and in <code>standaloneObsidian.bat</code> it begins with <code>start java</code>. Remove the <code>start</code> command and its window title if present (so the line begins with <code>java</code>), save the file and try again. You should get an informative message. Correct the underlying cause, restore the original line and run it again.

= My Obsidian systemd service stops when I log out of Linux =

The unit installed by <code>linux/install-embedded-linux-integration.sh</code> is a '''user''' service, so systemd stops it when the user's last session ends and does not start it at boot. Enable lingering for the account:

loginctl enable-linger <nowiki><username></nowiki>

Then confirm the service is enabled:

systemctl --user is-enabled obsidian-embedded@scheduler.service

If the service must run independently of any user account, create your own unit under <code>/etc/systemd/system/</code> based on <code>linux/obsidian-embedded@.service.in</code> in your install directory. See [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

= I tried running Obsidian in Jetty, but encountered the error "There is an error in invoking javac. A full JDK (not just JRE) is required" =

This applies to Obsidian 4.x through 6.x deployed to your own Jetty installation. It is caused by Jetty wanting a JDK for JSP compilation when it isn't configured.

The simplest way to resolve this is to uncomment the following line from <code>start.ini</code> in your Jetty installation by removing the hash sign:

<pre>
# -Dorg.apache.jasper.compiler.disablejsr199=true
</pre>

Obsidian 7.0.0 is tested on Tomcat 10.x and its WARs contain no JSPs, so no JSP compilation — and therefore no JDK — is required.

= My jobs aren't running and I'm seeing this error: "Licence was refused: Licence is valid but no keys are available for lease. Are you running too many nodes?" =

This can be caused by a few issues, but if you are unsure, [[Contact_the_Obsidian_Scheduler_Team|contact us]]:
<ol>
<li> You are running more Obsidian instances that you have available nodes on your license key. If you are running two nodes using the year-long free clustering node, your year may have run out.</li>
<li> Obsidian is unable to refresh your license lease properly, resulting in a new lease being acquired each time it contacts our license servers. This means to our servers it looks like multiple instances are trying to run concurrently. Ensure that Obsidian has access to read and write the Java temp directory (<code>java.io.tmpdir</code>), since it requires this to track the license it has leased. Below is a sample of granting access to the temp directory on WebSphere Application Server 8.5:
<pre>
// Update policy file at: C:/WebSphere/AppServer/profiles/AppSrv01/properties/server.policy

grant codeBase "file:${user.install.root}/installedApps/Cell01/obsidian_war.ear/-" {

permission java.io.FilePermission "${java.io.tmpdir}${/}-", "read,write";

};
</pre></li>
<li> Obsidian was not shut down properly, and was started in another location before the old license lease expired. Obsidian works by leasing a license for a specified amount of time, and refreshing it before it expires. When shut down gracefully, Obsidian will release this lease and make it available to any other node using the same key. If it is shut down non-gracefully, the lease will stay active, and only the same server will be able to refresh that same license before it expires. By default, a lease lasts an hour or two to gracefully handle sporadic connectivity.</li>
<li> You are using the wrong license key. Check the license key set in the [[Admin Scheduler Settings|scheduler settings]] screen of the web application. This is the value Obsidian is using to verify its licensing status. Note that the value in your properties file is only used to initialize the Obsidian database, so once it is set, you must update the value in the [[Admin Scheduler Settings|scheduler settings]] screen.</li>
<li> You may have runaway background Obsidian processes which are using a license that you are unaware of.</li>
</ol>

= I'm getting a "Lock wait timeout exception". What's going on? =

<pre>
java.sql.SQLException: Lock wait timeout exceeded; try restarting transaction
at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:1055)
at com.mysql.jdbc.SQLError.createSQLException(SQLError.java:956)
at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:3491)
at com.mysql.jdbc.MysqlIO.checkErrorPacket(MysqlIO.java:3423)
at com.mysql.jdbc.MysqlIO.sendCommand(MysqlIO.java:1936)
</pre>

If you encounter an error like the one above and are using MySQL (particularly version 5.0), there is a chance you are hitting a [https://bugs.mysql.com/bug.php?id=20932 MySQL bug]. This problem seems to occur mainly on new Obsidian instances, so once corrected, there is a good chance you will never see the issue again.

Two approaches have been used with success:
# In MySQL's my.cnf file, temporarily change (or add) the following line, and then restart mysqld: <pre>innodb_lock_wait_timeout = 600</pre><br />This appears to only be an issue when Obsidian first gets running, and it can typically be reverted after a while.<br /><br />
# At a MySQL prompt, run the following command: <pre>optimize table semaphore;</pre><br /> If this resolves your issue, we suggest optimizing all your tables using [https://dev.mysql.com/doc/refman/8.0/en/mysqlcheck.html mysqlcheck].

= I am running Obsidian on Oracle but I'm seeing the error "ORA-00942: table or view does not exist" =

This is usually caused by not setting the proper schema value for the Obsidian database user.

This is easily resolved by setting the property <code>com.carfey.obsidian.db.schema</code> to the name of your user (or other target schema). See [[Advanced Configuration]] for more details on this property.

Example: <code>com.carfey.obsidian.db.schema=obsidian</code>

= I'm seeing an error in the logs like "Maximum X connections already created for pool". What's going on? =

Obsidian uses an internal database connection pool to avoid opening connections more than necessary, which is an expensive operation. The default maximum size for this pool is 40, which is more than sufficient for almost all installations.

If you have set a smaller value (e.g. 10), and have a very large amount of API or job activity, you can try increasing this value.

Most frequently though, this issue arises because Obsidian is configured to use a JNDI data source with its own connection pool, and there are incompatibilities between the pools' settings. As a rule, your JNDI database pool maximum size must be equal to or greater than the the maximum size of the Obsidian pool via property <code>com.carfey.obsidian.db.maxConnections</code> as outlined in [[Advanced_Configuration#Database_Properties|Advanced Configuration]]. In addition, if there is an eviction process for idle connections, ensure than the value for the maximum idle age is 65 seconds or above to avoid warnings about unreleased connections. Alternatively, you can disable the Obsidian connection pool entirely by specifying <code>com.carfey.obsidian.db.disablePooling=true</code> in your <code>com.carfey.properties</code> file. This will cause Obsidian to never cache an opened idle connection.

Here is a good base JNDI pool configuration for Tomcat 7.
<pre>
<Resource name="jdbc/obsidian" auth="Container"
type="javax.sql.DataSource"
driverClassName="oracle.jdbc.OracleDriver"
url="jdbc:oracle:thin:@localhost:1521/OBSIDIAN"
username="OBSIDIAN"
password="<password>"
maxActive="50" maxIdle="10"
maxWait="2000" timeBetweenEvictionRunsMillis="65000"
/>
</pre>

= I'm seeing deadlocks in the logs while running on MS SQL Server =

MS SQL Server has different behaviour with the read committed isolation compared to other database platforms, which can result in periodic deadlocks in some installations.

To change this and eliminate deadlocks, enable the [[Getting_Started#MS_SQL_Server_Snapshot_Isolation|read committed snapshot isolation]] on your database.

= I'm seeing an error in the logs about a time zone conflict. What's going on? =

If you start multiple schedulers with different JVM time zones, Obsidian will abort startup to prevent inconsistent scheduling behaviour. The error will look something like "Cannot start scheduler in timezone [PST] since it conflicts with currently running node in timezone [EST]".

Normally, if a scheduler is shut down, it can be started again with a new time zone setting. However, if a scheduler is not gracefully shut down, the stored time zone may persist. In this case, the following sample SQL can be used while all schedulers are stopped to clear out all time zone state:
<pre>
-- Add table prefix as required.
DELETE FROM OPERATIONS_PARAMETER WHERE NAME LIKE '%time%one%';
</pre>

Spring Integration

2026-07-31T15:02:21Z

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

Though Obsidian works great on its own, Obsidian also supports seamless integration with [http://projects.spring.io/spring-framework/ Spring]. This page outlines how to set up Spring integration and execute jobs which are configured as Spring components. It also documents a simple component which lets you easily embed a scheduler process within Spring.

= Dependency Injection via Spring =

Obsidian integrates with your Spring dependency injection container, and supports loading job implementations from the Spring context. Obsidian does not include any Spring libraries and will defer to the version and libraries you include with your application. It supports versions of Spring from 2.5 onward.

Obsidian uses the <code>@Component</code> and any Spring or custom extensions of those annotations (such as <code>@Service</code> and <code>@Repository</code>) as a basis for knowing which job implementations should be retrieved from the Spring context. It is important to note that if a job class does not have one of these annotations, '''Obsidian will not use the container version''', and will instantiate the job directly.

Job classes which can be loaded from Spring can be either <code>SchedulableJob</code> implementations or [[Implementing_Jobs#Annotation-Based_Jobs|annotated]] jobs. Even if you are not using Spring annotations to wire your classes, you will need to add the <code>@Component</code> annotation (or a subtype) to your job classes to serve as a [http://en.wikipedia.org/wiki/Marker_interface_pattern marker] to Obsidian. See [[Implementing_Jobs|Implementing Jobs]] for details on how to write and configure executable jobs.

Regardless of the method you use to configure your Spring components, Obsidian will load them directly from the container which means the actual singleton or prototype object obtained from Spring is executed by Obsidian. This makes creating jobs which use configured services very easy and convenient.

Spring will need to be configured and started in all Obsidian scheduler runtimes, but not standalone Admin UI web apps. Each environment will require the job classes to be wired in Spring, scheduler nodes to permit retrieval from the context for execution, admin deployments to allow retrieval from the context for configuration validation.

To allow Obsidian to locate your application's Spring context, you will need to ensure Obsidian's [https://docs.spring.io/spring/docs/3.2.18.RELEASE/api/org/springframework/context/ApplicationContextAware.html ApplicationContextAware] implementation is configured by Spring. If you are using Spring's classpath scanning, you can use the following approach to add an additional package to your configuration:

<context:component-scan base-package="com.my.package.scan.base''', com.carfey.ops.job.di'''"/>

Another option is to extend our <code>com.carfey.ops.job.di.SpringContextAware</code> class with an empty extension class in one of your currently scanned packages. When this object is configured by Spring, it will automatically initialize Obsidian's Spring integration.

If you are not using scanning, simply ensure you wire in our <code>com.carfey.ops.job.di.SpringContextAware</code> class via XML.

If you have multiple instances of a given bean type in your Spring context, please ensure you use the <code>value=""</code> when you annotate your job with <code>@Component</code> or its specializations as this is how Obsidian will uniquely identify the job within the Spring context.

Implementations of <code>SchedulableJob</code> found in your [https://docs.spring.io/spring/docs/3.2.18.RELEASE/api/org/springframework/context/ApplicationContext.html ApplicationContext] will automatically be available in the [[Admin_Jobs#Adding_.26_Editing_Jobs|Job Admin]] screen thus avoiding needing to configure distinct [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]]. If you're using at least Spring 3.0, your [[Implementing_Jobs#Annotation-Based_Jobs|annotated]] jobs will also be found in the Spring <code>ApplicationContext</code>.

== Grails ==

Grails services can be used with the standard Spring Integration as outlined above, but they must have the appropriate <code>@Component</code> annotation, or a subtype of that annotation.

== Spring Boot ==

See the [https://github.com/ajit-kulkarni/obsidian-demo Spring Boot sample project] showing how to start and stop the Obsidian scheduler automatically, courtesy of Ajit Kulkarni.

== Best Practices ==

* Ensure Spring is initialized before Obsidian is started via either <code>com.carfey.ops.job.SchedulerStarter</code> or <code>com.carfey.ops.servlet.StartupShutdownListener</code>. This ensures the Spring context is fully available when Obsidian starts running jobs.
** If using <code>com.carfey.ops.servlet.StartupShutdownListener</code> within a <code>web.xml</code> file, ensure the Spring context loader (e.g. <code>org.springframework.web.context.ContextLoaderListener</code>) is called first.
** If using <code>com.carfey.ops.job.SchedulerStarter</code> called via Spring initialization, ensure it is called at the end of the context initialization (e.g. <code>@PostConstruct</code>, via an <code>InitializingBean</code>, etc).
* If your job has internal state (i.e. members) which is used during job execution, Spring prototypes should be used to avoid concurrency issues.
* In many cases, the majority of job logic can be left in your existing Spring components.
* Use Obsidian to configure parameters and store results, but leave application-level configuration in Spring.
* Make sure every job you want to be loaded from the Spring context has a <code>@Component</code> annotation, or a subtype of that annotation.

== Sample Jobs ==

As a prototype <code>@Component</code>:

<pre>
@Component
@Scope(value=ConfigurableBeanFactory.SCOPE_PROTOTYPE)
@Configuration(knownParameters={
@Parameter(name="incrementCounter", type=Type.BOOLEAN, defaultValue="true", required=true)
})
@Description("This job is a Spring Bean that invokes an Autowired Counter Service.")
public class SpringComponentJob implements SchedulableJob {

@Autowired private CounterService mCounterService;
private MyState mState;

@Override
public void execute(Context context) throws Exception {
...snip...
feel free to call methods that manipulate state since this is a prototype
...snip...
String prefix = SpringComponentJob.class.getName();
if (context.getConfig().getBoolean("incrementCounter")) {
context.saveJobResult(prefix + ".incrementCounter", mCounterService.incrementCounter());
} else {
context.saveJobResult(prefix + ".currentCounter", mCounterService.currentValue());
}
}
}
</pre>

As a singleton <code>@Service</code>:

<pre>
@Service
@Configuration(knownParameters={
@Parameter(name="incrementCounter", type=Type.BOOLEAN, defaultValue="true", required=true)
})
@Description("This job is a Spring Service that makes various service calls.")
public class SpringServiceJob implements SchedulableJob {

@Autowired private PricingService mPricingService;
@Autowired private AuditingService mAuditingService;

@Override
public void execute(Context context) throws Exception {
...snip...
feel free to call other services or local service methods
...snip...
}
}
</pre>

= Wiring an Embedded Obsidian Scheduler =

Obsidian can run scheduler nodes that do not include the full web application deployment. This is often used in conjunction with a separate standalone admin web application.

Obsidian comes bundled with a simple Spring component to automatically start and stop an embedded scheduler. <code>com.carfey.ops.job.di.SpringSchedulerStarter</code> can be wired into your Spring application via XML:

<pre>

<bean id="obsidianStarter" class="com.carfey.ops.job.di.SpringSchedulerStarter" />
</pre>

This wired bean will automatically start and stop the scheduler gracefully when the context initializes and shuts down.

'''Note:''' For safety reasons, this class does not possess a <code>@Component</code> annotation and cannot be auto-wired via Spring classpath scanning.

Scripting Jobs

2026-07-31T15:02:12Z

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

Obsidian provides support for execution of scripted jobs in various languages. None of these require any Java code to be written. The script to execute is set via a ''script'' job parameter. Jobs are executed under the context of the process user running Obsidian.

The following job classes can be configured with executable scripts in their target languages:

* com.carfey.ops.job.script.JavaScriptJob running [https://github.com/mozilla/rhino Rhino] or [https://wiki.openjdk.java.net/display/Nashorn/Main Nashorn] depending on your Java version.
* com.carfey.ops.job.script.PythonJob running [https://www.jython.org/ Jython]
* com.carfey.ops.job.script.GroovyJob [https://groovy-lang.org/ Groovy]
* com.carfey.ops.job.script.BeanShellJob executing a [https://beanshell.github.io/ BeanShell] script.
* com.carfey.ops.job.script.RubyJob executing a [https://www.jruby.org/ JRuby] script. ''Supported as of Obsidian 4.10.0''
* com.carfey.ops.job.script.ReflectiveJob is a convenience GroovyJob that does not require a script, using defined parameters to construct an object and invoke method(s), both supporting argument(s)
* <strike>com.carfey.ops.job.script.[[#SpringBeanJob|SpringBeanJob]]</strike> is a convenience GroovyJob that does not require a script, using defined parameters to obtain the bean and invoke the method(s). Deprecated. Use [[Implementing_Jobs#Dependency_Injection_via_Spring|Dependency Injection]] instead.

= Parameters =
Any parameters configured for the job will be set as global variables within the script. If a single value is configured for a parameter, it will be set as its direct type. If multiple values are set for a parameter, it will be passed into the script as a list of values.

== Loading Scripts from the File System ==

All script file jobs can use a script file path instead of configuring the script directly in Obsidian. When the job runs, Obsidian will load the contents of the file and execute the script in the same way that jobs configured using the <code>script</code> parameter are run.

To use this feature, when configuring the job, omit the <code>script</code> parameter and instead supply a file path under <code>Script File Path</code>. It is recommended that an absolute path is used, and the Obsidian process will need read access to the file for it to run successfully.

= Job Context =
The job context variable is accessed through the global variable named "jobContext". This can be used to save output parameters, etc. See [[Implementing Jobs#Job Results|Job Results]] and [[Implementing Jobs#Parameterization|Parameterization]].

= Sample Jobs =

Groovy:

[[File:GroovyConfig.png]]

Python:

[[File:PythonConfig.png]]

Javascript:

[[File:JavascriptConfig.png]]

= <div id="SpringBeanJob">SpringBeanJob</div> =
'''Deprecated.''' Use [[Implementing_Jobs#Dependency_Injection_via_Spring|Dependency Injection]] instead.
A SpringBeanJob is simply a convenience GroovyJob with a predefined script that uses some specified parameters to find a Spring Bean and invoke specified method(s). Specify any optional class imports (class names only), the single line of code to retrieve the Spring Bean reference and the method name(s) to invoke.

[[File:SpringBeanJobSample.png|300px]]

= Running Ruby from Obsidian =
Obsidian can be configured to run Ruby via JRuby. Jython support and JRuby conflict with each other due to conflicting dependencies. As of Obsidian 4.10.0, Obsidian supports JRuby out of the box, but will only allow you to select one of the two - JRuby or Jython. Prior to Obsidian 4.10.0, if you are willing to drop Jython(Python) support in Obsidian, you may follow these instructions to enable JRuby support.

# Download [http://jruby.org/ JRuby] JAR and replace the Jython JAR (jython-standalone-''n''.''n''.''n''.jar) with the JRuby JAR.
# Add the RubyJob source below. Either incorporate into your existing job building process or compile and statically add to your Obsidian deployment.
# Note the sample configuration below.

<nowiki>
/*
The MIT License (MIT)

Copyright ©2019 Carfey Software Corporation. All rights reserved.

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.

*/
package com.carfey.ops.job.script;

import com.carfey.ops.job.param.Description;

/**
* <p>
* <b>Usage: </b>
* See {@link ScriptEngineJob}.
* This is a script job using the ruby engine,
* which by default is the <a href="http://jruby.org/">JRuby</a> implementation.
*
*
* @see <a href="https://wiki.obsidianscheduler.com/docs/File:Obsidian.3.6.0.RubySampleJob.PNG">Sample Configuration</a>
*/
@Description("This job will execute the supplied Ruby script, with custom parameters inserted into the script variable context. " +
"Either an inline script or the full script path may be supplied.")
public class RubyJob extends ScriptEngineJob {

@Override
protected String getEngineName() {
return "jruby";
}

}
</nowiki>

[[File:RubyConfig.png]]

Release Notes - Older Releases

2026-07-31T14:49:59Z

Craig: De-link the deleted Legacy API page

<div class="toclimit-2">__TOC__</div>

== Obsidian 4.10.6 ==
Released April 2021.

=== Bug Fixes ===
* Correct issue where PostgreSQL database connection validation exceptions are masked.
* Fix UI styling issues in Firefox browser.

== Obsidian 4.10.5 ==
Released October 2020.

=== Features / Enhancements ===
* New ''LW'' instruction for day-of-month field in [[Cron#Special_Character_Usage|Cron]] to indicate last weekday of month.

=== Bug Fixes ===
* Fix for ''W'' day-of-month field in [[Cron#Special_Character_Usage|Cron]] skipping months where ordinal is last ordinal of the month and falls on the last Sunday of the month.

== Obsidian 4.10.4 ==
Released July 2020.

=== Bug Fixes ===
* Fix UTF-8 handling in [[REST_API|REST API]] calls.

== Obsidian 4.10.3 ==
Released March 2020.

=== Features / Enhancements ===
* Introduce better handling for edge case where a long running job that loses connectivity to the Obsidian database gets marked as Died while it is still running and then eventually reconnects to the database and its heartbeat updates resume. Heartbeat updates will now be prevented and new special events are triggered when this case is detected and when the job finally terminates.

=== Bug Fixes ===
* Fix JobIds parameter in [[Embedded_API#List_Job_Dashboard_.28Latest_Scheduled_Runtime_by_Job.29|Embedded]] API for Job Dashboard (Last Occurrence of Jobs)

== Obsidian 4.10.2 ==
Released October 2019.

=== Features / Enhancements ===
* [[REST_Endpoints#GET_a_list_of_the_latest_scheduled_runtime_by_job_.28supports_multiple_jobs.29|REST]] and [[Embedded_API#List_Job_Dashboard_.28Latest_Scheduled_Runtime_by_Job.29|Embedded]] API for Job Dashboard (Last Occurrence of Jobs)
* Timezone now included when dates are in event messages.

== Obsidian 4.10.1 ==
Released June 2019.

==== Bug Fixes ====
* [[Recovery_%26_Failover#Startup_.2F_Shutdown_Mode|Startup/Shutdown]] configuration of jobs not being applied in UI.
* [[Admin_Scheduler_Settings|Scheduler setting]] jobShutdownWaitTimeSeconds in Job category could not be set to -1 in the UI.

== Obsidian 4.10.0 ==
Released April 2019.

=== Features / Enhancements ===
* Support for automated [[Recovery_%26_Failover#Startup_.2F_Shutdown_Mode|Startup/Shutdown]] invocation of jobs.
* [[Implementing_Jobs#Parameterization|Parameters]] now have optional support for validation of list values to be unique.
* Formalized support for [[Scripting_Jobs|Ruby Script jobs]] via JRuby.
* Enhanced [[Installation_Guide#Selecting_Script_Libraries|installer]] to allow selectivity of desired script libraries/jobs. '''Breaking change to automated installer files.''' <ref>

If you are using automated installer files from previous releases, you will need to add a new section of xml as of Obsidian 4.10.0 to handle a new UserInputPanel. Immediately after the UserInputPanel.15 closing brace, add the following:<pre>
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.16">
<userInput>
<entry key="script.beanshell" value="true"/>
<entry key="script.jruby" value="false"/>
<entry key="script.groovy" value="true"/>
<entry key="script.jython" value="true"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>
</pre>
You can change the parameter values as desired. The above reflects the options for all versions prior to Obsidian 4.10.0.
</ref>
* Formalized support for [[Getting_Started#Supported_Platforms|MS SQL 2016 & 2017]]

== Obsidian 4.9.1 ==
Released March 2019.

==== Bug Fixes ====
* ClasspathJobScanner fails on job classes with no [[Implementing_Jobs#SchedulableJob_Interface|@Description]] annotation
* In some cases, [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup Job]] was not deleting certain history and related records.

== Obsidian 4.9.0 ==
Released February 2019.

=== Features / Enhancements ===
* [[Implementing_Jobs#SchedulableJob_Interface|Description]]/[[Implementing_Jobs#Parameterization|Parameter]] annotation support optional URLs arrays
* New built-in maintenance job [[Built-in_Jobs#Notification_Cleanup_Job|Delete Notifications Job]]
* New subscribable event for first occurrence of a host not running a job due to not being one of the fixed hosts.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/Context.html Context] class expanded to include some additional helpful attributes.

==== Bug Fixes ====
* [[Admin_Jobs#Nickname.2C_Class_and_Folder|Folder]] Selection in UI fixed to allow intermediary folders selections
* [[Event_Hooks#Slack_Notifier|SlackEventHook]] fixed to include ERROR level
* Logout from My User page fixed to redirect to Login page
* Fixed an issue with PostgreSQL DDL that could report wrong exception on execution failures.

== Obsidian 4.8.0 ==
Released November 2018.

=== Features / Enhancements ===
* Improve performance of job activity view when retrieving large job errors.

==== Bug Fixes ====
* Corrected an issue where in some situations job conflict priority calculation was incorrect.
* Missed and Overlapped job events are now subscribable.

== Obsidian 4.7.1 ==
Released October 2018.

=== Features / Enhancements ===
* New LDAP [[Advanced_Configuration#Authentication_Properties|Configuration Parameter]] to support additional group membership attributes.

==== Bug Fixes ====
* Correct Non-English Locale issues in database DDL/DML.

== Obsidian 4.7.0 ==
Released September 2018.

=== Features / Enhancements ===
* Optimized [[Built-in_Jobs#Job_History_Cleanup_Job|JobHistoryCleanupJob]] for better performance and reduced locking
* New [[REST_Endpoints#DELETE_a_future_scheduled_runtime|REST]] and [[Embedded_API#Delete_a_Future_Scheduled_Runtime_for_a_Job|Embedded]] API function for targeted deletion of a single future one time submission including its parameters.
* Modified job_state index to improve job listing performance in cases where there are a large of future-dated [[Job_Features#Resubmission_.26_Ad_Hoc_Runs|ad-hoc submissions]].
* PostgreSQL 10 Support
* Oracle 12c support

==== Bug Fixes ====
* Add missing job_history index on PostgreSQL installations
* Corrected issue where Get Schedules [[Embedded_API#List_a_Job.27s_Schedules|Embedded]] and [[REST_Endpoints#GET_a_list_of_an_existing_job.27s_schedules|REST]] APIs were setting all parameters to the ordinal of the last parameter.

== Obsidian 4.6.2 ==
Released August 2018.

=== Features / Enhancements ===
* Reduce locking in certain cases of job delete.

==== Bug Fixes ====
* Corrected NPE when performing recovery on a job that has transitioned from Disabled to Enabled state.

== Obsidian 4.6.1 ==
Released July 2018.

=== Features / Enhancements ===
* Performance improvements related to Job Result loading.
* Added informational logging for cases where licence key configuration will not applied.

==== Bug Fixes ====
* Corrected issue where stale admin_only hosts were not cleaned from database.
* Corrected issue where licence release failures were never logged due to shutdown state.

== Obsidian 4.6.0 ==
Released June 2018.

=== Features / Enhancements ===
* [[Advanced_Configuration#Miscellaneous_Properties|Support]] for starting a scheduler node in paused state.
* Several performance improvements for [[Admin_Job_Activity|Job Activity]] view.

==== Bug Fixes ====
* Removed class reference that was causing failures running Obsidian against Java 10.

== Obsidian 4.5.1 ==
Released April 2018.

=== Features / Enhancements ===
* Upgrade of [[Advanced_Configuration#Dependent_Libraries|bundled Groovy library]] which addresses known Groovy memory leaks.
* [[Getting_Started#Standalone_Scheduler|Standalone mode]] now attempts graceful shut down when SIGTERM is issued.

==== Bug Fixes ====
* [[Authenticator#Customizing_our_LDAP_Authenticator|LDAPAuthenticator]] no longer fails when combining delimited base.dn with search user.
* Defensively protect against possible stack overflow in [[Spring_Integration#Dependency_Injection_via_Spring|SpringContextAware]] for cyclical annotation hierarchies.

== Obsidian 4.5.0 ==
Released March 2018.

=== Features / Enhancements ===
* [[Event_Hooks|Custom Event Hooks]] allow for custom triggers on Obsidian events for things such as instant messaging, customized logging, etc.
* [[Event_Hooks#Slack_Notifier|Slack Notifier]] implemented as an [[Event_Hooks|Event Hook]]
* [[Implementing_Jobs#Async_Jobs|Async job]] support
* [[Implementing_Jobs#Dynamic_List_Providers|Dynamic List Provider]] support
* LDAP [[Authenticator|Authenticator]] to support delimited value [[Advanced_Configuration#Authentication_Properties|configurations]] for dn.base and Obsidian role/group mapping.
* Directory/File classes now provide folder/file in question throwing underlying filesystem exceptions.

==== Bug Fixes ====
* [[Recovery_%26_Failover#Configurable_Job_Recovery|Last recovery]] cron patterns no longer fail crossing some boundaries
* Not all job attributes were being applied in Obsidian [[Initializing_and_Restoring#Startup_Initialization|initialization file]]. Pickup buffer minutes wasn't being used in both create and update cases, job folder wasn't being used in update cases.
* Correct invalid Oracle index name

== Obsidian 4.4.1 ==
Released January 2018.

=== Features / Enhancements ===
* Job Queuer, Spawn Locking, Last Recovery performance improvements, includes a new database index.

==== Bug Fixes ====
* Admin UI restores previous search filter settings. In cases where the last job with a given Job Folder was deleted, or for screens that filter by Job Nickname, the filter was still applied but not visible resulting in no results returned. Now, any invalid options are automatically removed.
* [[Recovery_%26_Failover#Configurable_Job_Recovery|Last Recovery]] in rare cases would recover too far back.

== Obsidian 4.4.0 ==
Released October 2017.

=== Features / Enhancements ===
* Fixed Hosts now support [[Admin_Jobs#Advanced_Options | Blacklists]]
* Job Results now support [[Implementing_Jobs#Customizing_Job_Result_Serialization_and_Deserialization | Custom Serialization/Deserialization]] and default Gson JSON for complex objects.
* [[Advanced_Configuration#Properties_File|Configuration]] values may be specified as System Properties/Environment Variables.
* Obsidian upgrades now support [[Getting_Started#Disabling_DDL_Updates|data-only upgrades]] (structural changes are pre-applied offline).
* Job classes may now be partially introduced into the cluster and subsequently scheduled/executed without being attempted on missing hosts avoiding failures (via JobSpawner parameter ''skipSpawnAttemptsForUnavailableJobs'').
* [[Embedded API]] and [[REST API]]s now return basic audit values (created/updated user/time)

==== Bug Fixes ====
* Obsidian upgrades spanning multiple structural and data changes to a given table no longer fail.

== Obsidian 4.3.0 ==
Released June 2017.

=== Features / Enhancements ===
* [[REST_Endpoints#GET_licence_details_on_an_existing_scheduling_host |REST Endpoint]] and [[Embedded_API#Get_Licence_Health_by_Host|Embedded API]] for Licensing Health Check
* Support Markdown and customizable [[Description_%26_Parameter_Formatting|Formatting]] in Job description and Parameter description annotations
* Support timed wait as the new default on FOR UPDATE statements in Oracle - [[Advanced_Configuration#Database_Properties | Advanced Configuration - Database Properties]]. Old or customized behaviour possible via configuration properties.

==== Bug Fixes ====
* Fix issue in [[Built-in_Jobs#Disabled_Job_Cleanup_Job|DisabledJobCleanupJob]] that fails to delete disabled jobs with chained and/or resubmitted records.

== Obsidian 4.2.1 ==
Released May 2017.

==== Bug Fixes ====
* [[Cron#Recurrence|Recurrence]] schedules in server recovery will fail if last runtime doesn't exist.
* A job that is configured against a job class that has since been removed from the cluster can now be [[Admin_Jobs|loaded]]/[[Admin_Jobs#Deleting|deleted]] from the UI.
* [[Admin_Jobs#Deleting|Delete Job]] - If the delete operation fails for any reason and the operator leaves the modal and returns, the error from the previous operation was still visible.

== Obsidian 4.2.0 ==
Released March 2017.

=== Features / Enhancements ===
* Time Zone support in [[Cron|Cron]] patterns. Allows a cluster running in a single time zone to run jobs designated in different timezones.

==== Bug Fixes ====
* LAST [[Recovery_%26_Failover#Configurable_Job_Recovery|recovery mode]] wouldn't fire latest job on cluster recovery if the job had never fired or if the last runtime had been deleted by the maintenance job.
* ALL [[Recovery_%26_Failover#Configurable_Job_Recovery|recovery mode]] would fire first missed job, but the remaining ones wouldn't run and would be set as OVERLAPPED.
* When creating a new schedule that overlaps one or more previously configured future runtimes with parameters, parameters are now deleted from the database.

== Obsidian 4.1.0 ==
Released February 2017.

=== Features / Enhancements ===
* [[Admin_Jobs#Nickname.2C_Class_and_Folder|Folder]]/tag support for jobs including a [[REST_Endpoints#GET_a_list_of_job_folders|REST]] endpoint and [[Embedded_API#List_Job_Folders|Embedded]] method.

==== Bug Fixes ====
* UI issue in Job Execution Subscriptions and Templates - selected jobs now displaying correctly after save/refresh.
* [[Initializing_and_Restoring#Transfer_or_Restore_a_Configuration|UpdateConfigurationAction]] no longer fails in non-native Authentication mode if an empty Users element is provided.

== Obsidian 4.0.2 ==
Released October 2016.

=== Features / Enhancements ===
* [[Implementing_Jobs#Parameterization|Job Parameter]]s now support an optional <code>description</code> to be displayed in UI Help.

==== Bug Fixes ====
* Fixed an issue where [[Cron#Special_Character_Usage|Cron special character]] <code>L</code> would not work if specified as the only value in a field.
* Fixed 3.8.0 MySQL upgrade script.
* Fixed an issue where Obsidian continued to attempt regular licence verification after a valid site licence had been configured.
* Fixed an issue where table prefixes weren't used in all lookups.

== Obsidian 4.0.1 ==
Released August 2016.

==== Bug Fixes ====
* Fixed bug where a chained job that became conflicted would not evaluate chain conditions once it was no longer conflicted.
* Fixed catalina.base bug and dos line endings in jetty.sh script in bundled jetty server.
* Fixed job parameter edit box resizing bug.

== Obsidian 4.0.0 ==
Released July 2016.

=== Features / Enhancements ===
* All New User Interface
* Obsidian is now built using [[Getting_Started#Supported_Platforms|Java 7]]. No longer supports Java 6.
* [[Getting_Started#Really_Quick_Start_With_H2_and_Jetty|Quick Start]] now uses Jetty.
* Many [[Advanced_Configuration#Dependent_Libraries|updated libraries]] including some that had been updated to Java 7.
** ''Breaking Change'' New H2 library. If you're using the H2 database, you will want to look into [[Initializing_and_Restoring|exporting and restoring]] your Obsidian environment's configuration.
==== Bug Fixes ====
* [[REST_Endpoints#GET_a_system_restore_configuration|GetConfiguration]] filtering no longer fails when Templates/Subscriptions are job targeted.

== All Other Releases ==

=== Obsidian 3.8.0 ===
Released June 2016.

=== Features / Enhancements ===
* [[Job_Features#Resubmission_.26_Ad_Hoc_Runs|Ad Hoc]] runs now may be submitted multiple times per minute. [[Chaining|Chains]] may result in target jobs multiple times per minute. Existing behaviour of [[Admin_Jobs#Execution_.26_Pickup|Chain All]] job configuration remains unchanged.
* [[Built-in_Jobs#Script_Job|Script Job]] now supports best-effort interruption.
* APIs for GET System Restore Configuration support filtering for both [[REST_Endpoints#GET_a_system_restore_configuration|REST]] and [[Embedded_API#Get_System_Restore_Configuration|Embedded]].
* [[Implementing_Jobs#Parameterization|Context]] for job execution now supports retrieving the chain source job config, when applicable. See also the Javadoc for [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/Context.html#getSourceConfig() Context].
* [[Getting_Started#Setting_Host_Names|Host names]] maximum length increased to 255 characters from 50.

==== Bug Fixes ====
* Fixed an issue where [[Admin_Jobs#Execution_.26_Pickup|auto-interrupts]] were not firing.

=== Obsidian 3.7.1 ===
Released April 2016.

=== Features / Enhancements ===
* Job APIs windows now with improved locking/blocking on schedule modifications.

==== Bug Fixes ====
* [[REST_Endpoints#GET_a_system_restore_configuration|GET SystemRestoreConfiguration]] no longer fails when using non-native authentication.

=== Obsidian 3.7.0 ===
Released March 2016.
==== Features / Enhancements ====
* New maintenance job [[Built-in_Jobs#Disabled_Job_Cleanup_Job|Disabled Job Cleanup Job]].
* Support for parameters that are [[Implementing_Jobs#Parameterization|required at runtime]].
* Filter [[REST_Endpoints#GET_a_list_of_an_existing_job.27s_schedules|job schedules endpoint]] by start date and/or end date.
* Return [[REST_Endpoints#GET_details_of_an_existing_job|runtime parameters]] for schedule-based one-time runs.

==== Bug Fixes ====
* [[Embedded_API#Get_System_Restore_Configuration|SystemRestoreConfiguration]] export was only including the last schedule of a job.
* Admin-only hosts fail on startup if not in consistent timezone as cluster.

=== Obsidian 3.6.1 ===
Released February 2016.
==== Features / Enhancements ====
* Enhance JobQueuer to reduce execution time when dealing with large numbers of chain-only jobs.

==== Bug Fixes ====
* Fix issue where job that is scheduled and chained is scheduled late after being chained.

=== Obsidian 3.6.0 ===
Released January 2016.
==== Features / Enhancements ====
* [[Job_Forking|Forked Jobs]] offer jjdchinga tu mad[[Advanced_Configuration#Properties_File|Classpath com.carfey.properties]] no longer required. Applicable when using overrides.

==== Bug Fixes ====
* AutoInterrupt not being set on jobs from [[Initializing_and_Restoring#Jobs|System Restore]].
* RunningHostManager can, in rare cases, evaluate job metadata as a HostInformation entry.
* Schedule calculation on outage looks back one minute too far when considering pickup buffer.

=== Obsidian 3.5.2 ===
Released December 2015.

=== Bug Fixes ===
* With native authentication, at least one Admin User must still exist when making [[Admin_User_Management#Changing_Users|Role Changes]].
* Cleanup of some internal host management functionality.

=== Obsidian 3.5.1 ===
Released November 2015.

=== Features / Enhancements ===
* Obsidian nodes that are set to different timezones but have the same rules (functionally equivalent such as ''America/Los_Angeles'' and ''PST'') may now be run together.
* [[Authenticator|LDAPAuthenticator]] now supports [[Advanced_Configuration#Authentication_Properties|non-dn user attribute logins]].

==== Bug Fixes ====
* [[Admin_User_Management#Viewing_Rights_.26_Changing_Your_Password|My User]] screen would fail when using LDAPAuthenticator. Now shows authorized roles.
* Stale host and timezone records are predeleted on startup.

=== Obsidian 3.5.0 ===
Released November 2015.

=== Features / Enhancements ===
* Support for scanning and locating CGLIB-enhanced classes in [[Spring_Integration|Spring]] and Grails.
* Improved [[Admin_Job_Run_Time_Preview|runtime preview]] listing performance.
* Automatic logging of Obsidian version number no longer requires special configuration.
* [[Authenticator]] implementations including LDAP now support checking user validity when the "remember me" option is used to authenticate.
* Runtime listing [[REST_Endpoints#GET_a_list_of_scheduled_runtimes_.28supports_multiple_jobs.29|REST endpoint]] and [[Embedded_API#List_Scheduled_Runtimes|Embedded API]] now support specifying a sort order, maximum quantity and parameter filtering, and now guarantee ordering by scheduled time.

=== Bug Fixes ===
* Capped [[Admin_Job_Run_Time_Preview|runtime preview]] results now respect ascending ordering.

=== Obsidian 3.4.1 ===
Released September 2015.

==== Bug Fixes ====
* Remove undesired field jobHistoryRunningId from runtime listing REST endpoint.
* Fixed standalone scripts that would not shutdown instance when hostname could not be determined.
* Shell scripts should always exit with non-zero code on error.
* Improve forked job shell script compatibility.

=== Obsidian 3.4.0 ===
Released September 2015.

==== Features / Enhancements ====
* [[Cron#Recurrence_Start_DateTime|Recurrence]] supports a start datetime.
* [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] support [[Job_Features#Expected_Length_Handling_.28job_execution_duration.29|Auto Interruption]] when maximum expected run length is exceeded.
* [[Implementing_Jobs#Global_Parameters|Global Parameters]] support [[Implementing_Jobs#Global_Substitution_Mode|Global Substitution Mode]].
* Added ''jobClass'' parameter to job search in REST and Embedded APIs.
* Performance improvements in cron and recurrence calculations.
* Add database index for recovery performance.
* Support for [[Advanced_Configuration#Database_Properties|disabling internal connection pool]].
* Support [[Advanced_Configuration#Miscellaneous_Properties|base HREF overrides]] for load balancers, etc.
* JobHistoryCleanupJob always cleans up expired schedules according to <code>maxAgeDays</code> parameter.

==== Bug Fixes ====
* Default sequence_manager pool to 10% of connections with min of 2.
* Fix issue where parameter order is not maintained consistently on PostgreSQL
* Fix issue where JobHistoryCleanupJob misses cleaning up jobs that are in MISSED state.
* JobHistoryCleanupJob leaves latest runtime record to ensure Recurrence schedules fire at correct time.

=== Obsidian 3.3.3 ===
Released August 2015.

==== Bug Fixes ====
* Chain Skipped and Conflict Missed job runtime enum values corrected to use underscores in REST/Embedded API when listing runtimes.
* In rare cases, outages or queuing delays could prevent first job history from ever being queued.
* Job initial schedule end time not editable via text entry when cloned.

=== Obsidian 3.3.2 ===
Released June 2015.

==== Bug Fixes ====
* Restore missing fields on Runtime and RuntimeError classes for REST/Embedded API.
* Defensive handling of missing JOB_STATE records in chaining.
* Job class field in job edit screen loses content if enter is pressed without match.
* Obsidian version added to dispatcher logs.

=== Obsidian 3.3.1 ===
Released June 2015.
==== Features / Enhancements ====
* Case-sensitive collation support for SQL Server.
* Unicode support on SQL Server (please note that existing schemas will not be upgraded automatically).
* Unicode fixes for all platforms.
* Whitespace characters permitted in between delimited schedules.
* Improved logging on warning and error conditions.

==== Bug Fixes ====
* JobSearch not working on Oracle since 3.3.0.

=== Obsidian 3.3.0 ===
Released May 2015.
==== Features / Enhancements ====
* [[Implementing_Jobs#List_Parameterization|Job parameterization]] support for picklists of valid values.
* [[Implementing_Jobs#Dynamic_File_Lists|Server-side file listing]] support.
* Support for multiple [[Cron#Basic_Format|Cron]] schedule patterns.
* [[Admin_Job_Chains#Chain_Tree_View|Tree visualization of chains]].
* [[Admin_Job_Chains#Conditional_Chaining_Configuration|Conditional chains]] now support text ordinal comparisons.
* Added optional [[Admin_Job_Chains#Adding_or_Updating_a_Job_Chain|chain description]].
* Spawning and queuing performance improvements.

==== Bug Fixes ====
* Expired job schedules are no longer deleted when new schedules are applied. A patch is introduced in this release to find and create placeholder schedules for these jobs.
* [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup Job]] allowed configuration of maxAgeScheduleDays to be lower than maxAgeDays resulting in schedules being deleted for which there is still job history.

=== Obsidian 3.2.0 ===
Released April 2015.
==== Features / Enhancements ====
* [[Cron#Recurrence|Recurrence]] job schedules.
* Upgrade to latest Java mail library.
* Support for determining user that initiated a [[Implementing_Jobs#Interruptable_Jobs|job interrupt]].
* Pickup time in [[Job Forking|forked jobs]] now reflects JVM startup to more accurately report execution times.

==== Bug Fixes ====
* Adding new schedule with outstanding auto-retry execution no longer fails.
* Prevent license checks making extra calls.
* Ensure auto retries with 0 interval are executed as soon as possible, instead of after at least one minute.

=== Obsidian 3.1.1 ===
Released April 2015.
==== Bug Fixes ====
* Fix critical bug where successful job runs after failures would be marked as failed due to job recovery handling.

=== Obsidian 3.1.0 ===
Released March 2015.
==== Features / Enhancements ====
* SQL Server 2008-2014 support.
* Improve event log messages.
* "?" now equivalent to "*" in cron schedules.

==== Bug Fixes ====
* Prevent event log messages being dispatched before commit of source data.
* Fix delayed result set cleanup in job queuer in rare cases.

=== Obsidian 3.0.1 ===
Released February 2015.
==== Features / Enhancements ====
* Job schedule preview and update performance improvements.
* Job delete performance improvements for jobs with large number of history records.
* [[Implementing_Jobs#Classpath_Scanning|Classpath scanning]] interval now configurable (useful for job forking).
* [[Built-in_Jobs#Job_History_Cleanup_Job|JobHistoryCleanupJob]] now supports deleting old schedules.

==== Bug Fixes ====
* Jobs running on hosts that are disabled during execution will now flag them as FAILED or COMPLETED as expected.
* Ensure identical job schedule states which butt against each other are merged.
* Set catalina.base property at Winstone startup so default log configuration works.

=== Obsidian 3.0.0 ===
Released February 2015.
==== Features / Enhancements ====
* [[Job Forking|Job forking]] added to support distinct JVM instances for each job execution.
* Full API expansion. APIs now support all functionality exposed by the admin web application. See [[REST Endpoints|REST API]] and [[Embedded API]] for details.
* Pretty URLs and login redirects in admin web application, including bookmark support.
* [[Clustering#Host_Preference|Host preference]] support.
* Full [[Initializing and Restoring|initialization and restoration]] support for Obsidian instances.
* Auto-polling for job history, logs and sent notifications views in admin web application.
* [[Admin_Custom_Calendars#Deleting|Custom calendar delete]] support. Also available in APIs.
* Convenience database [[Upgrading_Obsidian#Database_Upgrade_Scripts|upgrade]] and [[Getting_Started#Database_Creation_Scripts|create]] scripts included in installation bundle. Automatic version upgrades still supported.
* Better [[Implementing_Jobs#Inheritance|inheritance options]] for defined job parameters.

==== Bug Fixes ====
* Fix LAST recovery type when job left in READY state.
* Redirect to proper 404 and error pages.
* Optimize persistence calls to better handle large number of schedules per job.
* Fix LDAPAuthenticator group membership attribute lookup.
* Explicitly shut down daemon connection reaper thread at Obsidian shutdown.
* Fix minor bugs with schedule merges and splits.
* Fix warning shown in rare cases on job history listing.
* Minor help user interface fixes.
* Minor job chain user interface fixes.
* Prevent system parameter sort order changing on updates.
* Fix record duplicates in job history and corresponding APIs caused by multiple chains which have the same source and target jobs.

=== Obsidian 2.9.1 ===
Released November 2014.
==== Bug Fixes ====
* Fixed issue where auto retry caused failure during a Disabled window.
* Fixed filenames on screen data downloads.
* Fixed issue with Last recovery when last executed time to current time spanned a Disabled window.
* Graceful handling of host designator update interruptions.

=== Obsidian 2.9.0 ===
Released November 2014.
==== Features / Enhancements ====
* [[Conflicts#Jobs_in_Multiple_Conflict_Sets|Jobs in multiple conflict sets]].
* Add ad hoc flag to Context object supplied to SchedulableJob instances.
* Improved [[Admin_Job_Chains#Conditional_Chaining_Configuration|chain detail]] messages in [[Admin_Job_History_(3.x.x and earlier)#Job_History_Details|job history details]] table.
* Ability to set the host designator for multiple Obsidian instances in the same JVM via <code>com.carfey.obsidian.schedulerDesignation</code> in the [[Advanced Configuration|properties file]].
* Job queuing performance improvements

==== Bug Fixes ====
* Ensure license check multiple is at least 2 in [[Admin_System_(3.x.x and earlier)|System]] tab.
* When recovering jobs which had died, new jobs were flagged as Overlapped instead of Missed.
* All recovery type resulting in Abandoned jobs incorrectly.
* Breadcrumbs incorrect when cloning a job.
* JNDI cannot be used when the key does not start with "java:" prefix. <ref>

If you are using automated installer files from previous releases and are using JNDI, you may add <pre><entry key="database.jndi.name" value="yourJNDIPath"/></pre> anywhere under the userInput element of UserInputPanel.3 and empty out the value for '''database.url'''. For example,
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.3">
<userInput>
<entry key="db.schema" value=""/>
'''''<entry key="database.url" value=""/>'''''
<entry key="database.password" value=""/>
<entry key="database.table.prefix" value=""/>
<entry key="database.connection.timeout" value="2000"/>
<entry key="database.username" value=""/>
'''''<entry key="database.jndi.name" value="java:comp/env/jdbc/obsidianJNDI"/>'''''
<entry key="database.max.connections" value="40"/>
<entry key="include.all.jdbc" value="false"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>

</ref>
* Database connections not rolled back just before close when removed from the pool, resulting in warning log messages.
* Sanitize HTTP headers, email subjects, etc. to prevent injection issues.

=== Obsidian 2.8.1 ===
Released September 2014.
==== Features / Enhancements ====
* New connection pool reaper to draw down pool size if usage allows.

==== Bug Fixes ====
* More explicit handling of connection pool emptying on Obsidian shutdown.

=== Obsidian 2.8.0 ===
Released September 2014.
==== Features / Enhancements ====
* Login popup when session expires in [[Admin_Web_Application_Guide|admin web application]]. Users can now log back in without losing their changes.
* Support for using [[Advanced_Configuration|context classloader]] via configuration property ''com.carfey.jdk.useContextClassLoader''.
* Reduced number of connections required for normal operation. Previously, up to 1 connection per job per minute was required.
* Minor user interface improvements.
* Support for re-queuing jobs rejected from the job thread pool (via parameter ''queueJobsOnPoolRejection'').
* Improved default log4j rolling file appender configuration.

==== Bug Fixes ====
* Fix NullPointerException on job recovery when last job was rejected by the thread pool.
* Fix rare instances of licenses not being released due to token file issues
* Fix poor validation message on saving if invalid boolean system parameter.

=== Obsidian 2.7.1 ===
Released August 2014.
==== Features / Enhancements ====
* [[REST_API#Authentication_.26_Authorization|REST authentication]] can be configured to be optional.
* Cron pattern expansion. Support range increments (e.g. 3-20/5)

==== Bug Fixes ====
* Fix NullPointerException in handling mdoodood..dkididkdkd
IP changes.
* Upgraded to TLD 2.0 fixing Obsidian WAR deployment in JBoss 6.

=== Obsidian 2.7.0 ===
Released July 2014.
==== Features / Enhancements ====
* [[Admin_Notifications#Job_Execution_Subscriptions|Re-tooled job execution notifications]], including [[Admin_Notifications#Conditional_Job_Notification_Configuration|conditional notifications]]
* We have open-sourced all of our [[Built-in_Jobs | built-in jobs]]!
* File-based job [[Implementing_Jobs#Initializing_Job_Schedules|initialization]].

==== Bug Fixes ====
* Fix page jumping when modifying job chain conditions on long pages.

=== Obsidian 2.6.1 ===
Released June 2014.
==== Features / Enhancements ====
* Cygwin support in startup/shutdown scripts.
* Run parameters override configured parameters.

==== Bug Fixes ====
* Oracle CLOB field storage fix.
* Fix single-node mode on host with no recognizable NIC.
* Prevent currently or soon to be running jobs from being deleted.
* Fix multiple job history parameters failing on H2.

=== Obsidian 2.6.0 ===
Released May 2014.
==== Features / Enhancements ====
* [[Implementing_Jobs#Classpath_for_Building_and_Deploying|Job implementation metadata stored in database]]. Admin UI deployments no longer require Job Implementations on the classpath in order to schedule and configure.
* Delete Chain support in [[Admin_Job_Chains#Deleting|UI]], [[Embedded_API#Delete_a_Job_Chain|Embedded API]] and [[REST_Endpoints#DELETE_an_existing_job_chain|REST API]]
* Hardware-linked licensing supported in public Obsidian bundle.

==== Bug Fixes ====
* Fixed [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] to work in WebLogic 12c.
* Fixed chain recovery date ranges being overly broad.
* Ensure any stale timezone records are cleaned up.
* Removed some libraries stored multiple times in installer.

=== Obsidian 2.5.1 ===
Released April 2014.
==== Features / Enhancements ====
* Expose convenience JobId and Nickname getters in [[Implementing_Jobs#SchedulableJob_Interface|Context]].
* Improved performance of chaining recovery.
* [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|JarJar]] bytecode modification support now includes gson.<ref>

If you are using automated installer files from previous releases, you may add <pre><entry key="jarjar.gson" value="true"/></pre> or <pre><entry key="jarjar.gson" value="false"/></pre> according to your desired usage anywhere under the userInput element of UserInputPanel.14. For example,
<com.izforge.izpack.panels.UserInputPanel id="UserInputPanel.14">
<userInput>
'''''<entry key="jarjar.gson" value="false"/>'''''
<entry key="jarjar.jxl" value="false"/>
<entry key="jarjar.dom4j" value="false"/>
<entry key="jarjar.jmustache" value="false"/>
<entry key="jarjar.opencsv" value="false"/>
<entry key="jarjar.h2" value="false"/>
</userInput>
</com.izforge.izpack.panels.UserInputPanel>

</ref>
* Introduced support for having a scheduler and non-scheduler instance running in same class-space.

==== Bug Fixes ====
* Improved failure messaging when a scheduler node is started in a different time zone than the current nodes in the cluster.
* Chain search filters aren't saved.
* Exclude unneeded web jars from standalone installations.

=== Obsidian 2.5.0 ===
Released March 2014.
==== Features / Enhancements ====
* [[Admin_Jobs#Execution_.26_Pickup|Retry Interval]] support for Auto Retry of failed jobs.
* [[Admin_Global_Parameters|Global Job Parameter]] support.
* [[Installation_Guide#JNDI_Configuration|JNDI Support]] for Database Connections and Email Sessions.
* MariaDB 5.5 support.
* JBoss AS 7 support.
* Text filter on Job Chain View.
* [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|JarJar]] bytecode modification support during installation to avoid dependency conflicts.
* Embedded API Javadoc artifact included in installation.

==== Bug Fixes ====
* Support */2 cron expressions, [[Admin_Jobs#Edit.2C_View_.26_Change_Schedules|Schedule Inputs]] extended to 255 characters.
* REST API - [[REST_Endpoints#GET_a_list_of_jobs|JobListing]].<code>getJobs()</code> was returning <code>List<Job></code> instead of <code>List<JobState></code>.
* Support multiple keys in key server proxy.
* Support VFS URLs in [[Implementing_Jobs#Classpath_Scanning|Classpath Scanner]] for JBoss.
* Postgres failed on blank schema.
* Job resubmission validates that job isn't disabled for next minute instead of current minute.
* Embedded API - [[Embedded_API#Delete_a_Job|Delete Job]] would fail if job class has since been removed from classpath.
* [[Admin_Jobs#Job_Listing|Job Listing]] schedule/state defaults to next minute.
* Filters aren't saved consistently on search screens and never saved for runtime preview.
* Table settings aren't saved on [[Admin_Jobs#Job_Listing|Job Listing]].

=== Obsidian 2.4.1 ===
Released February 2014.
==== Bug Fixes ====
* Fix installer not working in console mode.
* Ensure that defined job parameters and their values are returned in the original configured order.

=== Obsidian 2.4.0 ===
Released February 2014.
==== Features / Enhancements ====
* New [[Getting_Started|graphical installer and simplified startup scripts]].
* Full support for job chaining and conflicts in the [[REST API]] and [[Embedded API]].
* Revamped WebSphere support (8.5).
* [[Scripting Jobs]] can now be configured with a script file path instead of the script itself.
* New [[Built-in_Jobs#MySqlBackupJob|MySqlBackupJob]] built-in job.
* Informational message logged when a new version of Obsidian is available.
* [[Admin_User_Management#Deleting_Users|Delete user]] support.

==== Bug Fixes ====
* Fixed job execution recovery not working in some cases when the database is temporarily unavailable.
* Fix PostgreSQL connections not released from pool properly when connection is invalid.
* Fix [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] on WebSphere.
* Fix UI rendering issue on Jobs screen on WebSphere.

=== Obsidian 2.3.1 ===
Released December 2013.
==== Features / Enhancements ====
* New [[Built-in_Jobs#Script_Job|Script File Job]]
* Improved responsiveness of job interrupts for built-in jobs.
* UI tweak to [[Jobs]] screen to avoid displaying custom calendars when not in use.

==== Bug Fixes ====
* Update default log configuration for Tomcat to use <code>catalina.base</code>, which works consistently on *nix platforms.
* Remove redundant event logging for job success and failure in the Job Spawner category.
* Handle releasing licenses even when temp directory is not writable, and attempt to use working directory as a fallback.
* Job names containing ampersands did not work as filters in search screens.
* Host designator assigned earlier in startup to ensure logging accurately reports the host.

=== Obsidian 2.3.0 ===
Released November 2013.
==== Features / Enhancements ====
* Fully unified [[Embedded API]] which contains same operations and has same semantics as the [[REST API]]. The previous Legacy API is now deprecated.
* [[REST API]] bean classes bundled in <code>obsidian.jar</code> for simplified Java integration.
* Submission of [[Admin_Jobs#Ad_Hoc_.26_One-Time_Run_Submission|one-time job runs]] via the UI now allows specifying exact minutes instead of 5 minute intervals.
* [[Chaining]] evaluation is now fully recoverable. Processing of chaining now processed independently of job execution.
* Dozens of UI tweaks and improvements.
* Stale hosts in [[Systems|Systems tab]] now are pruned after about an hour of inactivity. Host disabling is preserved if the node is restored.
* Graceful shutdown in Winstone for [[Getting Started|quick start]] method.
* [[Jobs#Custom_Calendars|Custom Calendars]] can now be specified with multiple delimiters, including new lines and spaces.
* [[Email Templates]] can now include the event category.
* Track most recent upgraded version in the database.
* Job runtime [[REST_Endpoints#GET_a_list_of_scheduled_runtimes_.28supports_multiple_jobs.29|REST endpoint]] now defaults to a more useful previous 24-hour window.

==== Bug Fixes ====
* Chain All setting not shown correctly when editing existing [[Jobs]].
* Abandoned, Missed and Conflict Missed chaining never fires.
* Current scheduled state not shown correctly for existing jobs in [[Jobs]] in Winstone.
* Export on [[Logs]] contained extra text in ID column.
* Chained jobs now respect host restrictions.
* Correct custom calendar reversed PUT/POST for [[REST API]], and implement standardized date formatting.
* UI table listings no longer flash error message when quickly navigating away during a request.
* Legacy API calls no longer incorrectly start non-daemon threads for notifications and event logging.
* Lock issues when evaluating many [[Chaining|chained jobs]].

=== Obsidian 2.2.1 ===
Released October 2013.
==== Features / Enhancements ====
* Enhanced [[Spring_Integration|Spring Integration]] to remove need for distinct [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]]. Jobs can be auto detected from Spring context.
* Enhanced [[Job_Features#Host_Restrictions_or_Affinity|Running Hosts Restrictions]]. Now a configuration value can be used to determine if these restrictions apply to Ad Hoc jobs.
* Ability to [[Getting_Started#Disabling_Automatic_Database_Updates|disable database updates]] on startup.
* Add helpful text to job screen indicating you can type in a job class Obsidian
* Additional Spring support for [[Spring_Integration#Wiring_an_Embedded_Obsidian_Scheduler|embedded schedulers]].

==== Bug Fixes ====
* Corrected issue where classpath scanning configuration values were being overridden back to default on each restart (introducted in 2.1).
* Fix SchedulerStarter shutting down JVM in embedded mode.

=== Obsidian 2.2.0 ===
Released October 2013.
==== Features / Enhancements ====
* [[Spring_Integration|Spring]] Dependency Injection support.
* [[Built-in_Jobs#File_Scanner_Job|File scanner]] job.
* [[Advanced_Configuration#Dependent_Libraries|Python and Groovy]] libs updated. Python from jython.jar (version 2.5.2rc2) to jython-standalone-2.5.3.jar. Groovy from groovy-all-1.7.6.jar to groovy-all-2.1.8.jar.

==== Bug Fixes ====
* DBAuthenticator is now defaulted configuration. Improved handling of bad configuration on startup.
* Obsidian web app startup no longer attempts to start the scheduler with certain types of unrecoverable bad configuration.
* Fixed issue where classpath scanner only worked in Admin Web Application if running with an embedded scheduler.
* Fixed issue where Auto Failure Retry combined with triggered Job Chaining resulted in chaining failure.
* Cleaned up Job History Search Results File Export that could contain garbage characters.
* Fixed issue where job runtime preview fails when only disabled job state exists.
* Fixed TRACE logging level - No logging output if level explicitly set to TRACE.
* Remove unnecessary JAR files bundled with the installation package.

=== Obsidian 2.1.1 ===
Released September 2013.
==== Features / Enhancements ====
* [[Admin_Jobs#Run_Parameters|Ad Hoc / One-Time Run Job Parameterization]].
* Obsidian license purchases via Stripe.
* All Carfey Software libraries bundled into single obsidian.jar.

==== Bug Fixes ====
* Postgres schema support - only supported public schema.
* LogCleanupJob does not validate specified LEVEL attribute.
* LDAPAuthenticator assumed ''cn'' in building ''dn'' for authentication. Now configurable - see [[Advanced_Configuration#Configuration_Details|Advanced Configuration]].
* LDAPAuthenticator assumed only ''uniqueMember'' for group membership. Now also checks other common attributes, supporting ActiveDirectory. See [[Authenticator#Customizing_our_LDAP_Authenticator|LDAP Authenticator]].
* ''run.obsidian'' target execution classpath included in Obsidian bundle includes non-jar/non-resource files.
* Site license verification runs once on startup instead of every lease cycle.
* Date parsing issue related to Locales on retrieving and refreshing license. Fixed in [http://sourceforge.net/projects/carfeydate/ release 1.2 of carfey-date].
* In rare cases, job results in Job History listing could be mangled.
* Proxy key server would fail on requests when run from time zones different from the master key server.
* Oracle job results limited to 2000 characters - now unlimited on all platforms.

=== Obsidian 2.1 ===
Released July 2013.
==== Features / Enhancements ====
* [[Obsidian_Tables|Table name prefix]] support.
* [[Licenses & Nodes|Site license]] support in public Obsidian bundle.
* [[Advanced_Configuration#Properties_File|Programmatic properties]] override support.
* Alternate [[Advanced_Configuration#Configuration_Details|schema user/owner]] support. Additional Oracle details [[Obsidian_Tables#Oracle_Privileges|here]].
* [[Admin_Notifications#Deleting_a_Subscriber|Delete subscriber]] support.

==== Bug Fixes ====
* Ensure all [[Admin_Logs|Event Log]] messaging to always use Display Name for enums.
* Expand script job disabling to disable all potentially dangerous jobs.
* Ensure internal class AnnotatedSchedulableJob is always excluded from available class listing in [[Admin_Jobs#Job_Nickname_and_Class|Job Admin]].
* Upgraded to more recent Oracle JDBC driver (11.2.0.3)
* Various database metadata optimizations
* [[Implementing_Jobs#Classpath_Scanning|Classpath scanner]] rescans on parameter changes.

=== Obsidian 2.0 ===
Released June 2013.
==== Features / Enhancements ====
* [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] to automatically populate Job UI with available jobs.
* Fully customizable [[Email_Templates|Email Templates]].
* New [[Embedded_API|Embedded API]] operations exposed so job configuration can be manipulated without REST API or UI.
* [[Admin_Jobs#Custom_Calendars|Custom Calendar]] support to add date-based exclusions to job schedules (e.g. holidays).
* New [[Admin_User_Management#User_Rights|Limited Read]] role which restricts access to potentially sensitive configuration.
* New [[Built-in_Jobs|Built-in Jobs]] - file archival and file clean up.
* Easy [[Admin_Jobs#Job_Listing|job cloning]] in UI.
* [[Built-in_Jobs#Shell_Script_Jobs|Shell scripting]] job support.
* Additional [[Admin_Jobs#Job_Edit_Screen|job execution options]] - auto-retries on failure and new "Chain All" chaining mode.

==== Bug Fixes ====
* Improve logging of some trapped exceptions.
* Improve handling of spawn locks to reduce contention.
* Fix standalone execution from Ant script.

=== Obsidian 1.5.2 ===
Released May 2013.
==== Features / Enhancements ====
* Job nickname lengthened from 50 to 255 characters to allow more specific nicknames.
* Database metadata loading restricted to known Obsidian application tables.
* Add support in [[REST_Endpoints#Job_Endpoints|job listing endpoint]] for nickname and job custom parameter tag search.

==== Bug Fixes ====
* Fixed JobHistoryCleanupJob failures that occurred when a record to be cleaned up had been interrupted.
* Disallow failed job resubmission if the job is currently running. This prevents these resubmissions from potentially being ABANDONED due to execution duration exceeding pickup buffer minutes specified on the job. Job is available for resubmission once currently running job completes.

=== Obsidian 1.5.1 ===
Released February 2013.
==== Features / Enhancements ====
* [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]], including new [[REST_API|REST API]] endpoint.
* Spawning improvements to seek minute boundaries more consistently.
* Runtime preview now defaults to start time to current time.
* Improved license handling for paid licenses to increase reliability in case of outages.
* A handful of minor UI tweaks and additions.

==== Bug Fixes ====
* Fix connection handling when database connectivity is lost in spawner or queuer threads.
* Fix criteria causing some running conflicts to be not found resulting in conflicted jobs running concurrently.
* Improve messaging and details when failing to connect to MySQL.
* Various UI fixes.
* Events for jobs would sometimes be dispatched for the wrong target.

=== Obsidian 1.5 ===
Released January 2013.
==== Features / Enhancements ====
* [[REST_API|REST API]] for a complete range of job, scheduling and host management features.
* Export support in Excel, CSV and XML in [[Admin_Job_History_(3.x.x and earlier)#Exporting_Results|Job History]], [[Admin_Jobs#Exporting_Results|Job]], [[Admin_Job_Run_Time_Preview|Job Runtimes]], [[Admin_Logs#Exporting_Results|Log]] and [[Admin_Notifications#Sent_Notifications_Screen|Sent Notifications]] views.
* Expected job run time parameters - [[Admin_Jobs#Execution_.26_Pickup|See Expected Length]]. Events trigger in cases where execution duration is outside of defined threshold.
* Display actual run duration in job history view
* Enhance run once future date pattern to match actual future date. Contributes to consistency in job state absorption in new overlapping state ranges.
* Allow single node to run without valid lease
* Add 90/120 minutes pickup buffer option

==== Bug Fixes ====
* Ad hoc submission validation text inconsistent
* Job set to ad hoc active state would not allow one-time immediate submissions.
* Workaround String indexoutofbounds issue with winstone server
* Read-only users can submit one-time job runs.
* Can't save unscheduled active job in postgresql
* After saving new user, help icon disappears
* MySQL - Audit columns hit truncation error when registered user is too long
* Various display bugs

=== Obsidian 1.4.2 ===
==== Bug Fixes ====
* Lock wait timeout fix

=== Obsidian 1.4.1 ===
==== Features / Enhancements ====
* Conditional [[Chaining]] support.
* [[Admin_Jobs#Deleting|Delete]] job support.
* [[Admin_Jobs#Job_Listing|Job]] view filter inclusivity those with only future states.
==== Bug Fixes ====
* Default initial sorts case insenstive
* Status scheduling allowed for gaps
* Failed conditional chain prevents scheduling of job
* Schedule preview isn't ordered by effective date
* JobHistory order by clause sometimes ignored

=== Obsidian 1.4 ===
==== Features / Enhancements ====
* View of saved job history [[Admin_Job_History_(3.x.x and earlier)#Job_History_Details|results]].
* Add schedule shortcut link on Job view
==== Bug Fixes ====
* Various display bugs

== Footnotes ==
<references/>

REST Endpoints

2026-07-31T14:49:58Z

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

This page documents the format of each available REST endpoint.

For information on data formats, valid enumerations values, common behaviour and more, see the primary [[REST API]] page.

All endpoints have corresponding bean classes that can be used with JSON object mappers like [https://github.com/google/gson Gson]. If you wish to use these, please review [[REST_API#JSON_Bean_Classes|bean classes]] for information on serialization of Obsidian's custom types.

= Job Endpoints =

==GET a list of jobs==
'''<code>GET http(s)://localhost/rest/jobs[?host=host1&activeStatus=ENABLED&nickname=jobname&param_group=orders&jobClass=com.example.ExportJob]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobListing</code>

Returns a list of configured jobs, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| activeStatus || N || Restricts the preview to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| effectiveDate || N || If querying by activeStatus, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
|-
| host || N || If specified, only jobs that run on the specified host name(s) are included. Supports multiple values.
|-
| nickname || N || If specified, only jobs matching the supplied nickname are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs containing the word "order", use "%order%". Supports multiple values.
|-
| jobClass || N || If specified, only jobs matching the supplied job class are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs with job classes containing the word "Export", use "%export%". Supports multiple values. ''Available from version 3.4.0 forward.''
|-
| folder || N || If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values. ''Available from version 4.1.0 forward.''
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on jobs with specific job parameter values, either custom or defined. If multiple values for the same query parameter starting with ''param_'' are supplied, a job is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate names are used, each must have a matching value for the job to be returned.

'''Usage note:''' This can be used to tag jobs with searchable metadata by configuring custom parameters. For example, if jobs belong to logical groups, you may create a custom parameter on applicable jobs named "group" and use a query like the following to find jobs belonging to the "customer" or "order" groups:
<code>GET http(s)://localhost/rest/jobs[?param_group=customer&param_group=order]</code>

|}

'''Sample Response'''
<pre>
{
"jobs": [
{
"recoveryType": "NONE",
"jobId": 33,
"pickupBufferMinutes": 5,
"nickname": "jobOne",
"folder": "Production/Test", // as of 4.1.0
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll" : true, // corresponds to chainAll setting on job creation
"activeSchedule": {
"jobScheduleId": 34,
"status": "CHAIN_ACTIVE",
"endDate": "2999-12-31T23:59:00-0800",
"effectiveDate": "2013-01-06T14:37:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"revision": 0
},
{
"recoveryType": "CONFLICTED",
"jobId": 35,
"pickupBufferMinutes": 123,
"nickname": "jobTwo",
"interruptable": false
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll" : true, // corresponds to chainAll setting on job creation
"activeSchedule": {
"jobScheduleId": 37,
"status": "ENABLED",
"schedule": "@daily",
"scheduleDescription": "At midnight every day" (as of 5.2.0)
"endDate": "2013-01-08T14:34:00-0800",
"effectiveDate": "2013-01-07T14:34:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"revision": 2
}
]
}
</pre>

==GET details of an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Returns full job information, including all historical schedules and parameter information. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"schedules": [
{
"effectiveDate": "2013-01-08T15:15:00-0800",
"endDate": "2031-04-30T07:59:00-0800",
"status": "ENABLED",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day" (as of 5.2.0)
"jobScheduleId": 35,
"customCalendarId": 123 // if configured, the custom calendar
},
{
"effectiveDate": "2031-04-30T08:00:00-0800",
"endDate": "2031-04-30T08:00:00-0800",
"schedule": "0 8 30 4 3#5",
"scheduleDescription": "At 8:00AM on the 30th during April on the 3rd Friday" (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 2952,
"parameters": [{
"value": "value",
"name": "paramName",
"type": "STRING",
"values": ["value"]
}]
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"currentJobScheduleId": 35, // id of the item in "schedules" which is active right now
"jobClassDescription": "This job cleans up log history beyond the configured age.", // returned only if Job is annotated with @Description
"hosts": [
"host1"
],
"job": {
"jobId": 34,
"revision": 0,
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateWithEffectiveDatesAndParams",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"interruptable": false, // indicates if job can be interrupted (as 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll" : true // corresponds to chainAll setting on job creation
},
"parameters": [
{
"name": "level",
"type": "STRING",
"allowMultiple": true,
"required": true,
"values": [ "WARN", "ERROR" ], // Values may contain global parameter references
"defaultValue": "ALL",
"defined": true // true if defined by @Configuration annotation on the job
},
{
"name": "maxAgeDays",
"type": "INTEGER", // see Enumerations above for valid values
"allowMultiple": false,
"required": true,
"values": [ "60" ], // values is always a list for consistency, even when allowMultiple is false
"defaultValue": "120",
"defined": true
}
]
}
</pre>

==POST a new job==

'''<code>POST http(s)://localhost/rest/jobs</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Creates a new job with an initial schedule.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job should be auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"customCalendarId": null,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "{{globalLevels}}" // Values may contain global parameter references
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobClass || Y || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || Y || Unique nickname for the job. Max 255 chars.
|-
| pickupBufferMinutes || Y || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || Y || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| state || Y || Initial schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| schedule || Y/N || If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted. You may specify multiple cron patterns delimiting them with a semi-colon.
|-
| effectiveDate || N || Optional effective date for the initial schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
|-
| endDate || N || Optional end date for the initial schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
|-
| customCalendarId || N || Optional custom calendar id.
|-
| hosts || N || Zero or more host names that this job may run on. If none set, the job may run on any host.
|-
| minExecutionDuration || N || The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
|-
| maxExecutionDuration || N || The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
|-
| autoInterrupt || N || Boolean indicating whether auto interrupt functionality is desired. May only be true when the job is an interruptable job and a maxExecutionDuration has been specified. Defaults to false.
|-
| autoRetryCount|| Y || Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| autoRetryInterval|| N || Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
|-
| parameters || Y/N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==PUT updates to an existing job==

'''<code>PUT http(s)://localhost/rest/jobs/{jobId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Updates a job's configuration. Does not support schedule changes or additions. For schedule changes, see [[#POST a new schedule to an existing job|POST a new schedule to an existing job]].

This endpoint will only update fields that are supplied in the request, similar to a PATCH request. You may update one or more fields as desired.

'''Sample Request'''
<pre>
{
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"nickname": "testCreateMixedHostsAndParams",
"pickupBufferMinutes": 5,
"recoveryType": "NONE",
"hosts": [
"host1",
"host2"
],
"minExecutionDuration": "1s",
"maxExecutionDuration": "5m",
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"chainAll": false,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTNable"
! Field || Required? || Notes
|-
| jobClass || N || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || N || Unique nickname for the job. Max 50 chars.
|-
| pickupBufferMinutes || N || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || N || Recovery type as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| hosts || N || Zero or more host names that this job may run on. If none set, the job may run on any host.
|-
| minExecutionDuration || N || The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
|-
| maxExecutionDuration || N || The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "2h".
|-
| autoInterrupt || N || Boolean indicating whether auto interrupt functionality is desired. May only be true when the job is an interruptable job and a maxExecutionDuration has been specified. Defaults to false.
|-
| autoRetryCount || N || Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| autoRetryInterval|| N || Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
|-
| parameters || N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection.
|}

Responses have the same format as GET.

==DELETE an existing job==

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}[?cascade=true]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Deletes a job and its history. Returns a 404 if not found.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| cascade|| N || If set to true, all job conflict and chain definitions for this job will also be deleted. If not set, or set to false, any existing job conflicts or chain definitions will cause the request to fail.
|}

Responses have the same format as GET, and return the final state of the job before the delete.

==GET a list of an existing job's schedules==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/schedules[?start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Returns historical schedules for a job. This is essentially a subset of the primary GET endpoint for an existing job.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| start || N || Start date for the runtimes to preview (inclusive).
|-
| end || N || End date for the runtimes to preview (inclusive). Must be after the start time.
|}

'''Sample Response'''
<pre>
{
"schedules": [
{
"effectiveDate": "2012-01-06T15:53:00-0800",
"endDate": "2012-08-06T15:53:00-0700",
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"jobScheduleId": 37,
"customCalendarId": 123 // if configured, the custom calendar
},
{
"effectiveDate": "2015-01-06T15:53:00-0800",
"endDate": "2016-01-06T15:53:00-0800",
"status": "AD_HOC_ACTIVE",
"jobScheduleId": 38
}
],
"jobId": 35,
"currentJobScheduleId": 38
}
</pre>

==POST a new schedule to an existing job==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/schedules</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobScheduleListing</code>

Creates a new schedule for the job. This may be used to immediately change a job's scheduling state, or to schedule a future change. Creating a new schedule automatically splits and merges existing schedules. For example, if you have an enabled job and you disabled it for a day, the job will automatically re-enable after that day.

'''Sample Request'''
<pre>
{
"state": "ENABLED",
"schedule": "@daily",
"effectiveDate": "2012-01-10T15:33:00-0800",
"endDate": "2013-01-10T15:33:00-0800",
"customCalendarId": 123 // if desired, the custom calendar
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| state || Y || The schedule's job status as defined in [[Unified_API#Enumerations|Enumerations]].
|-
| schedule || Y/N || If state is ENABLED, the mandatory cron-style schedule for the job. If not ENABLED, this should be omitted. You may specify multiple cron patterns delimiting them with a semi-colon.
|-
| effectiveDate || N || Optional effective date for the schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is DISABLED.
|-
| endDate || N || Optional end date for the schedule, with no seconds specified. If set, the job will become DISABLED after this date passes.
|-
| customCalendarId || N || Optional custom calendar for schedule.
|}

Responses have the same format as GET.

==GET a list of configured global parameters ==
'''<code>GET http(s)://localhost/rest/global_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

Lists the configured global parameters

'''Sample Response'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

==PUT updates to global parameters ==

'''<code>PUT http(s)://localhost/rest/global_parameters</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.GlobalParameterListing</code>

Replaces the configured global parameters with the supplied values. If the value for parameters is missing or empty, all global parameters will be deleted.

'''Note:''' Calls to remove or alter global parameters may fail if jobs that use them do not pass parameter validation as a result of the change. This can be caused by removing a referenced global parameter or values that cannot be interpreted as the appropriate type in a job.

'''Sample Request'''
<pre>
{
"parameters": [
{
"name": "forceSSL",
"type": "BOOLEAN",
"values": ["false"]
},
{
"name": "hostNames",
"type": "STRING",
"values": ["example.com", "test.com"]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| parameters || N || Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "values", where type is a valid parameter type outlined in Enumerations.
|}

Responses have the same format as GET.

==GET a list of job folders ==
'''<code>GET http(s)://localhost/rest/job_folders</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobFolderListing</code>

''Available as of version 4.1.''

Lists all used job folders in both flat and hierarchical modes.

'''Sample Response'''
<pre>

"flat": [
"Prod",
"Prod/Test",
"QA",
"QA/123/456/789/Test",
"QA/Tester"
],
"hierarchy": [
{
"folder": "Prod",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
},
{
"folder": "QA",
"children": [
{
"folder": "123",
"children": [
{
"folder": "456",
"children": [
{
"folder": "789",
"children": [
{
"folder": "Test",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
}
],
"jobUsingDirectly": false
},
{
"folder": "Tester",
"children": [

],
"jobUsingDirectly": true
}
],
"jobUsingDirectly": true
}
]
}
</pre>

= Runtimes Endpoints (i.e. Job History) =

==GET a list of scheduled runtimes (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes[?startKey=12345&status=RUNNING&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

Returns a list of scheduled or completed job runtimes (i.e. history), optionally filtered by query string parameters. Ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values.
|-
| status || N || Restricts the search to the selected statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values. Supports multiple values.
|-
| host || N || If specified, only job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values. ''Available from version 4.1.0 forward.''
|-
| start || N || Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago.
|-
| end || N || End date for the job runtimes to return (inclusive). Defaults to a day after the start time. Must be after the start time.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A value of either "asc" or "desc", which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|-
| param_''parameterName'' || N || If specified, values starting with ''param_'' can be used to match only on runtimes with specific runtime parameter values (not job-level parameters). If multiple values for the same query parameter starting with ''param_'' are supplied, a runtime is matched if any of its configured values match one of the supplied values. If ''param_'' filters with separate names are used, each must have a matching value for the runtime to be returned.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date
"runtimes": [
{
"runtimeOrdinal": 0,
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0,
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

==GET a list of a job's scheduled runtimes==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeListing</code>

This endpoint is equivalent the other runtime endpoint (see preceding item) with a URL like the following: <code>GET http(s)://localhost/rest/job_runtimes?jobId={jobId}</code>

Other than the jobId, all other query string parameters from the multi-job endpoint are supported.

==POST a new scheduled runtime for an existing job (i.e. submit a one-time or ad hoc run)==
'''<code>POST http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeSubmissionResult</code>

Allows for submission of an ad hoc job run (executed immediately), or a one-time run scheduled for a later time.

'''Note:''' The job must be in a valid state to allow for execution (i.e. <code>UNSCHEDULED_ACTIVE</code>, <code>ENABLED</code>, or <code>AD_HOC_ACTIVE</code>).

'''Sample Request'''
<pre>
{
"scheduledTime": "2013-02-06T16:40:00-0800",
// Optional. Parameters supplied for scheduled runtime which will be available to the job when executing.
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "WARN"
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| N || The scheduled time, when the request is for a scheduled one-time run. If not supplied, the runtime is submitted for immediate execution as an ad hoc job.
|-
| parameters || N || Zero or more parameter definitions. Parameter definitions must have values for "name", "type" and "value", where type is a valid parameter type outlined in [[Unified_API#Enumerations|Enumerations]]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. If the parameter name matches a parameter defined for the job, it must be of the same type, and it will completely replace all configured values at the job level.
|}

'''Note:''' A <code>jobRuntimeId</code> is only returned in the case of an ad hoc run.

'''Sample Response (with inline comments) '''
<pre>
{
"jobRuntimeId": 2, // only returned for ad hoc submission (no scheduled time supplied)
"jobId": 36,
"scheduledTime": "2013-01-06T16:37:00-0800"
}
</pre>

==GET details of an existing scheduled (or completed) job runtime==
'''<code>GET http(s)://localhost/rest/job_runtimes/{jobRuntimeId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

Returns detailed information for the requested job runtime. Responses will contain all the same details as a single record from a <code>/job_runtimes</code> GET request, with the addition of the <code>output</code> and <code>parameters</code> elements, which contain saved job results and runtime-specific parameters respectively.

'''Sample Response'''
<pre>
{
"runtime": {
"heartbeatTime": "2013-01-06T16:27:00-0800",
"jobRuntimeId": 2,
"adHoc": false,
"pickupTime": "2013-01-06T16:26:00-0800",
"endTime": "2013-01-06T16:27:00-0800",
"revision": 6,
"resubmission": false,
"scheduledTime": "2013-01-06T16:26:00-0800",
"runningHost": "test3",
"status": "FAILED",
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 2, // present if this job was auto-retried from a failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 36,
"nickname": "testWithOutput",
"activeSchedule": {
"jobScheduleId": 37,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T18:06:00-0800",
"effectiveDate": "2013-01-06T16:25:00-0800",
"customCalendarId": 123 // if configured, the custom calendar for this job
},
"jobClass": "someclass"
},
"chainSource": null,
"chainTargets": [

],
"output": [
{
"jobRuntimeResultId": 4,
"name": "testname",
"value": "testvalue",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 5,
"name": "testname",
"value": "testvalue2",
"valueType": "java.lang.String"
},
{
"jobRuntimeResultId": 6,
"name": "testname2",
"value": "testvalue3",
"valueType": "java.lang.String"
}
],
// Parameters specified for ad-hoc or one-time runtime. This does not include parameters defined at the job level.
"parameters": [
{
"name": "level",
"type": "STRING", // see Enumerations above for valid values
"values": [ "WARN", "ERROR" ]
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"values": [ "60" ] // values is always a list for consistency
}
]
}
}
</pre>

==DELETE a future scheduled runtime ==

''Since Obsidian 4.7.0''

'''<code>DELETE http(s)://localhost/rest/jobs/{jobId}/runtimes</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.OneTimeDeletionResult</code>

Allows for deletion of a future scheduled ad hoc job run.

'''Note:''' When more than on runtime is scheduled for the given time, this function will remove gaps, that is ensure the remaining ordinals start at 0 and increment without skipping any values. For example, if you have 3 instances scheduled (ordinals 0, 1 & 2) and request ordinal 0 be deleted, the remaining two ordinals (1 & 2) will be renumbered to 0 & 1.

'''Sample Request'''
<pre>
{
"scheduledTime": "2021-02-01T19:00:00-0800",
// Optional if only one instance scheduled at the specified time.
"runtimeOrdinal": 2
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| Y || The scheduled time, when the job was previously requested to be run. Must yet be in the future.
|-
| runtimeOrdinal|| Y/N || The ordinal of future dated runtime. If only one runtime is scheduled for the given date, the value can be omitted or should be 0. If more than one instance is scheduled at the given time, the actual ordinal must be specified.
|}

'''Sample Response (with inline comments) '''
<pre>
{
"jobId": 2,
"jobRuntimeId": 36389,
"scheduledTime": "2021-02-01T19:00:00-0800"
}
</pre>

==POST a resubmission request for a failed job runtime==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/resubmissions</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResubmissionResult</code>

Allows for resubmission of a failed job runtime.

'''Sample Response '''
<pre>
{
"resubmission": {
"revision": 0,
"jobId": 35,
"resubmission": true,
"runtimeOrdinal": 0,
"scheduledTime": "2013-01-06T16:49:00-0800",
"status": "READY",
"jobRuntimeId": 2
}
}
</pre>

==POST an interruption request to kill a running job ==
'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/interrupts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobInterruptResult</code>

Allows for interruption of a currently running job runtime. This request can only be made once successfully.

An interruption request will result in the job being terminated, as long as it does not terminate naturally very soon after the request is made, and it is capable of shutting down. Not all jobs can be terminated. See [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] for full details.

'''Sample Response '''
<pre>
{
"interruption": {
"requester": "apiUserName",
"requestTime": "2013-01-06T16:49:00-0800"
}
}
</pre>

== POST async results ==

'''<code>POST http(s)://localhost/rest/job_runtimes/{jobRuntimeId}/async_results</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.RuntimeResult</code>

''Available as of version 4.5.0.''

Used to indicate the final status of an Async job. This request can only be made once successfully. See [[Implementing_Jobs#Async_Jobs | Async Job]] for full details.

'''Sample Request '''
<pre>
{
"asyncJobRuntimeStatus": "FAILED",
"resultTime": "2018-03-09T22:04:08-0500",
"jobResults": {
"Job Failure Description": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized."
},
"resultException": {"detailMessage":"Lock Not Acquired","stackTrace":[{"declaringClass":"com.carfey.finance.OptimizeDatabase","methodName":"optimize","fileName":"OptimizeDatabase.java","lineNumber":132},{"declaringClass":"com.carfey.ops.job.OptimizeDatabase","methodName":"acquireLocks","fileName":"OptimizeDatabase.java","lineNumber":445}],"suppressedExceptions":[]}
}
</pre>

'''Sample Response '''
<pre>
{
"runtime": {
"runningHost": "obsidian-production",
"runtimeOrdinal": 0,
"output": [
{
"name": "Job Failure Description",
"value": "Could not acquire locks on all resources. Tables [reference_object,reference_entity] were not optimized.",
"valueType": "java.lang.String",
"jobRuntimeResultId": 551
}
],
"pickupTime": "2018-03-09T07:45:30-0500",
"adHoc": false,
"heartbeatTime": "2018-03-09T07:46:59-0500",
"lastUpdatedBy": "REST: webServiceCallback",
"scheduledTime": "2018-03-09T07:45:00-0500",
"revision": 603,
"resubmission": false,
"job": {
"hostPreference": false,
"autoInterrupt": false,
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"autoRetryCount": 0,
"jobClass": "com.carfey.ops.job.WebServiceJob",
"nickname": "Finance DB Optimization Service",
"lastUpdatedBy": "devops",
"activeSchedule": {
"schedule": "@daily",
"lastUpdatedBy": "devops",
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T23:57:37-0500",
"endDate": "2999-12-31T23:59:00-0500",
"createdBy": "devops",
"jobScheduleId": 152,
"effectiveDate": "2018-03-08T23:58:00-0500",
"status": "ENABLED"
},
"interruptable": false,
"autoRetryInterval": 0,
"revision": 201,
"jobId": 1,
"lastUpdatedDate": "2018-03-08T23:57:37-0500",
"createdDate": "2018-03-08T14:47:33-0500",
"createdBy": "devops",
"autoRetryIntervalExponent": false,
"chainAll": false
},
"parameters": [],
"status": "FAILED",
"chainTargets": [],
"error": {
"exceptionClass": "java.lang.Exception",
"detail": "java.lang.Exception: Lock Not Acquired\r\n\tat com.carfey.finance.OptimizeDatabase.optimize(OptimizeDatabase.java:132)\r\n\tat com.carfey.ops.job.OptimizeDatabase.acquireLocks(OptimizeDatabase.java:445)\r\n",
"message": "Lock Not Acquired"
},
"jobRuntimeId": 756,
"lastUpdatedDate": "2018-03-09T21:50:57-0500",
"createdDate": "2018-03-09T07:44:01-0500",
"createdBy": "JobQueuer",
"endTime": "2018-03-09T22:04:08-0500"
}
}
</pre>

==GET a list of the latest scheduled runtime by job (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/latest[?startKey=12345&host=host1&quantity=100&sort=asc]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.history.JobDashboardListing</code>

''Available as of version 4.10.2.''

Returns a list of the latest job runtimes by job(i.e. history), optionally filtered by query string parameters. Ordering is guaranteed to be in order of scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the search to the selected jobs. Supports multiple values. ''Do not combine with nickname.''
|-
| nickname || N || If specified, only jobs matching the supplied nickname are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs containing the word "order", use "%order%". Supports multiple values. ''Do not combine with jobId.''
|-
| host || N || If specified, only the latest job runtimes that are assigned to the specified host(s) are included. Supports multiple values.
|-
| folder || N || If specified, only job runtimes with jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A value of either "asc" or "desc", which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey" : "2013-01-06T16:05:00-0800 634",
"start": "2013-10-31T23:59:00-0800",
"end": "2013-11-01T23:59:00-0800",
"runtimes": [
{
"runtimeOrdinal": 0,
"heartbeatTime": "2013-01-06T16:05:00-0800",
"jobRuntimeId": 8,
"adHoc": false,
"pickupTime": "2013-01-06T16:04:00-0800",
// present when this job was resubmitted from another job runtime
"resubmissionSource": {
"jobRuntimeId": 10,
"status": "READY",
"scheduledTime": "2013-01-06T16:06:00-0800"
},
"endTime": "2013-01-06T16:05:00-0800",
"revision": 1,
"resubmission": false,
"scheduledTime": "2013-01-06T16:04:00-0800",
"autoRetryCount": 2, // present if this job was auto-retried from a failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"status": "FAILED",
"error": { // present if the job fails
"message": "arg was null",
"detail": "stack trace..."
},
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 43,
"nickname": "jobThatChainsOthers",
"interruptable": false, // indicates if job can be interrupted
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted
"interruption" : {
"requester": "userName",
"requestTime": "2013-01-06T16:04:54-0800",
"interruptTime":"2013-01-06T16:04:56-0800" // this time will be set if successfully interrupted (otherwise not present)
},
// contains a list of job runtimes that were chained from this job runtime
"chainTargets": [
{
"trigger": true,
"detail": null, // if trigger is false, this will contains details of why it didn't trigger
"jobRuntimeId": 9,
"job": {
"jobId": 44,
"nickname": "jobThatGetsChained"
},
"scheduledTime": "2013-01-06T16:05:00-0800"
}
],
"executionType": "Resubmission" // when present, indicates it executed as a "Resubmission", "Chained", or "Ad Hoc" job
},
{
"runtimeOrdinal": 0,
"jobRuntimeId": 9,
"adHoc": false,
"revision": 0,
"resubmission": false,
"scheduledTime": "2013-01-06T16:05:00-0800",
"status": "READY",
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 44,
"nickname": "jobThatGetsChained",
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"revision" : 0,
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"scheduleDescription": "On the hour", (as of 5.2.0)
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800"
},
"jobClass": "someclass2"
},
// when present, this includes this runtime was chained as a result of another job runtime
"chainSource": {
"trigger": true,
"detail": "chained it",
"jobRuntimeId": 8,
"job": {
"jobId": 43,
"nickname": "jobThatChainsOthers"
},
"scheduledTime": "2013-01-06T16:04:00-0800"
},
"chainTargets": [ ],
"executionType": "Chained"
}
]
}
</pre>

= Runtime Preview Endpoints =

==GET a list of runtime previews (supports multiple jobs)==
'''<code>GET http(s)://localhost/rest/job_runtimes/previews[?jobId=1&jobId=2&start=1356987599000&end=1357510546000]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

Returns a preview of runtimes, optionally filtered based on the supplied query string parameters. This is useful to see when jobs will run during a given time period. Note that these are an estimate of runtimes and cannot account for overlapped jobs, schedule changes or other issues that may result in altered execution times. Results are ordered by scheduled time ascending.

'''Note:''' The capped field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). If you are hitting this condition, try limiting your date range or other parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobId || N || Restricts the preview to the selected jobs. Supports multiple values.
|-
| start || N || Start date for the runtimes to preview (inclusive). Defaults to the current minute.
|-
| end || N || End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.
|}

'''Sample Response'''
<pre>
{
"capped": false,
"start": "2013-10-31T23:59:00-0800", // the inclusive search from date
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date
"runtimes": [
{
"jobId": 36,
"nickname": "jobOne",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:31:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
},
{
"jobId": 37,
"nickname": "jobTwo",
"schedule": "* * * * *",
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"scheduledTime": "2013-01-06T15:30:00-0800",
"scheduleEffectiveDate": "2013-01-06T13:50:00-0800",
"scheduleEndDate": "2999-12-31T23:59:00-0800"
}
]
}
</pre>

==GET a list of runtime previews for an existing job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/runtimes/previews</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.RuntimePreviewListing</code>

This endpoint is equivalent the other runtime preview endpoint (see preceding item) with a URL like the following:
<code>GET http(s)://localhost/rest/job_runtimes/previews?jobId={jobId}</code>

Other than the <code>jobId</code>, all other query string parameters from the multi-job endpoint are supported.

= Job Chain Endpoints =

==GET a list of job chains==
'''<code>GET http(s)://localhost/rest/chains[?active=true&sourceJobId=123&targetJobId=456]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChainListing</code>

Returns a list of configured job chains, optionally filtered by query string parameters.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Limits results to those matching the active flag (true/false).
|-
| sourceJobId || N || Limits results to those matching the supplied source job ID.
|-
| targetJobId || N || Limits results to those matching the supplied target job ID.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobChains": [
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED","CONDITIONAL"],
"resultConditions": [
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName":"fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
},
{
"jobChainId": 2,
"active": false,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Customer Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.CustomerExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
},
"triggerStates": ["COMPLETED"],
"resultConditions": [] // only populated when CONDITIONAL state is used
}
]
}
</pre>

==GET details of an existing job chain==
'''<code>GET http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Returns details of a configured job chain, or a 404 if not found. Contains the same set of fields as the job chain listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"jobChainId": 1,
"schedule": "* * * * *", // if specified
"scheduleDescription": "Every minute every day", (as of 5.2.0)
"active": true,
"sourceJob": {
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Order Export Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.example.OrderExportJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 2
},
"target": {
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
},
"triggerStates": ["FAILED", "CONDITIONAL"],
"resultConditions": [ // only populated when CONDITIONAL state is used
{
"variableName": "exportFile",
"operator": "EXISTS",
"values": [] // empty list when values do not apply
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values": ["0"] // list with one element when multiples aren't applicable
},
{
"variableName": "status",
"operator": "IN",
"values": ["EXPORTED", "ZIPPED"]
}
]
}
</pre>

==POST a new job chain==

'''<code>POST http(s)://localhost/rest/chains</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Creates a new job chain.

'''Sample Request'''
<pre>
{
"sourceJobId": 12,
"targetJobId": 54,
"schedule": "* * * * *", //optional
"active": true,
"triggerStates": ["CONDITIONAL", "FAILED"],
"resultConditions": [ // only supplied when CONDITIONAL state is supplied
{
"variableName": "exportFile",
"operator":"EXISTS" // no "values" field required for EXISTS or NOT_EXISTS
},
{
"variableName": "fileSize",
"operator": "GREATER_THAN",
"values":["0"] // in this case, only one value allowed
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| sourceJobId || Y || ID of the source job.
|-
| targetJobId || Y || ID of the target job to chain
|-
| schedule || N || Optional schedule that constrains when the job chain triggers.
|-
| active || Y || Flag to indicate whether the chain is active or not.
|-
| triggerStates || Y || One or more job chain states as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.
|-
| resultConditions || Y/N || Conditions based on job results that apply to the <code>CONDITIONAL</code> trigger state. Must be supplied only when that state is used, in which case at least one condition must be supplied. Result conditions consist of a <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobChainConditionOperator</code>.
|}

Responses have the same format as GET.

==PUT updates to an existing job chain==

'''<code>PUT http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.JobChainUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Updates an existing job chain. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing job chain==

'''<code>DELETE http(s)://localhost/rest/chains/{jobChainId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobChain</code>

Deletes a job chain. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the job chain before the delete.

= Job Conflict Endpoints =

==GET a list of job conflicts ==
'''<code>GET http(s)://localhost/rest/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.ConflictListing</code>

Lists the configured job conflicts. Non-conflicted jobs are also included in the return value.

Conflicting jobs are returned in priority order within the same list. Multiple conflicting job sets can be returned in the <code>conflictJobs</code> field.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
[
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"folder": "Production/Test", // as of 4.1.0
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set A - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
}
],
[
{
"jobId": 53,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 1",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 2
},
{
"jobId": 54,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 2",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
},
{
"jobId": 55,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Archive Conflict Set B - 3",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
}
],
],
"nonConflictJobs": [
{
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Non-Conflicted Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
}
]
}
</pre>

==PUT updates to job conflicts ==

'''<code>PUT http(s)://localhost/rest/conflicts</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.job.ConflictUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobDetail</code>

Replaces the current job conflict configuration with the supplied configuration.

'''Sample Request'''
<pre>
{

// Note that if Job 5 and Job 2 are scheduled for the same minute, Job 5 will run first as it is selected as the highest priority job from the first conflict set.
// When priority is significant and varies across different sets, ensure your conflict sets are in the desired order.
"conflicts": [
[1, 2, 3, 5], // Job 1 has highest priority
[2, 5, 4] // Job 2 also conflicts with 4 & 5.
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| conflicts || N || A list of lists containing job IDs. Each inner list contains jobs that conflict with each other, in order of execution precedence. Jobs that do not conflict with any other jobs are simply omitted from this list. A job can exist in multiple conflict sets, but should only occur in a particular set once. To remove all job conflicts, an empty list can be supplied for this field.

When selecting available non-conflicted jobs to run, Obsidian inspects the conflict sets in the order provided when they are saved, and selects the highest priority available job before moving onto the next conflict set. When priority is significant and varies across different sets, ensure your conflict sets are in the desired order.
|}

Responses have the same format as GET.

==GET a list of conflicts for a specific job==
'''<code>GET http(s)://localhost/rest/jobs/{jobId}/conflicts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.job.JobConflictListing</code>

Lists all jobs that conflict with the requested job.

Conflicting jobs are returned in priority order, including the job for which this request was made, in order that its priority within the set can be determined. Note that if the job has no conflicts, the returned conflicting jobs list will be empty, and will not contain the requested job.

'''Sample Response (with inline comments)'''
<pre>
{
"conflictJobs": [
{
"jobId": 51,
"recoveryType": "LAST",
"pickupBufferMinutes": 2,
"nickname": "Conflict A",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 2
},
{
"jobId": 52,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Conflict B",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
},
{
"jobId": 56, // this is the requested job
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
}
],
"job": {
"jobId": 56,
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"nickname": "Requested Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.FileArchiveJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"minExecutionDuration" : "1s", // only present when defined on job
"maxExecutionDuration" : "10m" // only present when defined on job
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded
"chainAll": false,
"revision": 5
}
}
</pre>

= Scheduling Hosts Endpoints =

==GET a list of known scheduling hosts==
'''<code>GET http(s)://localhost/rest/hosts</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostListing</code>

Returns a list of known hosts. These are either running or recently shut down abnormally. Hosts that shut down normally are unregistered on shutdown. Note that returned IDs are transient and may change after startup or shutdown or a node. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"hosts": [
{
"id": 32,
"name": "production1",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": true
},
{
"id": 33,
"name": "production2",
"heartbeatTime": "2013-01-05T21:15:59-0800",
"enabled": false
}
]
}
</pre>

==GET details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Returns the requested host, or a 404 if not found.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==GET health details on an existing scheduling host==
''As of Obsidian 6.3.0''

<code>GET http(s)://localhost/rest/hosts/{id}/health</code>

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/health</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint response is to be parsed to evaluate health as it will include full health details with 200 response code if all is well, and a 400 if any part of system is unhealthy including license verification, job queuer and/or job spawner.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 243,
"name": "obsidian.production",
"heartbeatTime": "2025-07-17T20:28:34Z",
"licenceLeaseExpiryUtc": "2025-07-18 01:27:14",
"enabled": true,
"licenceStatus": "internet_node_verified",
"jobQueuerStatus": "healthy",//or laggy,delayed,unresponsive
"jobQueuerUpdateTimeUtc": "2025-07-17 20:28:28",
"jobSpawnerStatus": "healthy"//or laggy,delayed,unresponsive
"jobSpawnerUpdateTimeUtc": "2025-07-17 20:28:20",
"createdDate": "2025-07-17T19:27:13Z",
"createdBy": "SchedulerStarter.startUp",
"lastUpdatedBy": "SchedulerStarter.designator",
"lastUpdatedDate": "2025-07-17T20:28:34Z",
}
}
</pre>

==GET licence details on an existing scheduling host==
'''<code>GET http(s)://localhost/rest/hosts/{id}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/licence_health</code>'''        ''Prior to 4.5'': '''<code>GET http(s)://localhost/rest/hosts/licenceHealthCheck/names/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

The intended use of this endpoint is as a health check. This endpoint is identical to the [[REST_Endpoints#GET_details_on_an_existing_scheduling_host |GET details on an existing scheduling host]] above, with the exception that it will return a 400 if the licence has expired or is in some way invalid.

Returns the requested host with licence status, or a 404 if not found, or a 400 if the licence is invalid or its lease has expired.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint. Heartbeat time indicates when the server last performed the heartbeat health check against the database.

'''Sample Response'''
<pre>
{
"host": {
"id": 33,
"name": "production1",
"heartbeatTime": "2013-01-05T21:18:18-0800",
"licenceLeaseExpiryUtc": "2017-06-15 01:36:06",
"enabled": true,
"licenceStatus": "internet_node_verified",
"licenceLeaseExpiryUtc": "2017-06-15 02:15:42"
}
}
</pre>

==PUT updates to an existing scheduling host==
'''<code>PUT http(s)://localhost/rest/hosts/{id}</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.HostUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.HostDetail</code>

Updates the enabled status of the requested host, or a 404 if not found. This endpoint is used to enable or disable scheduling nodes.

'''Note:''' The name field corresponds to the host name, as described [[Getting_Started#Setting_Host_Names|here]]. Explicit host names should be set if you intend to rely known host names in this endpoint.

'''Sample Request'''
<pre>
{
"enabled": false
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| enabled || Y || Should this host should be enabled?
|}

Responses have the same format as GET.

= Event Hooks Endpoints =
''As of Obsidian 5.4.0''

==GET event hooks==
'''<code>GET http(s)://localhost/rest/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks across the cluster.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
},
{
"host": "prod-obsidian-HL1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T18:08:11-0400",
"heartbeat": "2024-06-01T19:01:37-0400"
}
]
}
]
}
</pre>

==GET event hooks on host==

'''<code>GET http(s)://localhost/rest/hosts/{id}/event_hooks</code>'''

Alternate (by host name): '''<code>GET http(s)://localhost/rest/hosts/names/{name}/event_hooks</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Returns all event hooks for the given host.

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "prod-obsidian-RG1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "INACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"markedInactiveAt": "2024-06-01T16:52:09-0400" --if applicable
}
]
}
]
}
</pre>

==POST event hook pause or resume ==
''As of Obsidian 5.5.0''

'''<code>POST http(s)://localhost/rest/event_hooks</code>'''

Alternate (by host id): POST http(s)://localhost/rest/hosts/{id}/event_hooks

Alternate (by host name): POST http(s)://localhost/rest/hosts/names/{name}/event_hooks

'''Request bean class:''' <code>com.carfey.ops.api.bean.host.UpdateEventHookRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.host.EventHookListing</code>

Requests a specific event hook on a specific host to either Pause or Resume

'''Sample Request'''

<pre>
{
"hostName": "obsidian-prod-1",//only used when using non host-specific event_hooks endpoint
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"eventHookName": "SlackEventHook"
"eventHookAction": "PAUSE"
}
</pre>

'''Sample Response'''
<pre>
{
"hostEventHooks": [
{
"host": "obsidian-prod-1",
"eventHooks": [
{
"eventHook": "com.carfey.ops.event.dispatch.SlackEventHook",
"name": "SlackEventHook",
"status": "ACTIVE",
"registrationTime": "2024-06-01T15:52:07-0400",
"heartbeat": "2024-06-01T16:52:09-0400",
"requestedStatus" : "PAUSE",
"requestedBy" : "carey-ops"
}
]
}
]
}
</pre>

= Custom Calendar Endpoints =

The following endpoints allow for managing of [[Job_Features#Custom_Calendars|Custom Calendars]].

==GET a list of custom calendars==
'''<code>GET http(s)://localhost/rest/calendars</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarListing</code>

Returns a list of custom calendars.

'''Sample Response'''
<pre>
{
"customCalendars": [
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
},
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2014",
"customCalendarId": 2
}
]
}
</pre>
==GET details on an existing custom calendar==
'''<code>GET http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Returns the requested custom calendar, or a 404 if not found..

'''Sample Response'''
<pre>
{
"revision": 0,
"dates": ["2013-01-01", "2013-02-18", "2013-04-01", "2013-05-20"],
"name": "Corporate Holidays 2013",
"customCalendarId": 1
}
</pre>

==POST a new custom calendar ==
'''<code>POST http(s)://localhost/rest/calendars/</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal1",
"dates": ["2016-10-14" ,"2018-06-14"],
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as GET.

==PUT updates to an existing custom calendar==
'''<code>PUT http(s)://localhost/rest/calendars/{id}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Updates the name and dates of the requested calendar, or a 404 if not found.

'''Sample Request'''
<pre>
{
"name": "Cal2",
"dates": ["2018-06-13","2016-10-13"]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

Responses have the same format as POST.

==DELETE an existing custom calendar==

'''<code>DELETE http(s)://localhost/rest/calendars/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.calendar.CustomCalendar</code>

Deletes a custom calendar. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the calendar before the delete.

= Subscriber Endpoints =

==GET a list of subscribers==
'''<code>GET http(s)://localhost/rest/subscribers</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberListing</code>

Returns a list of configured notification subscribers.

'''Sample Response (with inline comments)'''
<pre>
{
"subscribers": [
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "QUEUE",
"level": "ERROR",
"active": true,
},
{
"category": "JOB",
"level": "ERROR",
"active": true,
"job" : { // only exists when the subscription applies to a specific job
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
}
],
"jobExecutionSubscriptions": [
{
"allJobs": true,
"jobs": [], // always empty when allJobs is true
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": [], // present when CONDITIONAL triggerState is used
"active": false
},
{
"allJobs": false,
"jobs": [
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
},
{
"variableName": "warnings",
"operator": "EXISTS",
"values": []
}
],
"active": true
}
]
},
{
"id": 2,
"emailAddress": "inactive@example.com",
"active": false,
"generalSubscriptions": [],
"jobExecutionSubscriptions": []
}
]
}
</pre>

==GET details of an existing subscriber==
'''<code>GET http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Returns details of an existing subscriber, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"active": true,
"category": "QUEUE",
"level": "ERROR"
}
],
"jobExecutionSubscriptions": [
{
"active": false,
"allJobs": true,
"jobs": [],
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ],
"resultConditions": []
}
]
}
</pre>

==POST a new subscriber==

'''<code>POST http(s)://localhost/rest/subscribers</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Creates a new notification subscriber.

'''Sample Request'''
<pre>
{
"emailAddress": "test@example.com",
"active": true,
"generalSubscriptions": [
{
"category": "JOB",
"level": "ERROR",
"active": true,
"jobId": 123 // optional, and only valid when a job-related category is selected
}
],
"jobExecutionSubscriptions":[
{
"active": false,
"allJobs": true,
"triggerStates": [ "DIED", "FAILED", "RECOVERY" ]
},
{
"active": true,
"jobIds": [ 123 ], // should not be supplied with the allJobs flag which takes precedence
"triggerStates": [ "CONDITIONAL" ],
"resultConditions": [
{
"variableName": "cleanupState",
"operator": "EQUALS",
"values": [ "incomplete" ] // depending on the operator, values may be empty, have 1 value, or multiple.
}
]
}
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| emailAddress|| Y || Valid email address of the subscriber. Must be unique.
|-
| active || N || Whether the subscription is active. Defaults to false.
|-
| generalSubscriptions|| N || Zero or more general subscriptions. Each item contains a required subscription <code>category</code> and <code>level</code> as defined in [[Unified_API#Enumerations|Enumerations]], an optional <code>jobId</code> and an optional <code>active</code> flag which defaults to false.

'''Note:''' Only <code>ERROR</code>, <code>WARNING</code> AND <code>INFO</code> are valid values for <code>level</code>. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values for <code>category</code>.
|-
| jobExecutionSubscriptions || N || Zero or more job execution subscriptions. Each item contains a required <code>triggerStates</code> field containing at least one subscription job status as defined in [[Unified_API#Enumerations|Enumerations]]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.

If the <code>CONDITIONAL</code> state is selected, at least one condition must be supplied in the <code>resultConditions</code> field. Result conditions consist of a <code>variableName</code>, an <code>operator</code> as defined in [[Unified_API#Enumerations|Enumerations]], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list. Values for this field map to bean class <code>com.carfey.ops.api.enums.JobSubscriptionConditionOperator</code>.

In addition, two additional optional fields control which jobs the subscription applies to. <code>jobIds</code> is used to specify specific jobs, while <code>allJobs</code> may be set to true to make it apply to all jobs. If <code>jobIds</code> is supplied and <code>allJobs</code> is set to true, <code>jobIds</code> will be ignored.

Finally, the <code>active</code> flag may be supplied which defaults to true.
|}

Responses have the same format as GET.

==PUT updates to an existing subscriber ==

'''<code>PUT http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.SubscriberUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Updates an existing subscriber. Returns a 404 if not found.

Requests and responses have the same format as POST.

==DELETE an existing subscriber==

'''<code>DELETE http(s)://localhost/rest/subscribers/{subscriberId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Subscriber</code>

Deletes a subscriber. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the subscriber before the delete.

= Templates Endpoints =

These endpoints allow for managing notification templates.

==GET a list of templates==
'''<code>GET http(s)://localhost/rest/templates</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateListing</code>

Returns a list of configured templates.

'''Sample Response (with inline comments)'''
<pre>
{
"templates":[
{
"id": 1,
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true, // indicates if it is the default job template for the category
"jobs": [ // only present for job categories when defaultForJobs is false
{
"recoveryType": "NONE",
"jobId": 1,
"pickupBufferMinutes": 2,
"nickname": "Cleanup Job",
"folder": "Production/Test", // as of 4.1.0
"interruptable": true,
"jobClass": "com.carfey.ops.job.maint.JobHistoryCleanupJob",
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"chainAll": false,
"hostPreference": true,
"revision": 52
}
],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
},
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
]
}
</pre>

==GET details of an existing template==
'''<code>GET http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Returns details of a configured template, or a 404 if not found. Contains the same set of fields as the template listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 2,
"name": "Obsidian Default Other Template",
"active": true,
"category": "LICENCE", // if missing, it is the default generic template
"defaultForJobs": false,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

==POST a new template==

'''<code>POST http(s)://localhost/rest/templates</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Creates a new template.

'''Sample Request'''
<pre>
{
"name": "Cleanup Job Template",
"active": true,
"category": "JOB", // category not required when it is the default template
"defaultForJobs": false, // when true, jobIds are ignored
"jobIds": [ 123, 456 ],
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Obsidian {{hostName}} Body content..."
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name || Y || Unique name of the template.
|-
| active || N || Whether the template is active. Defaults to false.
|-
| category || N || The category for the template as defined in [[Unified_API#Enumerations|Enumerations]], or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values.
|-
| defaultForJobs || N || For job-related categories, setting this to true allows for a template to be used as the default template when one isn't assigned to a particular job. Defaults to false.
|-
| jobIds || N || For job-related categories, specific jobs may be assigned to use this template.
|-
| subjectTemplate || Y || A valid [[Email_Templates|Mustache template]] for the subject.
|-
| bodyTemplate || Y || A valid [[Email_Templates|Mustache template]] for the body.
|}

Responses have the same format as GET.

==PUT updates to an existing template==

'''<code>PUT http(s)://localhost/rest/templates/{templateId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.notification.TemplateUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Requests and responses have the same format as POST.

==DELETE an existing template ==

'''<code>DELETE http(s)://localhost/rest/templates/{templateId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Template</code>

Deletes a template. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the template before the delete.

= Notification Endpoints =

These endpoints allow you to query what notifications were triggered in Obsidian. Note that existence of records does not necessarily indicate the notification was successfully sent or received.

==GET a list of notifications==
'''<code>GET http(s)://localhost/rest/notifications[?category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.NotificationListing</code>

Returns a list of notifications, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| category || N || The category of the notifications as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the notifications defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| start || N || Start date for the notifications to return (inclusive). Defaults to the current minute.
|-
| end || N || Start date for the notifications to return (inclusive). Defaults to a day after the start time. Must be after the start time.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"nextPageStartKey": "123",
"notifications": [
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
},
{
"id": 52,
"log": {
"id": 295,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 145] scheduled for [2015-01-22 16:44:00]."
},
"subscriber": {
"id": 51,
"emailAddress": "test@test.com",
"active": true
}
},
]
}
</pre>

==GET details of an existing notification==
'''<code>GET http(s)://localhost/rest/notifications/{id}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.notification.Notification</code>

Returns detail of an existing notification, which contains the same fields as the listing endpoint. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 51,
"log": {
"id": 292,
"eventTime": "2015-01-22T16:44:00-0800",
"host": "Demo",
"category": "JOB_RUN",
"level": "INFO",
"summary": "Completed job [Job History Cleanup 033] scheduled for [2015-01-22 16:44:00]."
},
"subscriber":{
"id": 51,
"emailAddress": "test@test.com",
"active": true // current active state (not when triggered)
}
}
</pre>

= Log Endpoints =

==GET a list of logs==
'''<code>GET http(s)://localhost/rest/logs[?host=host1&filterText=error&category=QUEUE&level=ERROR&start=1356987599000&end=1357510546000&startKey=123]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.LogListing</code>

Returns a list of event logs, optionally filtered by query string parameters. Results are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the response indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same endpoint with the <code>startKey</code> query string parameter set to the returned <code>nextPageStartKey</code>.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| host || N || If specified, only logs from the specified host name(s) are included. Supports multiple values.
|-
| filterText || N || If specified, only messages containing the supplied filter text are returned. '%' can be used as a wildcard.
|-
| category || N || The category of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| level || N || The logging level of the log as defined in [[Unified_API#Enumerations|Enumerations]]. Supports multiple values.
|-
| start || N || Start date for the logs to return (inclusive). Defaults to the current minute.
|-
| end || N || Start date for the logs to return (inclusive). Defaults to a day after the start time. Must be after the start time.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|}

'''Sample Response'''
<pre>
{
"nextPageStartKey" : "123",
"logs": [
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
},
{
"id": 4,
"eventTime": "2015-01-20T11:54:49-0800",
"host": "Demo",
"category": "LICENCE",
"level": "INFO",
"summary": "Successfully refreshed licence from server https://licence.carfey.com/licence for 120 minutes."
}
]
}
</pre>

==GET details of an existing log==
'''<code>GET http(s)://localhost/rest/logs/{logId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.log.Log</code>

Returns detail of an existing log entry. Returns a 404 if not found.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1619,
"eventTime": "2015-01-21T13:59:43-0800",
"host": "Demo",
"category": "JOB_SPAWNER",
"level": "DEBUG",
"summary": "Spawning [Test Job] scheduled for 2015-01-21 13:59:00"
}
</pre>

= System Parameter Endpoints =

==GET a list of system parameters==
'''<code>GET http(s)://localhost/rest/system_parameters</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterListing</code>

Returns a list of system parameters which can be edited.

'''Sample Response (with inline comments)'''
<pre>
{
"parameters": [
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
},
{
"name": "maxJobThreads",
"description": "This value determines the maximum number of threads that will be spawned for running jobs. Changes to this value require a server restart.",
"type": "INTEGER",
"category": "JOB_SPAWNER",
"value": "1000"
}
]
}
</pre>

==GET details of a system parameter ==
'''<code>GET http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Returns details of a system parameter, or a 404 if not found. Contains the same set of fields as the listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"name": "clientKeyServerUrl",
"description": "Address of the primary key server. If running a proxy, this should be the address of the proxy server.",
"type": "STRING",
"category": "LICENCE",
"value": "https://licence.carfey.com/licence"
}
</pre>

==PUT updates to a system parameter ==

'''<code>PUT http(s)://localhost/rest/system_parameters/{name}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameterUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.SystemParameter</code>

Updates a system parameter's value. Values are accepted as strings, but must be valid for their target type (integer, boolean, etc.). Returns a 404 if not found.

'''Sample Request'''
<pre>
{
"value": "60"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| value || N || The new value for the system parameter, which can be converted into the appropriate target type. Some string values support an empty value.
|}

Responses have the same format as GET.

= User Endpoints =

Note that user endpoints are only available when using Obsidian's native authentication, and do not support LDAP or custom authentication.

==GET a list of users==
'''<code>GET http(s)://localhost/rest/users</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.UserListing</code>

Returns a list of configured users.

'''Sample Response (with inline comments)'''
<pre>
{
"users": [
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
},
{
"id": 2
"userName": "reader",
"active": false,
"roles": [] // no roles means read-only
}
]
}
</pre>

==GET details of an existing user==
'''<code>GET http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Returns details of a configured user, or a 404 if not found. Contains the same set of fields as the user listing endpoint.

'''Sample Response (with inline comments)'''
<pre>
{
"id": 1,
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"]
}
</pre>

==POST a new user==

'''<code>POST http(s)://localhost/rest/users</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserCreationRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Creates a new user.

'''Sample Request'''
<pre>
{
"userName": "admin",
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| userName || Y || Unique user name used to log in.
|-
| active || N || Whether the user is enabled. Defaults to false.
|-
| roles || N || Zero or more roles as defined in [[Unified_API#Enumerations|Enumerations]]. Supplying no roles indicates it is a normal read-only user.
|-
| password || Y || A password at least 6 characters long.
|}

Responses have the same format as GET.

==PUT updates to an existing user==

'''<code>PUT http(s)://localhost/rest/users/{userId}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.UserUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Updates an existing user. Returns a 404 if not found. Semantics similar to a PATCH request are used, so that only supplied fields are updated. User names cannot be updated.

'''Sample Request'''
<pre>
{
"active": true,
"roles": ["ADMIN","API"],
"password": "changeme"
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Whether the user is enabled. Defaults to the existing active state.
|-
| roles || N || Zero or more roles as defined in [[Unified_API#Enumerations|Enumerations]]. Supplying an empty list of roles indicates it is a normal read-only user. Supplying null indicates that the roles should not be updated.
|-
| password || N || A password at least 6 characters long. If not supplied, the password is not changed.
|}

Responses have the same format as POST.

==DELETE an existing user ==

'''<code>DELETE http(s)://localhost/rest/users/{userId}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.User</code>

Deletes a user. Returns a 404 if not found.

Responses have the same format as GET, and return the final state of the user before the delete.

==GET a list of known MFA users==

''As of version 5.0.''

'''<code>GET http(s)://localhost/rest/users/mfa</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Returns all known users which may have Multi-Factor Authentication (MFA) resets applied. Exists to facilitate use of the MFA reset endpoint.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

==PUT MFA user resets==

''As of version 5.0.''

'''<code>PUT http(s)://localhost/rest/users/mfa/reset</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.user.ResetMfaRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.user.MfaUserListing</code>

Resets the requested users' Multi-Factor Authentication (MFA) state so that they may perform MFA setup. This is useful when a user does not complete MFA setup within the required time, or when adding a user when not using Obsidian's native authentication.

'''Sample Request'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

'''Request Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| userNames || Y || The list of user names to reset. Note that these do not have to correspond to known Obsidian users, since it must support custom authentication methods.
|}

Responses echo the users in the request.

'''Sample Response'''
<pre>
{
"userNames": [
"admin",
"john.doe",
"operator"
]
}
</pre>

= System Restore Endpoints =

These endpoinds can be used to import and export Obsidian's configuration, including job-related configuration, subscription-related configuration, users and system parameters. See [[Initializing_and_Restoring|Initializing and Restoring]] for more details.

==GET a system restore configuration ==
'''<code>GET http(s)://localhost/rest/system_restores[?excludeItem=users&jobNickname=jobname]</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Returns the system's exported configuration. The output from this endpoint can be used with the corresponding [[#PUT_a_system_restore_configuration|PUT endpoint]] directly.

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| excludeItem || N || Allows filtering out of specific groups of system configuration items. Supported values are <code>jobs</code>, <code>chains</code>, <code>conflicts</code>, <code>systemParameters</code>, <code>customCalendars</code>, <code>globalParameters</code>, <code>users</code>, <code>templates</code>, <code>subscribers</code>. Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers). Supports multiple values.
|-
| jobNickname || N || Allows targeting only specific jobs in the jobs export. Filtering out any jobs automatically filters out all conflicts, any chains where these jobs exist and and drops any other references to these jobs (such as in templates and subscribers). Supports multiple values.
|}

'''Sample Response (with inline comments)'''
<pre>
{
"jobs": [
{
"updateSchedule": false, // whether to apply the current schedule and any additional jobSchedules when the job already exists
"updateAttributes": false, // whether job attributes (jobClass, recoveryType, pickupBufferMinutes, etc.) will be updated when the job exists
"jobSchedules": [
{
"state": "DISABLED",
"effectiveDate": "2015-03-20T10:35:00-0700",
"endDate": "2999-12-31T23:59:00-0800"
}
],
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"minExecutionDuration": "2s",
"maxExecutionDuration": "3s",
"nickname": "Log Cleanup",
"folder": "Production/Test", // as of 4.1.0
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [ "Demo-PC" ],
"ordinalParameters": [
"ordinal": 0,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ALL"
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"value": "120"
}
]
],
"chainAll": false,
"hostPreference": true,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "ENABLED",
"schedule": "* * * * *",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2015-03-20T10:34:00-0700"
},
{
"updateSchedule": false,
"updateAttributes": false,
"jobSchedules": [],
"jobClass": "com.carfey.ops.job.script.GroovyJob",
"nickname": "Script Job",
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [],
"ordinalParameters": [
"ordinal": 0,
"parameters": [
{
name": "script",
"type": "STRING",
"value": "sdfds"
}
]
],
"chainAll": false,
"hostPreference": false,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "DISABLED",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2999-12-31T23:59:00-0800"
}
],
"users": [
{
"update": false, // when false, the user attributes will not be updated if the user already exists
"userName": "admin",
"active": true,
"roles": [
"API",
"ADMIN",
"WRITE"
],
"password": "changeme"
}
],
"chains": {
"replaceAll": false, // if set to false or omitted, chains will only be created if none exist - existing chains are not updated.
"items": [
{
"sourceJobNickname": "Script Job",
"targetJobNickname": "Log Cleanup",
"active": true,
"triggerStates": [
"FAILED",
"CONDITIONAL"
],
"resultConditions": [
{
"variableName": "dfdsfds",
"operator": "EQUALS",
"values": [
"sdfs"
]
}
]
}
]
},
"conflicts": [
[
"Script Job",
"Log Cleanup"
]
],
"customCalendars": [
{
"name": "Sample Calendar",
"dates": [
"2011-01-01"
]
}
],
"systemParameters": [
{
"name": "adHocJobsRespectFixedHostsRestrictions",
"description": "This value determines whether the Fixed Hosts restriction assigned to a Job is respected for Ad Hoc jobs.",
"category": "JOB",
"value": "true"
}
],
"templates": [
{
"jobNicknames": [],
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Body Template"
}
],
"subscribers": [
{
"generalSubscriptions": [
{
"jobNickname": "Log Cleanup",
"category": "JOB",
"level": "ERROR",
"active": true
}
],
"jobExecutionSubscriptions": [
{
"jobNicknames": [],
"allJobs": true,
"triggerStates": [
"CONDITIONAL",
"DIED",
"FAILED",
"RECOVERY"
],
"resultConditions": [
{
"variableName": "someVar",
"operator": "EQUALS",
"values": [
"someValue"
]
}
],
"active": true
}
],
"emailAddress": "test@example.com",
"active": true
}
]
}
</pre>

==PUT a system restore configuration==
'''<code>PUT http(s)://localhost/rest/system_restores</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration</code>

Imports the requested system restore configuration, updating, creating and replacing data based on the input.

'''Usage Note:''' Entities within the export are generally identified by their names. For details on required fields, formats and update logic, refer to the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,java.lang.String) Javadoc] and the [[Initializing_and_Restoring|Initializing and Restoring]] page. The Embedded API and REST API both use the same format and processing rules.

Requests are in the same format as the [[#GET_a_system_restore_configuration|GET endpoint's]] response.

Responses are in the same format as the GET and return the full Obsidian system restore configuration following the changes (not necessarily the same as the input).

= Schedule Alias Endpoints =

''As of version 5.0.''

These endpoints can be used to manage schedule aliases. See [[Admin_Schedule_Aliases|Schedule Aliases]] for more details.

==GET a list of schedule aliases ==
'''<code>GET http(s)://localhost/rest/schedule_aliases</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasListing</code>

Returns the system's schedule aliases.

'''Sample Response'''
<pre>
{
"scheduleAliases": [
{
"alias": "@every4Minutes",
"schedule": "0/4 * * * *",
"scheduleDescription": "Every 4th minute every day" (as of Obsidian 5.2.0)
},
{
"alias": "@dailyAtNoon",
"schedule": "12 * * * *",
"scheduleDescription": "At 12:00PM every day" (as of Obsidian 5.2.0)
},
{
"alias": "@threeTimesWeekly",
"schedule": "0 0 * 1,3,5 *",
"scheduleDescription": "At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
},
{
"alias": "@combinedExample",
"schedule": "@dailyAtNoon;@threeTimesWeekly",
"scheduleDescription": "At 12:00PM every day - AND - At midnight on Mondays, Wednesdays, Fridays" (as of Obsidian 5.2.0)
}
]
}
</pre>

==PUT a schedule alias==
'''<code>PUT http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Request bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAliasUpdateRequest</code>

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Request'''
<pre>
{
"schedule": "5 11 * * 2"
}
</pre>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==GET a schedule alias==
'''<code>GET http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2",
"schedule": "At 11:05AM on Tuesdays" (as of Obsidian 5.2.0)
}
</pre>

==DELETE a schedule alias==
'''<code>DELETE http(s)://localhost/rest/schedule_aliases/{alias}</code>'''

'''Response bean class:''' <code>com.carfey.ops.api.bean.schedule.ScheduleAlias</code>

'''Sample Response'''
<pre>
{ "alias": "@1105AMTuesdays",
"schedule": "5 11 * * 2"
}
</pre>

= Job Execution Statistics Endpoints =

''As of version 6.4.0.''

To retrieve job execution statistics. Assumes [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] has run to completion at least once.

== GET a list of job execution statistics ==
'''<code>GET http(s)://localhost/rest/stats[?jobNickname=jobname&job_id=1&duration=six_months&unit=seconds&status=completed&acrossHosts=false&host=prod.obsidian-a1&host=prod.obsidian-a2]</code>'''

'''Query String Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobNickname || N || Allows targeting only specific jobs by nickname in the stats export. Supports multiple values.
|-
| jobId || N || Allows targeting only specific jobs by id in the stats export. Supports multiple values.
|-
| duration || N || Allows targeting stats durations. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| unit || N || Allows targeting stats units. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| status || N || Allows targeting stats terminal statuses. See [[Unified_API#Enumerations|Enumerations]] for valid values - case-insensitive. Supports multiple values.
|-
| host || N || Allows targeting stats from specific hosts. Supports multiple values.
|-
| acrossHosts || N || Allows selecting stats collected across all hosts. Boolean.
|}

'''Response bean class:''' <code>com.carfey.ops.api.bean.stats.StatsListing</code>

Returns the cluster's job execution statistics.

'''Sample Response'''
<pre>
{
"stats": [
{
"statsId": 733,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a1",
"status": "COMPLETED",
"unit": "SECONDS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 97,
"average": 7701.463918,
"median": 6965.0,
"mode": 62,
"min": 62.0,
"max": 17925.0,
"variance": 23055960.248698,
"standardDeviation": 4801.66
},
{
"statsId": 545,
"jobId": 55,
"nickname": "Cache Reloader",
"host": "prod.obsidian-a2",
"status": "COMPLETED",
"unit": "HOURS",
"duration": "YEAR",
"start": "2024-12-14",
"end": "2025-12-14",
"count": 114,
"average": 2.238684,
"median": 1.932778,
"mode": 1,
"min": 0.015,
"max": 4.989444,
"variance": 2.18319,
"standardDeviation": 1.47756
}
],
"hosts": [
"prod.obsidian-a1",
"prod.obsidian-a2"
]
}
</pre>

REST API

2026-07-31T14:49:57Z

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

Obsidian includes a REST API to ease integration into other applications and software environments, regardless of the technology used. A complete range of job, scheduling and host management features are exposed via the API. It is exposed by both the standalone and bundled versions of the admin web application.

This page contains general information on the REST API, including data formats, authentication and common API behaviour.

For full details specific API endpoints, see [[REST Endpoints|Endpoints]].

'''Note:''' Obsidian also has an [[Embedded API]], which can be used when no web application is available or you'd simply rather not use REST.

=Overview=

The Obsidian REST API allows other applications a way to access Obsidian data, schedule jobs, and control Obsidian in a variety of ways. It can be integrated with any programming language since it uses standards like HTTP and JSON.

The REST API gives users the power to do things like automate migration scripts, trigger jobs based on events in external applications, and expose pieces of the Obsidian API in their own custom user interfaces.

==Endpoints==
The API is exposed under the path <code>/rest</code>.

For example, if your web application is deployed at <code>localhost</code>, the jobs endpoint is accessible at <code><nowiki>http://localhost/rest/jobs</nowiki></code>.

For full details on the API endpoints, see [[REST Endpoints|Endpoints]].

==Data Format==
[http://www.json.org JSON] is used for all endpoints. This includes response data and PUT/POST data.

The returned <code>Content-Type</code> will always be <code>application/json</code> using the UTF-8 encoding.

All PUTs and POSTs must include <code>Content-Type</code> header set to <code>application/json</code> with a valid JSON body. UTF-8 should be used as the content encoding for maximum compatibility.

==Authentication & Authorization==
The REST API is secured by limiting access to users configured in [[Admin User Management|User Management]] with the API Access role.

Valid [http://en.wikipedia.org/wiki/Basic_access_authentication basic access authentication] must be supplied with every request. Valid API users are authorized to access any REST endpoint.

=== Disabling Authentication ===
In some rare cases, users may wish to disable the need for authentication credentials in REST calls.

This can be done by changing the [[Admin Scheduler Settings|scheduler setting]] <code>allowAnonymousRestCalls</code> under the ''Dispatch'' category to <code>true</code>. When this is done, no Authentication header needs to be provided.

'''Note:''' This is not recommended on networks exposed to the Internet, or other non-trusted environments.

=Common API Behaviour=
* For GET and DELETE, parameterization is done via request parameters, and not JSON body. Supported parameters are simple and primarily provide search options and simple flags.
* All non-200 responses will always return a JSON response in the following format. One or more errors may be returned in the errors property.
<pre>
{
"errors":["nickname is required.", "jobClass is required."]
}
</pre>
<pre>
{
"errors":["Resource not found"]
}
</pre>
* If a request does not pass validation or if an action cannot be performed, a 400 status code will be returned. This may happen if required fields are omitted, in an invalid format, or an action cannot be performed in the current context.
* If a JSON payload contains unexpected fields, a 400 status code will be returned.
* If a resource with the specified identifier could not be found, a 404 status code will be returned. For example, this would occur if you attempt to load a job with an ID that does not exist.
* If an incorrect method is used on an endpoint (e.g. DELETE on a job runtime), a 405 status code will be returned.
* If no valid basic authentication is provided, a 401 status code will be returned.
* If no endpoint exists at the requested path, a 404 status code will be returned.
* If the Content-Type header of a PUT or POST request is not application/json, a 415 status code will be returned.
* If the server encounters an unexpected error, a 500 status code will be returned.

== Date Formats ==
Since scheduling is inherently linked to time zones and is not fully represented by a UTC time, all times in the API are returned in the following string format. Note the trailing timezone indicator which indicates the UTC offset.
<pre>
yyyy-MM-dd'T'HH:mm:ssZ
</pre>
For example, the last second of 2012 PST is:
<pre>
2012-12-31T23:59:59-0800
</pre>

When a date only is input or output (as with custom calendars), it is always in the following format:
<pre>
2012-12-31
</pre>

=== Date & Time Inputs ===
While datetimes are always output in the same format, datetimes in query strings or in JSON payloads can use either the standard output format shown above, an abbreviated form that contains no timezone offset and assumes server time, or the UTC time represented as milliseconds since the epoch.
For example, the last second of 2012 PST is:
<pre>
2012-12-31T23:59:59-0800
</pre>
Or, interpreted in the server time zone:
<pre>
2012-12-31T23:59:59
</pre>
Or, as milliseconds since the epoch:
<pre>
1356987599000
</pre>

=Common Enumerations=

Enumerations are consistent with the [[Unified_API#Enumerations|Embedded API's enumerations]].

= JSON Bean Classes =

Obsidian comes bundled with simple bean classes in the package <code>com.carfey.ops.api.bean</code> that can be used to serialize JSON requests and deserialize responses into plain old Java objects (POJOs). These bean classes are located in <code>obsidian.jar</code> which is included in your Obsidian zip download within the <code>standalone</code> directory.

These classes are tested with [https://github.com/google/gson Gson] since that is what Obsidian uses internally, but you can integrate it with the JSON library of your choosing. Obsidian uses custom types for dates and datetimes, so see the following section on how to configure JSON serialization correctly.

Each [[REST Endpoints|endpoint]] documents the appropriate bean class to use.

== Serializing & Deserializing Date Types ==

Since the Obsidian REST API uses its own specific date formats to fully represent scheduled times including their time zones, you will have to use custom serializers to properly use the supplied bean classes. Doing this is simple, and we've provided a sample below for [https://github.com/google/gson Gson], plus a generic example to show you how to parse and format dates appropriately, which you can adapt for use in JSON other libraries.

'''GSON Serialization:'''
<pre>

import com.carfey.jdk.lang.Date;
import com.carfey.jdk.lang.DateTime;

import com.carfey.jdk.lang.Date;
import com.carfey.jdk.lang.DateFormat.ParseException;
import com.carfey.jdk.lang.DateTime;
import com.carfey.jdk.text.Json;
import com.google.gson.Gson;
import com.google.gson.GsonBuilder;

public class GsonDemo {
public static void main(String[] args) throws ParseException {

// Set up the custom serializers for date types
GsonBuilder gb = new GsonBuilder();
gb.registerTypeAdapter(Date.class, Json.REST_SERIALIZER);
gb.registerTypeAdapter(DateTime.class, Json.REST_SERIALIZER);
Gson gson = gb.create();

// The Gson instance can now be used with all Obsidian REST bean classes
SampleBean sample = new SampleBean();
String stringValue = gson.toJson(sample);
System.out.println(stringValue);

SampleBean rebuilt = gson.fromJson(stringValue, SampleBean.class);
System.out.println(rebuilt);
}

private static class SampleBean {
private com.carfey.jdk.lang.Date date = new Date();
private com.carfey.jdk.lang.DateTime dateTime = new DateTime();
public Date getDate() {
return date;
}
public void setDate(Date date) {
this.date = date;
}
public DateTime getDateTime() {
return dateTime;
}
public void setDateTime(DateTime dateTime) {
this.dateTime = dateTime;
}
@Override
public String toString() {
return "SampleBean [date=" + date + ", dateTime=" + dateTime + "]";
}

}
}

</pre>
'''Output:'''
<pre>
{"date":"2013-10-30","dateTime":"2013-10-30T22:04:24-0700"}
SampleBean [date=20131030, dateTime=20131030 10:04:24:000 PM -0700]
</pre>

'''Generic Date Parsing and Formatting Example:'''
<pre>

// converting REST date time formats (serialize and deserialize)
com.carfey.jdk.lang.DateFormat dateTimeFormat = new com.carfey.jdk.lang.DateFormat("yyyy-MM-dd'T'HH:mm:ssZ");

com.carfey.jdk.lang.DateTime dateTime = new com.carfey.jdk.lang.DateTime();
String dateTimeString = dateTimeFormat.format(dateTime);
com.carfey.jdk.lang.DateTime asDateTime = dateTimeFormat.parse(dateTimeString);
System.out.println(asDateTime);

com.carfey.jdk.lang.DateFormat dateFormat = new com.carfey.jdk.lang.DateFormat("yyyy-MM-dd");

com.carfey.jdk.lang.Date date = new com.carfey.jdk.lang.Date();
String dateString = dateTimeFormat.format(date);
com.carfey.jdk.lang.Date asDate = dateTimeFormat.parse(dateString).getDate();
System.out.println(asDate);

</pre>

'''Output: '''
<pre>
20131105 06:10:41:000 PM -0800
20131105
</pre>

Obsidian Tables

2026-07-31T14:49:57Z

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

Obsidian needs to create and manage the following tables in its target database. When sharing schemas between Obsidian and other applications, ensure there are no naming conflicts by reviewing this list.

'''Note:''' Since Obsidian does not run jobs within the same connection or transaction as your jobs, there is no real need to run Obsidian within the same database or schema as your own application(s), though you may wish to do so to facilitate maintenance.

Obsidian can be configured to use a [[Advanced_Configuration#Table Prefixes|table prefix]] when creating its tables.

* custom_calendar
* event_log
* event_subscriber
* event_subscription
* global_job_config
* job
* job_chain
* job_chain_mode
* job_chain_mode_condition
* job_configuration
* job_conflict_config
* job_history
* job_history_config
* job_history_chain
* job_history_error
* job_history_interrupt
* job_history_result
* job_running_host
* job_sub_mode_condition
* job_subscription
* job_subscription_job
* job_subscription_mode
* job_state
* notification
* notif_template
* notif_template_entity
* operations_parameter
* role
* semaphore
* sequence_manager
* suite_user
* user_cookie
* user_role

== Oracle Privileges ==

If you are not using the schema owner as your Obsidian database user, the following privileges will need to be granted to your database user:

<pre>
# For each Obsidian table...
GRANT INSERT,SELECT,UPDATE,DELETE ON OBS_JOB TO OBSIDIAN_USER;

# Required for alternate schema usage
GRANT ALTER SESSION TO OBSIDIAN_USER;
GRANT ANALYZE ANY TO OBSIDIAN_USER;
GRANT ANALYZE ANY DICTIONARY TO OBSIDIAN_USER;
</pre>

== MS SQL Server Snapshot Isolation ==

For maximum compatibility and to avoid deadlocks, MS SQL Server should be configured to use [https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/sql/snapshot-isolation-in-sql-server read committed snapshot isolation].

This can be enabled on your database by running the following commands:

<pre>
ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON
</pre>

Licenses & Nodes

2026-07-31T14:49:56Z

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

Each running Obsidian scheduler process requires a valid license. Here are some quick facts:
* When you download Obsidian, it automatically obtains a free license key, which gives you one free license for permanent use. We'd be happy to have you evaluate Obsidian clustering, so just reach out to us and we'll grant you a second instance on the same key for a few months. You can use a single scheduler instance forever at no charge.
* Running the admin web app without scheduler does not require a license when used in conjunction with licensed instances.
* All standard licenses are ''floating'', meaning they are not restricted to particular hardware and can be moved around as needed.
* Running scheduler instances must have access to the Internet to lease and verify the license.
* Every license key has one or more valid licenses associated with it.

= License Verification =
The default Obsidian license requires a a live Internet connection to validate clustered scheduler instances.

Obsidian's license verification is built to handle sporadic outages to Internet connectivity. Customers using paid licenses can generally expect grace periods of over 48 hours during which Internet connectivity is not available. Obsidian will automatically attempt to re-validate your license key on a schedule based on configurable settings which control [[#License Leasing|License Leasing]]

Obsidian also provides a [[Key_Server_Proxy|license proxy]] should you wish to restrict Internet access to a single server. Obsidian instances can then be directed to the deployed license proxy.

Obsidian also supports hardware licenses. These are tied to deployment hardware and are not floating. Contact [[Contact Carfey Software|Carfey Software]] for further details.

Obsidian can also be run under a site license. When Obsidian is run under a site license, no Internet connectivity and verification is required and a specific maximum number of nodes are permitted within the licensed organization based on prior agreement. Contact [[Contact Carfey Software|Carfey Software]] for further details.

=Nodes=
Nodes are individual instances of Obsidian scheduler. Nodes can be running standalone, within the admin web app or embedded in an existing JVM application. Nodes typically are deployed one per host, but Obsidian supports multiple nodes per host. Each running host uses the hostname to designate the node running each scheduled instance of a job. Subsequent instances on the same host will suffix an ordinal to the end of the hostname. Optionally, you can specify a configuration property (see [[Advanced Configuration]]) or provide a System property (see [[Getting_Started#Setting_Host_Names|Getting Started]]) choosing the host designator you wish to use.

No extra work, special configuration or administration is required to add nodes. Simply setup the environment, ensure a node license is available and start it up. The same holds true for shutting down.

Nodes can be gracefully brought down out of the pool, allowing them to complete any in-process work while no longer claiming and processing any subsequently scheduled work. Graceful shutdown in the web embedded scheduler, either in the web admin app or your own web app, requires using the container's shutdown. Starting and stopping a standalone version of the scheduler uses a listener port to support graceful shutdown. See the [[Getting Started]] guide for details.

== License Leasing ==

When an Obsidian instance is validated, a license is locked to the leasing node. Other nodes or instances will not be able to use this license until the lease expires.
After the lease time elapses (configured in [[Admin Scheduler Settings|scheduler settings]] screen, or in the key proxy properties file), it is available for other nodes. In the meantime, if the instance goes down and you attempt to start a node in another location, the license will not be available for lease. If you restart the node in the same location, it will reacquire the same license.

You can customize the leasing settings in the [[Admin Scheduler Settings|scheduler settings]] screen under the ''License'' category. Key settings include ''clientKeyRefreshMinutes'' and ''clientKeyLeaseLengthMultiple'', which are documented on that page. Changing these settings allows you to find the right balance between tolerance for Internet outages, and the ability to deploy a used Obsidian license to a new installation, affecting the length of time for locked licenses to expire.

== Your License Key ==

You can find your license key in [[Admin Scheduler Settings|Scheduler Settings]] as shown below.

Obsidian will automatically acquire your free single node license. You can request a second clustering node for evaluation for up to 1 year. If you are converting your trial backup node license to a paid license or are purchasing additional nodes, you can obtain your license key from the location show below.

[[Image:ClientKey_4.0.png]]

Key Server Proxy

2026-07-31T14:49:56Z

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

Obsidian licensing requires access to Carfey Software's servers to verify license authenticity. To accommodate those who wish to limit Obsidian hosts with access to the internet, we provide a key server proxy that can be deployed in any servlet container.

In your software package, you would have received the key server proxy as <code>obsidianKeyProxy.war</code>. Within this war, under <code>WEB-INF/classes</code> is <code>com.carfey.properties</code>. Note you should not need to edit the master key server url, which is fixed at "https://licence.carfey.com/proxy".

Once the proxy is deployed, to configure use of the key server proxy by the Obsidian scheduler, simply login to Obsidian Web Admin app as an admin user, open [[Admin_Scheduler_Settings|Scheduler Settings]], select the ''Licence'' category and set the address of your deployed key server proxy as the ''clientKeyServerUrl''. Make sure it ends with "/licence", e.g. "https://internal.server/licence".

Then make sure the value for the [[Admin_Scheduler_Settings|scheduler setting]] ''clientKeyServerUrlBackup'' is set to Carfey Software's key license server at https://licence.carfey.com/licence. This will give you failover in case your proxy goes down.

'''Security Note:''' By default, the proxy key server allows non-secure connections. If you wish to force secure connections through HTTPS, you can edit the web.xml in your war and uncomment the <security-constraint> element in the file. This will force all requests to redirect to an encrypted connection. For details on setting up SSL on your servlet container, refer to its documentation.

Job Forking

2026-07-31T14:49:55Z

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

Obsidian can run each job in its own JVM. This allows for a number of possibilities, including support for dynamic changes to your deployed jobs (i.e. hot-swapping of JARs). In theory, you could even specialize classpaths on a per job basis by customizing the provided execution scripts.

JVM job forking is disabled by default. Standalone deployments support forking out-of-the-box, but it is not active until you enable it as defined in [[#Configuring_Job_Forking|Configuring Job Forking]].

'''Note:''' In order to support hot-swapping of JARs that contain compiled jobs, Obsidian expects you to ensure JAR consistency between nodes. If you plan on deploying new jobs or changing the configurability (e.g. supported parameter changes), you will want to deploy these to all Obsidian nodes that have job forking enabled and either restrict these from executing on nodes with forking disabled (see [[Admin_Jobs#Advanced_Options|Fixed Hosts]]) or deploy the changes to these nodes with appropriate restarts of Obsidian.

= How Does Job Forking Work? =
When job forking is enabled, Obsidian will run a shell script (or batch file on Windows) for each job execution to be forked. This script in turn starts a new JVM which invokes an Obsidian class with the appropriate arguments to start the single-job execution. Forking can be [[#Script_Customization|customized]] easily by using alternate scripts from the provided defaults. To support new jobs or configurability changes to existing jobs, [[Implementing_Jobs#Classpath_Scanning|Classpath Scanning]] also runs as a forked process using the same scripts.

'''Forked Jobs and the Obsidian Database'''

Each occurrence of a Forked Job will require a few connections to the database. Make sure you plan accordingly in your connection allocations on the database and sizing for the JNDI datasource, if applicable.

== Interrupt Support ==

Forked jobs can be interrupted. See [[Job_Forking#Configuring_Job_Forking | Configuring Job Forking]] below.

= Configuring Job Forking =

=== Enabling Job Forking - Cluster ===

To use forking, first you must enable a setting (''jvmJobForkingEnabled'') that will apply across the cluster. This is a [[Admin Scheduler Settings|scheduler setting]] found in the ''Job Spawner'' category. You may enable it through the admin web application, the [[Embedded API]], [[REST API]], or Obsidian's [[Initializing and Restoring|initialization & restore]] support.

If you wish to enable interruption of forked jobs that implement the necessary [[Implementing_Jobs#Interruptable_Jobs|Interruptable]] interface, you must also enable the setting ''jvmForkedJobsCanBeInterrupted'' also found in the ''Job Spawner'' category.

[[File:JobForking_4.0.png]]

=== Enabling Job Forking - Node ===
Once you've done that, you'll need to enable it on each desired node. [[Getting_Started#Standalone_Scheduler|Standalone scheduler]] instances are configured to support forking by default. For other nodes types, you will need to set the appropriate [[Advanced_Configuration#Configuration_Details|property value]].

<code>com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true</code>

In a [[Getting_Started#Standalone_Scheduler|standalone scheduler]], job forking will be then be functional on next restart. In other deployments, or if you wish to make additional customizations, additional changes will be required.

=== Script Location ===
Job forking uses a script for each job execution to start up a fresh JVM.

You may wish to specify the forking script location for other deployments, such as [[Getting_Started#Embedded_Scheduler|embedded schedulers]] and [[Getting_Started#Combined_Scheduler_and_Admin_Web_Application |combined scheduler and admin web application]] instances, or for other reasons.

To override the script location, set the appropriate [[Advanced_Configuration#Configuration_Details|property value]] in your properties file:

<code>com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0</code>

Obsidian is bundled with '''<code>obsidianForkedJob.bat</code>''' and '''<code>obsidianForkedJob.sh</code>'''. These are the '''required''' script names.
If you wish to customize these scripts or use your own, you are free to do so, but the script names cannot be changed. Review the notes on the [[#Forked_Obsidian_Job_Runner|forked job runner]] to assist your customization efforts.

=== Classpath Override ===
You may wish to override the default classpath that is used by the forked execution instance. Or for deployment types other than [[Getting_Started#Standalone_Scheduler|standalone schedulers]], you can use this [[Advanced_Configuration#Configuration_Details|property]] to specify the classpath.

<pre>com.carfey.obsidian.forkedJobscriptClasspathOverride=/home/user/workspace/obsidian/bin:/home/user/workspace/obsidian/lib/activation-1.1.jar\
:/home/user/workspace/obsidian/lib/mail-1.4.jar:/home/user/workspace/obsidian/lib/dom4j-1.6.1.jar:/home/user/workspace/obsidian/lib/obsidian.jar\
:/home/user/workspace/obsidian/lib/log4j-1.2.9.jar:/home/user/workspace/obsidian/lib/gson-2.2.2.jar:/home/user/workspace/obsidian/lib/bsh-2.0b4.jar\
:/home/user/workspace/obsidian/lib/groovy-all-2.1.8.jar:/home/user/workspace/obsidian/lib/jython-standalone-2.5.3.jar\
:/home/user/workspace/obsidian/lib/mariadb-java-client-1.1.5.jar
</pre>

The sample demonstrates usage in an embedded Obsidian instance running inside an Eclipse project. The default classpath used in the <code>obsidianForkedJob.(sh|bat)</code> script is built automatically assuming a [[Getting_Started#Standalone_Scheduler|standalone scheduler]] deployment. As such, it uses the jars in the <code>standalone/</code> directory for building the classpath. If you require a custom classpath on a per job basis, modification of the forking script(s) will be required.

=== Database Configuration Parameters ===
If your environment does not have database configuration entries in the properties/yaml file accessible to the forked job (e.g. config is done via System properties and/or programmatically), you will want to enable the following option for forked jobs. When enabled, database configuration will be passed into the scripts instead of relying on locating a properties file with the same information.

<code>com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true</code>

= Script Customization =

If you aren't using a [[Getting_Started#Standalone_Scheduler|standalone scheduler]], or you simply need to customize Job Forking, review the following section for detailed documentation on the scripts used and how they can be customized.

== Script Arguments ==
Obsidian calls the script with the following arguments.
* <code>stack_file</code> Always the first argument. Used by the Scheduler Node to be aware of execution exceptions,
* <code>-argumentsFile</code> Required if you need database parameters or additional execution data such as job nickname, job class or running host.
* <code>-classpathScan</code> Flag indicating the run is a classpath scan request.
* <code>-jobHistoryId</code> Required. Job execution instance identifier.
* <code>-classpathOverride</code> Optionally provided if the <code>com.carfey.obsidian.forkedJobscriptClasspathOverride</code> property is present.

The following arguments can be found in the arguments file that is created for each invocation. Job parameters are not included in classpath scan requests. Database parameters are only included if the <code>com.carfey.obsidian.jvmJobForkingIncludeDbSysParms</code> property is true. All these parameters are parsed into the provided scripts as arguments. See the notes inside each script for more details.

* <code>jobNickname</code>
* <code>jobClass</code>
* <code>runningHost</code>
* <code>dbUrl</code>
* <code>dbJndi</code>
* <code>dbUser</code>
* <code>dbPass</code>
* <code>dbMaxConn</code>
* <code>dbConnTimeout</code>
* <code>dbUnusedConnTimeout</code>
* <code>dbTablePrefix</code>
* <code>dbSchema</code>

== Forked Obsidian Job Runner ==
Should you wish to write your own <code>obsidianForkedJob.sh</code>/<code>obsidianForkedJob.bat</code> or wish to modify the one(s) provided, you'll need to know how to invoke the forked job runtime. The runtime is accessed by invoking the Obsidian class <code>com.carfey.ops.job.ForkedJob</code>. Its main method '''must''' be called with 2 arguments.
# <code>job_history_id</code> or <code>"scanClasspath"</code>
# <code>stack_file</code>

A number of the other arguments are available to be passed as JVM system properties for database connectivity as noted below:

<pre>
-Dcom.carfey.obsidian.db.url=$dbUrl -Dcom.carfey.obsidian.db.jndiType=$dbJndi -Dcom.carfey.obsidian.db.userId=$dbUser \
-Dcom.carfey.obsidian.db.password=$dbPass -Dcom.carfey.obsidian.db.maxConnections=$dbMaxConn -Dcom.carfey.obsidian.db.connectionTimeout=$dbConnTimeout \
-Dcom.carfey.obsidian.db.unusedPoolConnectionTimeoutSeconds=$dbUnusedConnTimeout -Dcom.carfey.obsidian.db.tablePrefix=$dbTablePrefix -Dcom.carfey.obsidian.db.schema=$dbSchema
</pre>

== Per Job Customizations - Classpaths and More ==
Three other parameters are provided as context for additional customization efforts, such as having alternate classpaths for particular jobs, classpath library ordering, controlling which Java executable is used and so on. Please contact the [[Contact_the_Obsidian_Scheduler_Team |Obsidian support]] team to discuss your needs or with any questions you have.

The scripts parse <code>jobNickname</code>, <code>jobClass</code> and <code>runningHost</code> from the arguments file. These can be utilized within the script to determine what specialization to apply. These could be used in conjunction with the default classpath, the <code>classpath_override</code> or on its own.

For example, if you wanted to use a custom classpath if the <code>job_class</code> is of type "com.example.OldLibrariesJob" and another one when the job nickname is "New Open Document Format Job", you might modify the shell script like this:

<pre>
if [ "New Open Document Format Job" == "$jobNickname"] ; then
cp=/Obsidian-3.0.0/newlibs/odf-4.0-beta.jar:/Obsidian-3.0.0/libs/... rest of classpath here
elif [ "com.example.OldLibrariesJob" == "$jobClass"] ; then
cp=/Obsidian-3.0.0/oldlibs/my-old-lib-1.0a.jar:/Obsidian-3.0.0/libs/... rest of classpath here
elif [ "" != "$classpathOverride" ] ; then
cp=$classpathOverride
elif [ "$(expr substr $(uname -s) 1 6)" == "CYGWIN" ] ; then
cp=$(find standalone -name "*.jar" -exec printf "{};" ';')
else
cp=$(find standalone -name "*.jar" -exec printf :{} ';')
fi
</pre>

== Notes about Spring and JNDI ==
Since Job Forking is starting a specialized short-lived Obsidian instance designed to either run a classpath scan or execute a job via a Java class' main method, database/email configuration via JNDI and Spring container support are not available out-of-the-box as these are made possible through your deployment and configuration options that Obsidian simply expects to be available. It's still possible to make use of these, it will just require an intermediary step between the forking scripts and the <code>com.carfey.ops.job.ForkedJob</code> class.

=== How to Support Spring and JNDI ===
You need some points of customization to make container resources available.

Possible customizations needed may include:
* A new entry point class that initializes a Spring Container, calls the Obsidian <code>com.carfey.ops.job.ForkedJob</code> class and then shuts down the container.
* A new or existing entry point mechanism that is able to call the Obsidian <code>com.carfey.ops.job.ForkedJob</code> class in your server container.
* Forking script modifications to utilize the above.

For example, let's say you have integrated Spring and Obsidian and want Spring support while using Job Forking.

# Write a new class that initializes your Spring container following the same Obsidian integration as you have done for your primary application. This class must take in the [[#Script_Arguments|Script Arguments]].
# In code, after initialization is complete, call <code>com.carfey.ops.job.ForkedJob</code> with the script arguments passed in.
# When the main method returns, shutdown the Spring container in code.
# Modify the forking script(s) to call the new class.

Job Features

2026-07-31T14:49:54Z

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

In Obsidian, everything starts with [[Admin_Jobs|jobs]]. They can be scheduled, constrained by parameters, and even restricted to running on specific hosts.

In addition to job [[Implementing_Jobs|implementation features]], Obsidian supports the following features that apply to the execution and scheduling environment.

= Full Execution History =

Obsidian offers full transparency into when jobs run, complete and if they fail. In addition, Obsidian stores [[Admin_Job_Activity|history]] of any time jobs are skipped, overlapped, missed due to downtime, etc.

Obsidian also stores saved job results, chaining evaluations and stack traces in the event of a job failure.

== Execution Statuses ==

The following are the valid states a job execution may appear in.

* '''Ready''' - Ready to be executed at its scheduled time and awaiting pickup for execution.
* '''Running''' - Currently executing.
* '''Completed''' - Completed execution without error (i.e. without throwing an uncaught exception). This is a terminal state.
* '''Failed''' - Did not complete successfully. Exception stack trace is saved for review. This is a terminal state.
* '''Missed''' - Could not be executed at its scheduled time due to an outage. This is typically when Obsidian was not running but could also be caused by technical issues such as database outage, inability to verify licenses, etc. This is a terminal state.
* '''Conflicted''' - Currently in an executable window (past its scheduled time but before its pickup buffer has expired), but is conflicted with another job. Equivalent to Ready, but when a conflict exists.
* '''Conflict Missed''' - Was prevented from executing by a conflicting job until after its pickup buffer expired. This is a terminal state.
* '''Died''' - The job execution thread (or forked process) was terminated. This can happen when Obsidian is shut down before a job completes. This is a terminal state.
* '''Abandoned''' - Was in Ready state but its pickup buffer expired without an active scheduler instance available to begin execution. This can also happen when there are active scheduler instances, but due to use of [[Admin_Jobs#Advanced_Options|Fixed Hosts]], no running instances match the host designator(s) assigned to the job. This is a terminal state.
* '''Overlapped''' - Was due to be run at its scheduled time, but was overlapped by a prior executing instance of the job. This means the previous running job's completion time was after the job's pickup buffer expired. This is a terminal state.
* '''Chain Skipped''' - Configured as a chain target, but the chaining restrictions were not met, so the job is not executed. This occurs when conditional chain criteria are not met, or the job state does not match one of the trigger states. This is a terminal state.
* '''Pending''' - The state given to an [[Implementing_Jobs#Async_Jobs | Async Job]] that has completed in Obsidian but has not yet been updated via the API to indicate its result.

== Execution Status Flow ==

[[File:obsidian_execution_statuses.png]]

= Date Bound Scheduling =

Obsidian supports setting the job's runtime schedule and state by date/time windows. This allows you to configure future changes to a schedule or job state. Obsidian also allows these changes to be scheduled in windows, so that a configuration will revert back to previous state at the completion of the window. This useful feature allows you to prepare for known outages, schedule holiday schedules in advance, and more, all without having to remember to make changes exactly when they need to go live.

Scheduling is done using standard [[Cron]] patterns and custom [[Cron#Recurrence | Recurrence]] extensions.

[[#Custom Calendars|Custom Calendars]] can also be configured with schedule changes to prevent execution on certain dates.

= Parameterization =
Jobs can also be parameterized, so that jobs can be reused in multiple configurations. Parameters allow for many varying instances of the same job class that differ by the specified parameters. See [[Implementing_Jobs#Parameterization|Parameterization]].

=Host Restrictions =
Jobs can be restricted to run only on specified hosts. This allows you to use Obsidian in a multi-host environment, even when certain jobs can only run on one of the hosts in the cluster.

A configuration item allows you to specify whether you wish host restrictions to apply on AdHoc jobs or not. It defaults to TRUE on new installations. It can by found under '''[[Admin Scheduler Settings|Scheduler Settings]] / Job / adHocJobsRespectFixedHostsRestrictions'''.

=Host Preference =

In addition to strict host selections, Obsidian supports the concept of host preference. For each job, you can select this option to enable prioritizing specific hosts for job execution. When a job configured with this setting is ready for execution, Obsidian will select the most preferred host to execute the job on, and if no preferred host is available, execution will fall back to any available host. This is configurable on the [[Admin_Jobs#Adding_.26_Editing_Jobs|job configuration screen]].

=Recovery=

Obsidian has extensive recovery support to ensure reliable execution in the event of outages.

Each job is configured with a ''Pickup Buffer'' which indicates how many minutes after the scheduled time a job is considered valid for regular pickup and execution.

Every configured job also specifies a ''Recovery Type'', which indicates how to handle a job that is not run within the ''Pickup Buffer''. This might happen because of a configured [[Admin_Job_Conflicts|conflict]] or because the scheduler was not running. Obsidian gives you fine control over how to handle these situations by exposing the following ''Recovery Types'':
* ''Last'' indicates that only the last missed job run will be recovered.
* ''Conflicted'' indicates that only conflicted job runs will be recovered.
* ''All'' indicates that all job runs will be recovered.
* ''None'' indicates that no job runs will be recovered.

Obsidian also supports individual job failure recovery through automated retries.
Each job can be configured to use ''Auto Retries''. Specify a ''Count'' that will tell Obsidian how many times to keep trying (essentially an auto-resubmit) a failed job.

You can use ''Interval'' and ''Exponential'' as well. Use ''Interval'' to indicate the minimum number of minutes from the last failure to the next retry.
Use ''Exponential'' if you want the auto retries interval to exponentially increase as retries are attempted. For example, if you set the interval minutes to 5 and check Exponential, the first retry will be 5 minutes after failure, the second retry after a subsequent failure will be 10 minutes later, then 20 minutes, and so on.

= Resubmission & Ad Hoc Runs =
Did a job fail unexpectedly? Or do you just need to run a job one time? Obsidian gives you the flexibility to resubmit failed jobs or submit them for a single execution regardless of their execution schedule. This can be done via our [[REST_API|REST API]], [[Embedded_API|Embedded API]] or via the [[Admin_Job_Activity|admin web application]].

In addition, when you submit an ad hoc job run, you can supply job parameters which apply only to that execution. This can be useful for executing jobs for a particular one-time need. For example, if you run out of disk space on a host, you may have a log archival job which can be run against a specific directory for a single execution.

Multiple Ad Hoc Runs may be submitted per minute for both immediate (next minute) execution and future execution.

= Forced Termination (interruptable jobs) =
Jobs that appear to be hung or need to be interrupted for any other reason can be terminated by having the job implement a simple interface. See [[Implementing_Jobs#Interruptable_Jobs|interruptable jobs]].

=Expected Length Handling (job execution duration) =

Jobs can have an expected runtime length set, which causes a Warning level event to be triggered if a job falls outside of the expected range. This is used primarily for notifications. Users can be alerted in the event of a long-running (or unexpectedly short) job by configuring the appropriate [[Admin Notifications|Notifications]].

[[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] also support auto interruption when execution length exceeds maximum expected run length.

= Custom Calendars =
[[Admin_Custom_Calendars|Custom calendars]] allow you to create named sets of dates that are used to prevent job executions. When setting a schedule for a job, you can select a custom calendar so that job execution is suppressed on any date defined in the custom calendar, regardless of the cron pattern used.

Common uses would be to define corporate holidays or those of your partners. Custom calendars are optional applications to the aforementiond [[Job_Features#Date_Bound_Scheduling|date bound scheduling]].

Installation Guide

2026-07-31T14:49:54Z

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

'''This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases.

This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.

The installer itself installs and configures the artifacts. The configured artifacts will have their [[Advanced_Configuration#Properties_File|Properties]] file configured according to the choices made during the installation process. You may always change these later or use one of the [[Advanced_Configuration#Properties_File|override]] mechanisms.
== Running the Obsidian Installer ==
The installer is an executable JAR file in the Obsidian download zip package available on our [https://web.obsidianscheduler.com/download/ download page].

The installer can be run from the command line as a graphical user interface using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code> or in interactive console mode using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar -console</code>. Note that you will have to replace the JAR file name with the actual versioned name in your installation.

On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.

If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>.

== Obsidian Installer Artifacts ==

The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.

[[Image:Obsidian-7.0.0-Installation-Packages.png]]

# '''Obsidian WAR''' - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at ''INSTALL_PATH''/obsidian.war!/WEB-INF/classes/com.carfey.properties.
# '''Obsidian Standalone Admin WAR''' - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at ''INSTALL_PATH''/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
# '''Standalone Obsidian Runtime''' - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at ''INSTALL_PATH''/standalone/obsidian-props.jar!/com.carfey.properties.
# '''Obsidian License Proxy''' - Allows for local license leasing from a [[Key_Server_Proxy|Key Server Proxy]] that ultimately leases licenses from the Obsidian License server.
# '''Documentation''' - README and Embedded API Javadoc.
# '''Obsidian Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
# '''Obsidian Standalone Admin Embedded Tomcat JAR''' — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
# '''License''' - Obsidian and 3rd party license information.

==== Deployment options ====

Obsidian 7.0.0 offers four deployment profiles in the installer:

* '''Obsidian WAR''' — deploy '''obsidian.war''' to your own servlet container (Tomcat, WebLogic, etc.).
* '''Obsidian Embedded Tomcat JAR''' — adds an embedded Tomcat runtime and '''webObsidian''' scripts to run '''obsidian.war''' locally ('''start scheduler'''). '''Requires''' the Obsidian WAR pack.
* '''Obsidian Standalone Admin WAR''' — admin console WAR for an external servlet container.
* '''Obsidian Standalone Admin Embedded Tomcat JAR''' — embedded runtime for the admin WAR ('''start adminOnly'''). '''Requires''' the Standalone Admin WAR pack.

Embedded Tomcat does '''not''' replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack. For how to start, stop and change the ports of the embedded runtime, see [[Getting_Started#Starting_Obsidian_with_embedded_Tomcat|Starting Obsidian with embedded Tomcat]].

==== Linux desktop and systemd integration ====

On a Unix host, an embedded Tomcat pack also copies a '''linux/''' directory under your install path holding user-level systemd and desktop-entry templates, and the installer offers to activate them. Nothing is installed system-wide and no root privileges are required.

The '''Embedded Tomcat - Linux integration (optional)''' panel carries the checkbox '''Install Linux desktop and user systemd integration''' (unchecked by default). Tick it to have the installer run the integration script for you; the option only takes effect if you also selected an embedded Tomcat pack. Leaving it unchecked still copies the templates, so you can opt in later by running this from the install directory:

./linux/install-embedded-linux-integration.sh "$PWD"

Either route writes two files, for the installing user only:

* ''~/.config/systemd/user/obsidian-embedded@scheduler.service''
* ''~/.local/share/applications/obsidian-embedded.desktop''

(''XDG_CONFIG_HOME'' and ''XDG_DATA_HOME'' are honoured when set.)

For an automated (headless) install, request the integration with:

<nowiki><entry key="embed.linux.integration" value="true"/></nowiki>

This panel is '''not shown on Windows installs''' — the systemd and desktop templates are Linux-only. On Windows, run '''webObsidian.bat''' manually or wrap it with your own service tooling.

Installing these files does not enable or start anything. To enable, stop, reconfigure or remove the service, see [[Getting_Started#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].

== Obsidian Configuration ==

The installer will guide you through the configuration Obsidian.

[[Image:Obsidian-7.0.0-Configuring-Obsidian.png]]

First, you must choose what [[Authenticator]] mechanism will be used within Obsidian. ''Native (Database)'' authentication requires no additional configuration and is what most users will select. Select ''Other'' if you have implemented your own authentication mechanism, OAuth (OIDC), SAML or LDAP according to your desired mechanism.

Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event [[Event_Notifications|notification]] and [[Admin_Notifications|subscription]] support in Obsidian.

Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.

==== OAuth / OIDC Configuration ====

If you selected '''OAuth (OIDC)''' as the authentication type, the installer displays additional panels for OAuth configuration.

===== Provider and Common Settings =====

[[Image:Obsidian-7.0.0-Configuring-OAuth_OIDC.png]]

* '''Identity Provider''' — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
* '''SSO Button label''' — Label shown on the "Sign in with…" button (e.g. ''Keycloak'', ''Acme Corp SSO''). If left blank the button reads "Sign in with SSO".
* '''Redirect URI''' — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
* '''Logout mode''' — ''local'' (default) or ''rp'' (RP-initiated logout via the IdP's end_session_endpoint).

===== Provider-Specific Settings =====

Fill in the connection details for your chosen provider.

[[Image:Obsidian-7.0.0-Configuring-Keycloak.png]]

;Keycloak
* '''Issuer URL''' — e.g. ''https://keycloak.example.com/realms/myrealm''.
* '''Client ID''' and '''Client Secret''' from the Keycloak client settings.
* '''Scopes''' — recommended: ''openid profile email groups''.
Note: Keycloak does not include a ''groups'' claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

[[Image:Obsidian-7.0.0-Configuring-Microsoft-Entra-ID.png]]

;Microsoft Entra ID
* '''Issuer URL''' — ''https://login.microsoftonline.com/<tenant-id>/v2.0''.
* '''Client ID''' — the Application (client) ID from the Azure portal.
* '''Client Secret''' — a client secret value from the Azure portal.
* '''Scopes''' — ''openid profile email''.
Note: the ''groups'' claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names.
'''Multi-tenant applications are not supported in Obsidian 7.0.0.'''

[[Image:Obsidian-7.0.0-Configuring-Okta.png]]

;Okta
* '''Issuer URL''' — use the '''Custom Authorization Server''' URL, e.g. ''https://<domain>.okta.com/oauth2/default''. Do '''not''' use the Org Authorization Server URL.
* '''Client ID''' and '''Client Secret''' from Okta application settings.
* '''Scopes''' — ''openid profile email groups''.

[[Image:Obsidian-7.0.0-Configuring-Auth0.png]]

;Auth0
* '''Domain / Issuer URL''' — e.g. ''https://<domain>.auth0.com/''.
* '''Client ID''' and '''Client Secret''' from Auth0 application settings.
* '''Scopes''' — ''openid profile email''.
'''Important:''' Auth0 issues opaque access tokens by default which are '''not supported''' on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

[[Image:Obsidian-7.0.0-Configuring-Generic_OIDC.png]]

;Generic OIDC
* '''Issuer URL''' — the base URL; Obsidian appends ''/.well-known/openid-configuration'' to discover endpoints.
* '''Client ID''' and '''Client Secret''' from the provider.
* '''Scopes''' — at minimum ''openid''; add ''profile'' and your groups scope as needed.

===== Group → Role Mapping =====

[[Image:Obsidian-7.0.0-OAuth-Group-Role-Mapping.png]]

The final OAuth panel maps IdP group values to Obsidian roles. '''Require role assignment''' (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the '''Admin''' role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties]] for the full property reference.

===== Registering the redirect URI at the IdP =====

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match ''com.carfey.suite.security.OAuthAuthenticator.redirectUri'' exactly, including scheme and port.

==== LDAP Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.LDAP.png]]

If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian [[Authenticator#Roles|Roles]]. The ''Access DN'' configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.

==== Custom Authenticator Configuration====

[[Image:Obsidian-5.0.0.Installer.Configure.CustomAuthenticator.png]]

If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.

==== Database Configuration ====

[[Image:Obsidian-5.0.0.Installer.Database.Configuration.png]]

Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.

The ''Database connections per instance'' and ''Database connection timeout(millis)'' fields are required and provide directive to the connection pool.

''Database table name prefix'' is optional and is typically used when Obsidian will be colocated in an existing database/schema.

''Database schema (Oracle/PostgreSQL)'' - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.

By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check ''Include all supported JDBC libs''.

==== Email Configuration ====

If not using JNDI for mail sessions, provide the server and authentication details as required.

[[Image:Obsidian-5.0.0.Installer.Configure.SSL.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.TLS.Email.png]]

[[Image:Obsidian-5.0.0.Installer.Configure.Open.Email.png]]

==== JNDI Configuration ====

[[Image:Obsidian-5.0.0.Installer.Configure.JNDI.png]]

If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.

==== Configuring 3rd Party Library Conflict Management ====
[[Image:JarJar-Obsidian-6.0.0.png]]

The Obsidian installer allows you to use [https://code.google.com/archive/p/jarjar JarJar] to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.

==== Selecting Script Libraries ====

[[Image:Obsidian-6.0.0-Choose-Scripting-Libraries.png]]

The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.

==== Choosing Email Support ====
As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

[[Image:Obsidian-5.0.0.Installer.EmailImplementation.Configuration.png]]

==== Additional configuration items ====

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

[[Image:Obsidian-5.5.0.Extra.Configuration.png]]

==== Offline or restricted-network install ====

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

# Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching '''Obsidian-Install-7.0.0.jar''').
# Copy the cache to the install host. Two layouts are supported:
#* '''Flat:''' one file per installed JAR name directly under the cache root.
#* '''File Maven repo:''' '''<group>/<artifact>/<version>/<installed-filename>.jar'''
# Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

===== Corporate Maven mirror (online) =====

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

== Completing the Installation ==

[[Image:Obsidian-5.0.0.Installer.Finished.png]]

Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.

Should you wish to automate future installations with the same configuration, click ''Generate an automatic installation script''. This will prompt you to save an XML file that can be used for future installations using the automated install procedure <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar my-obsidian-configuration.xml</code>. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the [[Release_Notes|Release Notes]]. These automated installer files can also be used as templates for other environments, modifying them as necessary.

Initializing and Restoring

2026-07-31T14:49:53Z

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

At times, you may wish to perform initialization, backup or restoration of an Obsidian installation. For example, you may wish to take a known good configuration from a development environment and apply it to a test environment.

As of Obsidian 6.3.0, we introduce support for [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.Initializable.html annotation based initialization] that leverages our [[Implementing_Jobs#Classpath_Scanning|classpath scanning]].

In Obsidian 3.0.0, we introduce support that leverages the [[Embedded_API#SystemRestoreManager_API|System Restore]] functionality of our API. Both the [[Embedded_API|Embedded API]] and [[REST_API|REST API]] expose functions for retrieving and updating the full configuration for an Obsidian installation. Rather than require you to individually retrieve all the configuration items and then apply them elsewhere, a full JSON snapshot can be generated and imported, allowing for easy backups and restores.

== Uses ==

=== Annotation Initialization ===
''As of Obsidian 6.3.0''

Job configuration can be automated into target environments via via annotations and [[Implementing_Jobs#Classpath_Scanning|classpath scanning]]. The base annotation to configure a job is [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.Initializable.html Initializable]. It is a [https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/annotation/Repeatable.html @Repeatable] annotation. On every startup, the nickname in the annotation is used to determine if that job <code>Initializable</code> reference has been initialized before, either via annotation, API or UI. Any nickname conflict will prevent initialization. Initialization is best effort per annotation, with errors logged and event notifications dispatched.

Chains can be initialized via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.InitializableChainAnnotation.html InitializableChainAnnotation] using nicknames. It is also a [https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/annotation/Repeatable.html @Repeatable] annotation. Descriptions along with source and target job are used to determine if the chain has been initialized previously, since source/target pairs can be repeated with different setups. Conditional chaining can be done via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.InitializableChainConditionAnnotation.html InitializableChainConditionAnnotation]. Again, it is a [https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/annotation/Repeatable.html @Repeatable] annotation.

=== Backup or Export ===
Use the System Restore [[REST_Endpoints#GET_a_system_restore_configuration|GET REST endpoint]] or the [[Embedded_API#Get_System_Restore_Configuration|equivalent Embedded API]] to retrieve a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration]. Store the JSON representation in your backup media.

=== Transfer or Restore a Configuration ===
Follow the [[Initializing_and_Restoring#Backup_or_Export|Backup]] instructions. Then, using the backup JSON, you can either place it on the file-system/classpath as described in [[#Startup_Initialization|Startup Initialization]], or use it in conjunction with the System Restore [[REST_Endpoints#PUT_a_system_restore_configuration|PUT REST endpoint]] or [[Embedded_API#Update_System_Restore_Configuration|equivalent Embedded API]].

You may choose to update parts of the exported configuration depending on your needs, or to set new user passwords.

'''Note:''' Users do not include the current passwords since they cannot be determined, and also as a security measure. All users will be returned with the password "changeme".

=== Startup Initialization ===
By default, Obsidian will look for a file on the classpath named <code>/obsidianInitialization.json</code> containing configuration data in the format described in [[#JSON_Configuration_Format|JSON Configuration Format]].

You may override the classpath resource name using the system property <code>obsidianInitClasspath</code>. For example, you could add the java system property <code>-DobsidianInitClasspath=/com/mycompany/obsidianInit.json</code>. You can also use a file-based resource by using the system property <code>obsidianInitFile</code>. For example, you could add the java system property <code>-DobsidianInitFile=/var/obsidian-3.0.0/obsidianScheduleInitialization.json</code>.

'''Note:''' Initialization only runs on scheduler instances. This means that a standalone Obsidian web application with no scheduler running will not do any initialization based on the presence of the appropriate JSON file.

== JSON Configuration Format ==
The file format is a JSON serialized version of the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration] class. Here we will define each configuration item and any special conditions associated with each one. A sample JSON is [[#Sample|provided]].

=== Jobs ===
The <code>jobs</code> key has a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/JobSaveRequest.html JobSaveRequest] objects. Each of these represents a configured job in Obsidian. This JobSaveRequest is very much like a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobCreationRequest.html JobCreationRequest] but having two extra attributes to handle the case where a job with the same nickname already exists. The <code>updateAttributes</code> flag is used to determine whether the job attributes (jobClass, recoveryType, pickupBufferMinutes, etc.) will be updated when the job exists. The <code>updateSchedule</code> flag is used to determine whether to apply the current schedule and any additional <code>jobSchedules</code> when the job already exists. If any of the schedules' end dates are in the past, they will be skipped.

=== Job Chains ===
The <code>chains</code> key is a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/ChainsRequest.html ChainsRequest] that houses a collection of chain configurations and a <code>replaceAll</code> attribute. The replaceAll attribute is used when chains already exist in the system. If chains exist and the flag is not set to true, the existing chains are left as is. If set to true, all existing chains are deleted and the new set of chains are created.

=== Job Conflicts ===
The <code>conflicts</code> key is similar to the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictUpdateRequest.html ConflictUpdateRequest] but it uses job nicknames instead of job IDs. If an empty list is supplied, all chains will be deleted. Note that this is different from a null or missing value.

=== Users ===
The <code>users</code> key has a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/UserSaveRequest.html UserSaveRequest] objects. These are similar to the standard [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserCreationRequest.html UserCreationRequest], but they contain an <code>update</code> attribute that is used when the user already exists. If the same user name exists and the flag is not set to true, the user is left as is. Otherwise, the user is created or updated as the case dictates.

=== Global Parameters ===
The <code>globalParameters</code> key is a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameter.html GlobalParameter] objects that are to be set into the system. Any current global parameters are either deleted or overridden.

=== Custom Calendars ===
The <code>customCalendars</code> key is a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarUpdateRequest.html CustomCalendarUpdateRequest] objects. Creates or updates as the case dictates by matching on the name.

=== System Parameters ===
The <code>systemParameters</code> key is a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameter.html SystemParameter] objects. Updates all parameters given.

=== Subscribers ===
The <code>subscribers</code> key is a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SubscriberSaveRequest.html SubscriberSaveRequest] objects. Creates or updates as the case dictates by matching on the email address.

=== Templates ===
The <code>templates</code> key is a list of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/TemplateSaveRequest.html TemplateSaveRequest] objects. Creates or updates as the case dictates by matching on the name.

== Sample ==

<pre>
{
"jobs": [
{
"updateSchedule": false,
"updateAttributes": false,
"jobSchedules": [
{
"state": "DISABLED",
"effectiveDate": "2015-03-20T10:35:00-0700",
"endDate": "2999-12-31T23:59:00-0800"
}
],
"jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
"minExecutionDuration": "2s",
"maxExecutionDuration": "3s",
"nickname": "Log Cleanup",
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [ "Demo-PC" ],
"ordinalParameters": [
"ordinal": 0,
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ALL"
},
{
"name": "maxAgeDays",
"type": "INTEGER",
"value": "120"
}
]
],
"chainAll": false,
"hostPreference": true,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "ENABLED",
"schedule": "* * * * *",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2015-03-20T10:34:00-0700"
},
{
"updateSchedule": false,
"updateAttributes": false,
"jobSchedules": [],
"jobClass": "com.carfey.ops.job.script.GroovyJob",
"nickname": "Script Job",
"pickupBufferMinutes": 2,
"recoveryType": "NONE",
"hosts": [],
"ordinalParameters": [
"ordinal": 0,
"parameters": [
{
"name": "script",
"type": "STRING",
"value": "sdfds"
}
]
],
"chainAll": false,
"hostPreference": false,
"autoRetryCount": 0,
"autoRetryInterval": 0,
"autoRetryIntervalExponent": false,
"state": "DISABLED",
"effectiveDate": "2015-01-01T00:00:00-0700"
"endDate": "2999-12-31T23:59:00-0800"
}
],
"globalParameters": [
{
"name": "dbPassword",
"type": "STRING",
"values": ["secret"]
}
],
"users": [
{
"update": false,
"userName": "admin",
"active": true,
"roles": [
"API",
"ADMIN",
"WRITE"
],
"password": "changeme"
}
],
"chains": {
"replaceAll": false,
"items": [
{
"sourceJobNickname": "Script Job",
"targetJobNickname": "Log Cleanup",
"active": true,
"triggerStates": [
"FAILED",
"CONDITIONAL"
],
"resultConditions": [
{
"variableName": "dfdsfds",
"operator": "EQUALS",
"values": [
"sdfs"
]
}
]
}
]
},
"conflicts": [
[
"Script Job",
"Log Cleanup"
]
],
"customCalendars": [
{
"name": "Sample Calendar",
"dates": [
"2011-01-01"
]
}
],
"systemParameters": [
{
"name": "adHocJobsRespectFixedHostsRestrictions",
"description": "This value determines whether the Fixed Hosts restriction assigned to a Job is respected for Ad Hoc jobs.",
"category": "JOB",
"value": "true"
}
],
"templates": [
{
"jobNicknames": [],
"name": "Obsidian Default Job Template",
"active": true,
"category": "JOB",
"defaultForJobs": true,
"subjectTemplate": "Obsidian [{{hostName}}] {{subject}}",
"bodyTemplate": "Body Template"
}
],
"subscribers": [
{
"generalSubscriptions": [
{
"jobNickname": "Log Cleanup",
"category": "JOB",
"level": "ERROR",
"active": true
}
],
"jobExecutionSubscriptions": [
{
"jobNicknames": [],
"allJobs": true,
"triggerStates": [
"CONDITIONAL",
"DIED",
"FAILED",
"RECOVERY"
],
"resultConditions": [
{
"variableName": "someVar",
"operator": "EQUALS",
"values": [
"someValue"
]
}
],
"active": true
}
],
"emailAddress": "test@example.com",
"active": true
}
]
}
</pre>

Implementing Jobs

2026-07-31T14:49:53Z

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

This information covers implementing [[Admin_Jobs|jobs]] in Java. This includes how to write your own jobs, use parameterization and job result features, and how to set up your classpath to include your own job implementations. If you want to schedule execution of scripts, please see our [[Scripting Jobs]] topic.

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]]. 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.

= SchedulableJob Interface =

[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|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/>

<pre>
public interface SchedulableJob {
public void execute(Context context) throws Exception;
}
</pre>

In your implementation, the <code>execute()</code> method does any work required in the job and it can throw any type of Exception, which is handled automatically by Obsidian.

If you aren't using parameterization or saving job results, that's all you need to do. It's likely you'll just be calling some existing code through your job implementation. Here's an example:

<pre>
import com.carfey.ops.job.Context;
import com.carfey.ops.job.SchedulableJob;
import com.carfey.ops.job.param.Description;

@Description("This helpful description will show in the job configuration screen.")
public class MyScheduledJob implements SchedulableJob {
public void execute(Context context) throws Exception {
CatalogExporter exporter = new CatalogExporter ();
exporter.export();
}
}
</pre>

All executed jobs are supplied a <code>Context</code> object (see [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/Context.html Javadoc]) is used to expose configuration parameters and job results.

You can also access the scheduled runtime of the job using <code>com.carfey.jdk.lang.DateTime Context.getScheduledTime()</code>. If you wish to convert this to another Date type, such as <code>java.util.Date</code>, you can use the <code>getMillis()</code> method which provides UTC time in milliseconds from the epoch:

<pre>
Date runTime = new java.util.Date(context.getScheduledTime().getMillis());
</pre>

'''Note:''' You can annotate your job with the <code>com.carfey.ops.job.param.Description</code> (see [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/Description.html Javadoc]) annotation to provide a helpful job description which is shown in the job configuration screen. This can be useful for indicating how a job should be configured.

'''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 ==

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.AsyncJob.html AsyncJob Javadoc]

'''As of Obsidian 4.5.0''', this marker annotation is used to indicate that a SchedulableJob kicks off an asynchronous process, such as a call to a web service. Once the asynchronous process has been completed, the <code>execute(Context context)</code> method should complete. The job will then be marked as <code>PENDING</code> indicating that its ultimate status is pending. The activity record will remain in this state until either the [[REST_Endpoints#POST_async_results|REST API]] or [[Embedded_API#Post_Results_to_a_Pending_.28Async.29_Runtime|Embedded API]] is used to set the final results of the job.

== Threading in Jobs ==

Obsidian runs each job within its own Java thread, so execution does not hold up scheduling or execution of any other job. For most jobs, you can do all your work in this single thread and not worry about multi-threading or thread safety.

However, you may wish to multi-thread execution within a job for performance reasons. There is no problem with this approach, but to do so, there are a few things to keep in mind:
* If you start any threads or create an <code>ExecutorService</code>, you will need to clean up before the job terminates. All resources acquired within the <code>execute()</code> method must be cleaned up by your job code, including threads.
* If you want the job to terminate only after all threads or created tasks complete, you must call <code>Thread.join()</code>, <code>Future.get()</code>, or an equivalent method to ensure execution completes before the job thread continues and exits the <code>execute()</code> method.
* For job failures within created threads or tasks to be reported to Obsidian, an <code>Exception</code> must be thrown by the job thread itself. For example, this can be done via <code>Future.get()</code>. For raw threads, you may need to save some state indicating success or failure, and throw an <code>Exception</code> as appropriate within the job's execution thread.

= Dependency Injection via Spring =
Obsidian supports executing jobs wired as components via Spring. See our dedicated page on [[Spring_Integration|Spring Integration]] for full details.

= Parameterization =

Obsidian offers flexibility and reuse in your jobs by supplying configurable parameters for each job.

If you would like to parameterize jobs, you can define parameters on the job class itself, or use custom parameters which are only set when configuring a job. Defined parameters are automatically displayed in the [[Admin_Jobs|Jobs]] screen to help guide configuration, but also to provide defaults and enforce data types and required values. Custom parameters can be set for any job, and lack additional validation.

Defined parameters are specified on the job class using the <code>@Configuration</code> annotation (see [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/Configuration.html Javadoc]).

The following example shows a job using various parameters. It includes a required ''url'' parameter has two valid values, an optional set of names for saving the results and a Boolean value to determine whether compression should be used. It shows a fairly comprehensive usage of various data types and other parameter settings.

<pre>
import com.carfey.ops.job.param.Configuration;
import com.carfey.ops.job.param.Parameter;
import com.carfey.ops.job.param.Type;

@Configuration(knownParameters={
@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="compressResults", required=false, defaultValue="false", type=Type.BOOLEAN)
})
public class MyScheduledJob implements SchedulableJob {
</pre>

'''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:
<pre>
public void execute(Context context) throws Exception {
JobConfig config = context.getConfig();

MyExistingFunction function = new MyExistingFunction();

String url = config.getString("url");
function.setUrl(url);

boolean compress = config.getBoolean("compressResults"); // defaults to false
function.setCompress(compress);

String result = function.go();

for (String resultsName : config.getStringList("saveResultsParam")) {
context.saveJobResult(resultsName, result);
}
}
</pre>

For all the available methods on <code>JobConfig</code>, see the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/config/JobConfig.html Javadoc].

The following is the <code>@Parameter</code> source code (see [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/Parameter.html Javadoc]), which helps illustrate attributes that can be configured:

<pre>
public @interface Parameter {
public String name();
public boolean required();
public boolean requiredAtRuntime();
public Type type() default Type.STRING;
public boolean allowMultiple() default false;
public String defaultValue() default "";
public Class<? extends ListProvider> listProvider() default StaticListProvider.class;
public String[] listArgs() default {};
public String description() default ""; // as of 4.0.2
public String[] urls() default {}; //as of 4.9.0
public boolean requireUniqueSelection() default false; //as of 4.10.0
}
</pre>

''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.

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.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 ==

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>
@Configuration(knownParameters={
@Parameter(name="logLevel", required=true, type=Type.STRING, listArgs={"ERROR", "INFO", "DEBUG"})
})
</pre>

=== List Providers ===

For more complex scenarios, you may wish to enumerate values through code. This can be done by creating your own implementation of the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/ListProvider.html ListProvider] interface, including it in the Obsidian classpath, and then referencing it in your <code>@Parameter</code> annotation via <code>listProvider</code>. The <code>listArgs</code> value can be used to provide arguments to your <code>listProvider</code>, since they are passed into it when enumerating valid values.

The example below demonstrates this using the built-in [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider], which provides a listing of full file paths based on a directory configured in a global parameter specified via <code>listArgs</code>.

<pre>
/** Enumerate all files in the directory specified by the global parameter "rootDirectory". **/
@Configuration(knownParameters={
@Parameter(name="file", required=true, type=Type.STRING, listProvider=com.carfey.ops.job.param.FileListProvider.class, listArgs={"rootDirectory"})
})
</pre>

==== Dynamic List Providers ====

''As of Obsidian 4.5.0'', a <code>ListProvider</code> can be marked as providing dynamic, or changing values, using the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/ListProvider.DynamicListProvider.html DynamicListProvider] annotation. By doing so, the provider will be asked to provide its valid values every time the [[Implementing_Jobs#Classpath_Scanning | Classpath Scanner]] runs. Any configured jobs will need to satisfy the values when they are executed or re-configured.

=== Dynamic File Lists ===

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.

This allows you to enumerate files in a server-side directory which is configured in a named [[Admin_Global_Parameters|global parameter]]. To use this feature, specify the appropriate <code>listProvider</code> class along with at least one value for <code>listArgs</code> to specify the global parameter name which will contain the configured directory. When the job is configured, Obsidian will enumerate valid values from the directory configured in the global parameter. At execution, the configured value will also be checked to ensure it is a valid value based on the current directory listing.

<pre>
Configuration(knownParameters={
@Parameter(name="fileToProcess", type=Type.STRING, listArgs={"sourceDirectory"}, listProvider=FileListProvider.class, required = false),
@Parameter(name="logTarget", type=Type.STRING, listArgs={"logDirectory", "false", ".*log", "true"}, listProvider=FileListProvider.class, required = false)
})
</pre>

As shown in the <code>logTarget</code> parameter, <code>FileListProvider</code> supports additional arguments. See the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html Javadoc] for full usage details.

== Inheritance ==

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.

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 ==

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.

Obsidian will perform automatic type conversion for all values - a global parameter's type definition doesn't have to match the type of the defined parameter that references it. Once Obsidian has resolved all global parameter values, it will validate them to ensure all defined parameter restrictions are respected. Note that Obsidian strictly enforces that a global parameter must exist when referenced.

Note that you can configure a job parameter with multiple global parameter references along with normal values, and Obsidian will combine them all into the configuration passed into your job.

The [[Admin_Global_Parameters|Global Parameters]] page explains how to configure global parameters.

'''Note:''' If you wish to change the tokens used to surround global parameters, you may override them using properties outlined in [[Advanced Configuration]].

=== Global Substitution Mode ===

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:

<pre>
-Dfile.encoding={{globalFileEncoding}}
</pre>

To enable this, update the [[Admin_Scheduler_Settings|scheduler setting]] <code>useGlobalSubstitutions</code> to <code>true</code>. Note that this changes the behaviour of '''all global parameter references''' to use plain text substitution.

After enabling this setting, you may reference any number of global parameters inside job parameters using the normal curly brace syntax (e.g. <code>{{globalParamName}}</code>), and they may occur anywhere in the parameter value.

'''Important Note:''' Changing this setting may impact existing jobs since global substitutions use the first configured global parameter value to perform text substitution, while the normal behaviour expands global parameter references to use all configured values. In addition, if any job parameters contain text within doubled-up curly braces, Obsidian will interpret these as global parameter references and will fail job validation if they do not exist.

== Ad Hoc & One-Time Run Parameters ==

In addition to defining parameters for at the job level, Obsidian supports accepting parameters for a specific run time (i.e. job history) through the [[Admin_Jobs|Jobs]] screen, or via the [[REST_API|REST]] or [[Embedded_API|Embedded]] APIs. If a parameter name for a run parameter has the same name as a configured job parameter, the job parameter values are dropped, and the run parameter values are used instead.

These parameters are treated the same as those at the job level, and are exposed to the job in the same manner as parameters at the job level. Note that parameters must have the same data type as any already configured for the job, and must conform to restrictions defined by the <code>@Configuration</code> annotation if applicable.

= Config Validating Job =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/ConfigValidatingJob.html ConfigValidatingJob Javadoc]

In addition to providing simple validation mechanisms through the <code>@Parameter</code> annotation, Obsidian gives you a way to add custom parameter validation to a job.

The interface <code>com.carfey.ops.job.ConfigValidatingJob</code> extends <code>SchedulableJob</code> and allows you to provide additional parameter validation that goes beyond type validity and mandatory values. Below is its definition:

<pre>
public interface ConfigValidatingJob extends SchedulableJob {

public void validateConfig(JobConfig config) throws ValidationException, ParameterException;

}
</pre>

When a job implementing this interface is configured or executed, the <code>validateConfig()</code> method is called. All configured parameters are available in the same <code>JobConfig</code> object that is provided to the <code>execute()</code> method. You can perform any validation you require within this method. If validation fails, the job will not be created, modified or executed (depending on when validation fails), and the messages you added to the <code>ValidationException</code> are displayed to the user. Consider this example:

<pre>
public void validateConfig(JobConfig config) throws ValidationException, ParameterException {
List<String> hosts = config.getStringList("hosts");
ValidationException ve = new ValidationException();
if (hosts.size() < 2) {
ve.add("Host syncronization job requires at least two hosts to synchronize.");
}
int timeout = config.getInt("timeout");
if (timeout < 0) {
ve.add(String.format("Timeout must be 0 indicating no timeout or greater than 0 to indicate timeout duration. Timeout provided was %s.", timeout));
}
if (!ve.getMessages().isEmpty()) {
throw ve;
}
}
</pre>

=== Validation on Non-Scheduler Instances ===
If you configure a <code>ConfigValidatingJob</code> on a non-scheduler web application which does not have the job classpath available, Obsidian is forced to skip calling the corresponding validation method when the job is saved, but it will still do so during execution.

= Job Results =

Obsidian also allows for storing information about your job execution. This information is then available in chained and resubmitted jobs. In addition, as of release 1.4, jobs can be conditionally chained based on the saved results of a completed trigger job.

Job Results can be viewed after a job completes in the [[Admin_Job_Activity#Job_Activity_Details|Job Activity]] screen. They are also exposed in the Obsidian [[REST_API|REST API]].

Note this example that both evaluates source job information (i.e. job results saved by the job that chained to this one) and saves state from its own execution which could be used by a subsequently chained job:
<pre>
public void execute(Context context) throws Exception {
Map<String, List<Object>> sourceJobResults = context.getSourceJobResults();

// Grab results from the source job that was chained to this one
List<Object> oldResultsList = sourceJobResults.get("inputFile");
String oldResults = (String) oldResultsList.get(0);

... job execution ...

// This saved value is then available to chained jobs and can be viewed in the UI
context.saveJobResult(resultsParamName, oldResults + " Updated");

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

// You can replace job results.
context.replaceJobResult(resultsParamName, "replace old value");
context.replaceMultipleJobResults("file", Arrays.asList("third", "fourth"));

}
</pre>

The <code>Context</code> object (see [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/Context.html Javadoc]) methods used for retrieving and storing results are:

* <code>java.util.Map<java.lang.String,java.util.List<java.lang.Object>> getSourceJobResults()</code>
* <code>void saveJobResult(java.lang.String name, java.lang.Object value)</code>
* <code>void saveMultipleJobResults(java.lang.String name, Collection<?> values)</code> (from 2.2 onward)
* <code>void replaceJobResult(java.lang.String name, java.lang.Object value)</code> (from 3.6 onward)
* <code>void replaceMultipleJobResults(java.lang.String name, Collection<?> values)</code> (from 3.6 onward)

Note that <code>getSourceJobResults()</code> will return job results saved by the job that was chained directly to the currently executing job. If multiple jobs are chained in sequence, this method will ''not'' return results from every job in the chain. If you wish to pass all results down the chain, you can invoke <code>saveMultipleJobResults()</code> within each job, using the values from <code>getSourceJobResults()</code>.

== Default Supported Job Result Types ==
Though the job result methods accept <code>java.lang.Object</code>, by default there are limitations to what types Obsidian can store as a job result:
* Basic <code>java.lang</code> types such as <code>Boolean</code>, <code>String</code> and subclasses of <code>Number</code> are supported automatically and stored using <code>toString()</code> representations.
* If a type has a public constructor that accepts a single <code>String</code> argument, its <code>toString()</code> representation is used to store the result, and the constructor is used to re-construct it.
* ''As of Obsidian 4.4'', all other types are stored using the object's JSON representation by using [https://github.com/google/gson GSON].
* If you need to add support for types that do not work with the default implementation, or wish to completely change how types are stored and re-constructed, see the next section.

== Customizing Job Result Serialization and Deserialization ==

You may wish to customize the storage (serialization) and re-construction (deserialization) of job results, either to get custom behaviour or to support types that do not work by default. For example, you may wish to use Jackson-based JSON for complex types instead of the default GSON approach.

To customize behaviour, you may implement your own [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationStrategy.html SerializationStategy] and register it via the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationFactory.html SerializationFactory] singleton. The linked javadoc contains all the information you need to understand Obsidian's default behaviour and how to customize it.

Below is a sample that maintains Obsidian's default serialization for simple types, but uses a custom [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationStrategy.html SerializationStategy] for complex types.

<pre>

List<SerializationStrategy> strategies = Arrays.asList(
new DefaultSerializationStrategy(), // maintain Obsidian's simple type and String-based constructor support as the highest priority strategy
new CustomTypeSerializationStrategy() // add our custom strategy for all other types
);

SerializationFactory singletonFactory = SerializationFactory.get();
singletonFactory.replaceAll(strategies);

</pre>

= Annotation-Based Jobs =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.Schedulable.html Schedulable Javadoc]

While Obsidian offers a simple Java interface for creating new jobs, Obsidian also provides a way to use annotations to make an arbitrary Java class executable.

<code>com.carfey.ops.job.SchedulableJob.Schedulable</code> is a class-level marker annotation indicating that methods are annotated for scheduled execution. Adding this annotation allows you to configure a job in the Obsidian web app or REST API despite the class not implementing <code>SchedulableJob</code>.

<code>com.carfey.ops.job.SchedulableJob.ScheduledRun</code> is a method-level annotation to indicate one or more methods to execute at runtime. It has an <code>int executionOrder()</code> method that defaults to ''0''. This value indicates the order in which to execute methods. Duplication of execution order is not permitted. Annotated methods must have no arguments and must be public.

'''Note:''' Using these annotations precludes you from storing job results or parameterizing your job.

= Interruptable Jobs =

[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]

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.

The interfaces <code>InterruptableJob</code> and <code>InterruptableContextJob</code> extend <code>SchedulableJob</code> and flag a job as interruptable. Technically speaking, this means that the main job thread will be interrupted by <code>Thread.interrupt()</code>, when an interrupt request is received via the UI or REST API.

Both interfaces mandate implementation of a <code>void beforeInterrupt()</code> method, with the <code>InterruptableContextJob</code> version supplying the job's <code>Context</code> object, which contains the interrupting user through <code>getInterruptUser()</code>. This method allows for you to perform house-cleaning before Obsidian interrupts the job thread. For example, you may have additional threads to shut down, or other resources to release. You may also want to set a flag on the job instance to indicate to the executing thread that it should shut down, rather than rely on checking <code>Thread.isInterrupted()</code>. You should attempt to have your <code>beforeInterrupt()</code> execute in a timely fashion, though it will not interrupt other job scheduling/execution functionality if it takes some time.

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 [https://docs.oracle.com/javase/tutorial/essential/concurrency/interrupt.html tutorial] explains the details of thread interrupts.

= Classpath for Building =

To implement jobs in Java, you will need to reference Obsidian base classes in your Java project.

A single library containing everything you need to build Java jobs is found in your installation under the <code>/standalone</code> directory:

* <code>obsidian.jar</code>

This library will not conflict with your existing build classpath since it is unique to Obsidian.

To build a custom WAR, you can use the provided WAR artifacts in the Obsidian zip package you downloaded, and customize it in your desired build technology (e.g. Ant, Maven, Gradle, etc.).

For instructions on how to deploy your custom jobs to Obsidian, see [[Getting Started]].

== JVM Forking ==
[[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 =

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.

To configure classpath scanning, you must specify one or more package prefixes via [[Admin_Scheduler Settings|scheduler settings]]. Select the "Job" category, and locate the "packageScannerPrefix" parameter. Specify your comma delimited list of package prefixes and save your changes.

'''Note:''' The prefixes should be as specific as possible to reduce memory overhead. For example, if all your jobs are under <code>com.example.obsidian.jobs</code>, use the prefix "com.example.obsidian.jobs" rather than "com.example".

[[File:PackageScannerPrefix_4.0.png]]

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.

= 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.

= Best Practices =

Obsidian's many features give you multiple ways to solve the same problem, but here are some tips to guide your implementation:

* Use [[#Parameterization|parameters]] to promote reuse in your jobs by making them more generic - this helps avoid builds just for configuration changes. Defined parameters are especially useful to enforce constraints on configuration.
* Use class inheritance when writing your SchedulableJob classes to share common functionality between different jobs.
* Use [[#Job Results|job results]] for use in chained jobs. For example, you can chain to a generic archive or FTP transfer job which uses source job results to know what to send.
* Use [[#Global Parameters|global parameters]] when you are referencing configuration that many jobs require (e.g. database connection info or shared file paths).
* Avoid catching and not rethrowing exceptions when you want Obsidian to recognize it as a job failure. Obsidian relies on seeing a thrown exception to record job failures.
* Use [[Scripting_Jobs|script jobs]] to write simple jobs that are used for maintenance or simple tasks, but stick to compiled SchedulableJob classes for critical jobs or performance-sensitive production code.
* [[Contact_the_Obsidian_Scheduler_Team|Contact us]] if you want suggestions on how to implement your jobs. Our team is happy to help guide you on the right path.

Getting Started

2026-07-31T14:49:52Z

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

This Getting Started is for Obsidian 4.0 and newer versions.''

This guide will help you choose a deployment setup that works for you, and then get it running. Before reading this page, you may wish to review Obsidian's [[Deployment Models]] to understand the different parts of Obsidian or to find out what deployment model works for you.

If you've are looking to start writing your own Obsidian jobs, see [[Implementing Jobs]].

= Supported Platforms =

Please quickly review our supported platforms before continuing.

* Obsidian is OS-independent, and runs on the Java Virtual Machine. It works in a variety of environments, including Linux, OSX and Windows, and can be run inside virtual machines.
* Obsidian 5.x.x, 6.x.x and 7.x.x run on Java 11 or above (Obsidian 4.x.x runs on Java 1.7 or above). A JRE is sufficient — the embedded Tomcat runtime does not compile JSPs and needs no JDK.
* Obsidian's administration web application is a servlet application.
** 7.x.x has been tested on Tomcat 10.x
** 6.x.x has been tested on Tomcat 10.x and Jetty 11.x (Jakarta Servlet 5.0)
** 5.x.x has been tested on Tomcat 9.x and Jetty 10.x (Javax Servlet 4.0)
** 4.x.x has been tested on Tomcat 7, 8 & 8.5 and Jetty 9.x (Javax Servlet 4.0)
* It works on all modern browsers and is tested on recent versions of Chrome, Edge and Firefox.
* Obsidian requires one of the following fully-supported database platforms:
** MySQL 8.0.x (Obsidian 5.x and higher), 5.5-5.7 (excluding Galera)
** MariaDB 5.5
** Oracle 18c, 19c, 21c on Obsidian 5.x and higher
** Oracle 10g, 11.x, 12c on versions prior to Obsidian 5.0.0
** PostgreSQL 11-16 on Obsidian 5.x and higher
** PostgreSQL 9, 10
** MS SQL Server 2008-2019
** H2 1.4.
** ''Larger major versions are likely to work without issues but are not officially supported.''

'''Note:''' With some exceptions, clustered scheduler instances require access to contact license servers over the Internet, or access to an internal proxy license server. See [[Licenses & Nodes]] for more information.

== Hardware Requirements ==

We recommend the following minimum hardware for typical installations:

* 1 GHz processor
* 2 GB RAM
* 1 GB hard disk space (excluding accumulated logs)

Note that actual requirements may vary depending on job volume, clustering and other factors.

= Choose Your Installation Type =

Obsidian consists of two main processes:

* '''Scheduler''' - schedules and executes jobs, sends notifications, etc. Also exposes the [[Embedded API]].
* '''Admin Web Application''' - provides management and monitoring UI, plus the [[REST API]] and [[Embedded API]].

These can be run together or separately in the following configurations. You will pick one or more of these options together to provide both the scheduler and admin web application functionality.

# '''Standalone Scheduler''' - A Java process that performs job execution. A standalone scheduler installation is generated when you run the Obsidian installer, and may be customized by adding JAR files containing your job code. It is started and stopped by scripts included with the installation. Requires a separate admin web application to be deployed.
# '''Embedded Scheduler''' - Provides job execution like a standalone scheduler, but instead runs as a process embedded within and started from your application. This eliminates the need to customize and deploy a separate artifact which will perform job execution. Requires a separate admin web application to be deployed.
# '''Standalone Admin Web Application''' - A Java servlet application providing Obsidian's administration capabilities but no scheduling services. A standalone admin application WAR file is generated when you run the Obsidian installer, and may be customized by adding JAR files containing your job code. Requires a separate standalone, embedded or combined scheduler and web application to be deployed for job execution to be performed.
# '''Combined Scheduler and Admin Web Application''' - A version of the admin web application which also runs a scheduler service for job execution. A combined scheduler and admin application WAR file is generated when you run the Obsidian installer, and may be customized by adding JAR files containing your job code.

Regardless of the deployment configuration, any time you run more than one scheduler process operating against the same Obsidian database, they will automatically form a cluster and share in job execution.

Choosing which installation type works best for you depends on your specific needs. The setups which are suitable for most cases are, in order:

* Using an '''Embedded Scheduler''' (option 2), along with a '''Standalone Admin Web Application''' (option 3). This approach lets you embed Obsidian into your existing application without having to alter the Obsidian artifacts to include your job code. Instead, Obsidian's required libraries are included in your application and they are deployed together.
* Using a '''Combined Scheduler and Admin Web Application''' (option 4) alone or in a cluster. This is suitable if you don't have another application containing job code for Obsidian to execute, or if you simply want to use Obsidian's scripting support, which doesn't require deploying JAR files.

= Downloading Obsidian =
Just go to our [https://web.obsidianscheduler.com/download/ download page], and grab the latest Obsidian's installation zip file. There is no need to register or obtain a license before downloading.

Once you've downloaded the zip file, extract it to a directory of your choice.

If you are trying to upgrade to a newer version of Obsidian, see [[Upgrading_Obsidian|upgrade]] instructions.

= Quick Start for Evaluation Purposes =

If you wish to quickly try Obsidian without minimal setup required, follow these steps. Otherwise, skip ahead to [[#Initial Setup|Initial Setup]].

== Really Quick Method Using Embedded Database ==

''We do not recommend this setup for production use. ''

# Ensure you have a JDK (11 or up for Obsidian 6.x.x & 5.x.x, 1.7 or up for Obsidian 4.x.x) installed and that the <code>JAVA_HOME</code> environment variable is set to your JDK installation directory.
# Unzip the Obsidian download zip file to a directory of your choice.
# At the command line, in the zip extraction directory, run the [[Installation_Guide|installer]] using this command, substituting the appropriate Obsidian version number: <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>
# Start Obsidian using the command: <code>./webObsidian.sh start scheduler</code> for Linux or <code>webObsidian.bat start scheduler</code> for Windows.
# Go to http://localhost:8080 in your browser and check out your fully functional Obsidian web application and scheduler! You can log in to the admin web application with the default user ''admin'' and password ''changeme''.
# When you're done, stop Obsidian using the command: <code>./webObsidian.sh stop</code> or <code>webObsidian.bat stop</code> for Windows.

'''Note:''' If you restart the Quick Start installation and see "lock wait timeout" or similar errors in the log screen, you may have to delete your embedded H2 database lock file. By default, the file name is ''obsidian.lock.db'' and is located in the user home directory.

'''Note:''' If you see a <code>java.net.BindException: Permission denied</code> error on startup, you will need to use an alternate port. See [[Troubleshooting]] for details on how to change this.

== Quick Method Using Existing Database ==

If you wish to get Obsidian running quickly using a database platform you already have running, follow these steps:

# Ensure you have a JDK (11 or up for Obsidian 6.x.x and 5.x.x, 1.7 or up for Obsidian 4.x.x) installed and that the <code>JAVA_HOME</code> environment variable is set to your JDK installation directory.
# Unzip the Obsidian download zip file to a directory of your choice.
# At the command line, in the zip extraction directory, run the [[Installation_Guide|installer]] using this command, substituting the appropriate Obsidian version number: <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar</code>
# Start Obsidian using the command: <code>./webObsidian.sh start scheduler</code> for Linux or <code>webObsidian.bat start scheduler</code> for Windows.
# Go to http://localhost:8080 in your browser and check out your fully functional Obsidian web application and scheduler! You can log in to the admin web application with the default user ''admin'' and password ''changeme''.
# When you're done, stop Obsidian using the command: <code>./webObsidian.sh stop</code> or <code>webObsidian.bat stop</code> for Windows.

= Initial Setup =

This section covers the setup required after you've selected your [[#Choose_Your_Installation_Type|installation type]].

== Database ==

Obsidian requires a database which must be created before running Obsidian. Multiple [[#Supported Platforms|database platforms]] are supported. Obsidian can share a database/schema with another application.

Note that the database must exist before deployment, but by default Obsidian will automatically create all required tables.

Later, you will specify database connection parameters within Obsidian's installer to tell it how to connect. If you need to configure advanced settings or change settings directly after you've run run the installer, see [[Advanced Configuration]].

'''Note:''' Obsidian needs to create the tables in the target database. If the schema is shared with your application’s tables, please ensure there are no name conflicts. If there are conflicts, separate schemas/databases can be used, or a table prefix can be specified as shown in [[Advanced_Configuration#Database_Properties|Advanced Configuration]]. [[Obsidian Tables]] lists the tables Obsidian will created upon first deployment.

=== Manual Schema Creation ===

When you start Obsidian, it will automatically detect and create missing tables in your target database. However, if you wish to run Obsidian with a database user that does not have create privileges, or simply wish to prepare your database structure ahead of time, you can use the database scripts provided with your download zip file under the "db_scripts" directory.

First create your database, and locate the "complete.sql" file under the directory for the database you are using under the "db_scripts" directory. Statements within this file contain the token "$px$" to enable table prefixes. Before you run the SQL file, replace all instances of the token "$px$" (without quotes) with a table prefix 6 characters or shorter (letters and underscores supported), or with blank.

Then, in your SQL client of choice, execute the script and all the required Obsidian tables will be created.

=== Alternate Oracle Schemas ===

After allowing Obsidian to create all the required tables and initial data by deploying it a single time, Obsidian can be run with an alternate Oracle user by specifying the target schema on Oracle databases. See [[Advanced_Configuration#Database_Properties|Advanced Configuration]] for the property to set.

If you use a separate user from the schema owner, you must grant the user [[Obsidian_Tables#Oracle Privileges|certain privileges]] for Obsidian to function correctly.

=== MS SQL Server Snapshot Isolation ===

For maximum compatibility and to avoid deadlocks, MS SQL Server should be configured to use [https://learn.microsoft.com/en-us/dotnet/framework/data/adonet/sql/snapshot-isolation-in-sql-server read committed snapshot isolation].

This can be enabled on your database by running the following commands:

<pre>
ALTER DATABASE MyDatabase SET ALLOW_SNAPSHOT_ISOLATION ON
ALTER DATABASE MyDatabase SET READ_COMMITTED_SNAPSHOT ON
</pre>

== Authentication ==

By default, Obsidian manages its own set users and logins to restrict access to the admin web application and REST API. A default “admin” user is created when the scheduler is first deployed and no additional setup is required.

Alternatively, to use LDAP authentication, select the LDAP option in the installer and enter your LDAP details.

As of 7.0.0, you can also select OAuth / OIDC authentication to enable Single Sign-On via an external identity provider. See [[Authenticator#OAuthAuthenticator_(OIDC_SSO)|OAuthAuthenticator]] for details.

Finally, you may implement your own [[authenticator|custom authenticator]] Java class, which you also enter when running the installer.

= Running the Installer =

Now that you've chosen your installation type and performed initial setup of your database and authentication, you can run Obsidian's installer to configure and build a set of artifacts that you can either use to embed Obsidian, or deploy directly.

To run the installer, please follow our detailed [[Installation_Guide|installation guide]].

=== Installer-Created Artifacts ===

Once you've run the installer, your installation directory will look something like the following, depending on which artifacts you chose to generate.

<pre>
├───db_scripts
└───Obsidian-7.0.0
│ com.carfey.yaml.reference
│ obsidian.war
│ obsidian-builtin-job-src.jar
│ obsidianForkedJob.bat
│ obsidianForkedJob.sh
│ obsidian-javadoc.zip
│ standaloneObsidian.bat
│ standaloneObsidian.sh
│ standaloneObsidianAdmin.war
│ webObsidian.bat
│ webObsidian.sh
│
├───embed-tomcat-lib (present when an Embedded Tomcat pack is selected)
├───license
├───linux (present on Unix when an Embedded Tomcat pack is selected)
├───logs
└───standalone
(various JAR files...)
obsidian-yaml-configuration.jar
obsidian.jar
</pre>

The installer creates a top-level directory named '''Obsidian-n.n.n''' containing generated artifacts. The key files and directories are:

; com.carfey.yaml.reference or com.carfey.properties.reference
: Copy of the configuration file generated by the installer.
; obsidian.war
: Combined scheduler and admin web application WAR. Deploy directly to a servlet container, or run locally using the Embedded Tomcat pack (see below). Customise by adding your job code and dependencies as JARs to '''/WEB-INF/lib''' within the archive.
; standaloneObsidian.bat and standaloneObsidian.sh
: Windows and Linux scripts to start the standalone scheduler process with no web application. Customise by adding your job code and dependencies as JARs to the '''standalone''' directory.
; webObsidian.bat and webObsidian.sh
: Windows and Linux scripts to start Obsidian using the embedded Tomcat runtime (requires the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack). Use '''start scheduler''' to run the combined scheduler+admin WAR, or '''start adminOnly''' to run the standalone admin WAR. Stop with '''stop'''.
; standaloneObsidianAdmin.war
: Standalone admin web application WAR (no scheduler). Deploy directly to a servlet container or run via the embedded Tomcat pack.
; embed-tomcat-lib
: Present when an Embedded Tomcat pack is selected. Contains the embedded Tomcat runtime JARs used by the '''webObsidian''' scripts.
; linux
: Present on Unix when an Embedded Tomcat pack is selected. Optional user-level systemd unit and desktop-entry templates, plus '''install-embedded-linux-integration.sh''' and '''README-linux-integration.md'''. See [[#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]].
; standalone
: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.

= Starting Obsidian with embedded Tomcat =

If you selected the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack during installation, use the '''webObsidian''' scripts to start and stop Obsidian.

From the Obsidian install directory:

webObsidian.bat start scheduler
(Unix: ./webObsidian.sh start scheduler)

For standalone admin only:

webObsidian.bat start adminOnly

Stop:

webObsidian.bat stop
(Unix: ./webObsidian.sh stop)

Default HTTP port is '''8080'''. To change ports, pass '''-Dembedded.tomcat.http.port''', '''-Dembedded.tomcat.stop.port''', and '''-Dembedded.tomcat.stop.key''' as JVM arguments before starting.

On Linux you can also run Obsidian as a user-level systemd service, or launch it from a desktop entry, instead of calling the script by hand — see [[#Running_Obsidian_as_a_Linux_user_service|Running Obsidian as a Linux user service]] below.

If you are deploying '''obsidian.war''' to your own external servlet container instead, refer to your container's deployment documentation.

= Running Obsidian as a Linux user service =

On Linux, an embedded Tomcat pack can install a user-level systemd unit and a desktop entry — see [[Installation_Guide#Linux_desktop_and_systemd_integration|Linux desktop and systemd integration]] for the installer option and the manual '''linux/install-embedded-linux-integration.sh''' script. Installing those files does not enable or start anything, so enable the service yourself:

systemctl --user enable --now obsidian-embedded@scheduler.service

Check and stop it with:

systemctl --user status obsidian-embedded@scheduler.service
systemctl --user stop obsidian-embedded@scheduler.service

''./webObsidian.sh stop'' also stops a service-started instance. Do '''not''' run ''./webObsidian.sh start scheduler'' by hand while the service is running — both bind the same HTTP and stop ports.

== Ports ==

The unit and the desktop entry both invoke '''webObsidian.sh''', so they use the script's ports: HTTP '''8080''' and stop port '''9597'''. Passing ''-Dembedded.tomcat.*'' on a ''java'' command line has no effect on the service — edit the values in '''webObsidian.sh''' before enabling it.

== Running without an active login session ==

This is a '''user''' service, so by default it runs only while that user has a login session and stops at logout. To keep Obsidian running after logout and start it at boot, enable lingering for the account:

loginctl enable-linger <nowiki><username></nowiki>

If you want Obsidian to run as a system service independent of any user account, write your own unit under ''/etc/systemd/system/'' using '''linux/obsidian-embedded@.service.in''' as a starting point.

== Standalone admin installs ==

The generated unit runs '''webObsidian.sh start scheduler'''. If you installed only the '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack, change ''ExecStart'' in ''~/.config/systemd/user/obsidian-embedded@scheduler.service'' to use '''start adminOnly''' before enabling the service.

== Removing the integration ==

systemctl --user disable --now obsidian-embedded@scheduler.service
rm ~/.config/systemd/user/obsidian-embedded@scheduler.service
rm ~/.local/share/applications/obsidian-embedded.desktop
systemctl --user daemon-reload

The same details ship as '''linux/README-linux-integration.md''' in your install directory.

= Embedding Obsidian & Customizing Artifacts =

The Obsidian scheduler process needs Java classpath access to your jobs so it can detect valid jobs and execute them. This requires a bit of customization before you are ready to run custom Java jobs. If you still haven't created your custom jobs, consult [[Implementing Jobs]] before proceeding. If you only intend to use [[Scripting Jobs]], customization will not be required and you can skip to [[#Deployment|Deployment]].

If you want to embed Obsidian into your application or need to deploy jobs and their dependent libraries to the generated Obsidian artifacts, follow the steps in the appropriate sections below.

Note that only Obsidian scheduler processes need to be customized to include your job code. The admin web application itself does not require classpath access to your jobs.

== Embedding Obsidian - Importing Libraries and Properties File ==

To embed Obsidian, you will need to update your application build to bring in the JAR files it requires, along with the Obsidian properties file. Simply follow these steps:

# Import all required [[Advanced_Configuration#Dependent_Libraries|Obsidian JAR files]] into your project and reference them in your build files.
#* These can be obtained from the <code>standalone</code> directory of your installation. Make sure you '''exclude''' <code>obsidian-(yaml/properties)-configuration.jar</code>
#* Ensure your Maven, Gradle or Ant files are updated to include all required libraries in your build, along with your IDE.
# Make a copy of <code>com.carfey.yaml.reference</code> or <code>com.carfey.properties.reference</code> from your installation with the <code>.reference</code> suffix removed, and add it to your project's classpath.
#* This is typically just a matter of adding it to your project's resources directory.
#* From now on, you can update this file to change the various configuration options such as database connection details.
#* You may wish to leave this file out of source control and let developers configure their own installations. However, any running Obsidian instance will need access to a valid [[Advanced_Configuration#Properties.2FYaml_File|properties file]].

'''Maven users:''' Note that we do not publish Maven artifacts for Obsidian, so you will not be able to include them by referencing a public repository.

== Adding Custom Jobs to Standalone Scheduler ==

In order for the standalone scheduler to detect and execute custom jobs written in Java, you will need to ensure Obsidian's classpath contains the compiled job code, along with its dependencies.

To do so, you need to perform just one step before starting the standalone scheduler:

# Copy JAR files containing custom Obsidian jobs and all runtime dependencies to the <code>standalone</code> directory in your installation.
#* These JARs should be alongside <code>obsidian.jar</code>.
#* All JAR files in this directory will be automatically added to the classpath when run via the <code>standaloneObsidian.sh</code> or <code>standaloneObsidian.bat</code> scripts.

== Adding Custom Jobs to Combined Scheduler and Admin Web Application ==

In order for the combined scheduler and admin web application to detect and execute custom jobs written in Java, you will need to ensure Obsidian's classpath contains the compiled job code, along with its dependencies.

To do so, you need to perform just one step before deploying the Obsidian WAR file:

# Copy JAR files containing custom Obsidian jobs and all runtime dependencies to the <code>WEB-INF/lib</code> directory within the WAR archive.
#* These JARs should be alongside <code>obsidian.jar</code>.
#* WAR files use the ZIP format and can be extracted and recompressed with normal ZIP tools or the JDK <code>jar</code> utility.

== Updating the Properties File in Admin Web Applications ==

''Note that updating the WAR artifact is not necessary to perform properties file changes when using an external properties file as described [[Advanced_Configuration#Properties_File|here]].''

If you need to change [[Advanced_Configuration#Properties_File|configuration properties]] for a standalone admin web application or combined scheduler and admin web application, follow these steps:

# Obtain the WAR artifact from your installation that requires changes. This is either <code>obsidian.war</code> or <code>standaloneObsidianAdmin.war</code>.
# Extract the WAR file to a clean directory.
# Edit the <code>com.carfey.(yaml/properties)</code> file within the subdirectory <code>WEB-INF/classes</code> and save your changes.
# Rebundled the WAR artifact using a zip utility or the JDK <code>jar</code> utility.
#* Some zip utilities such as 7Zip will allow you to edit files within an archive directly without the previous steps. It is generally safe to do so.

= Deployment =

You are now ready to deploy your scheduler and/or admin web application.

== Embedded Scheduler ==

When Obsidian is embedded, there is no separate deployment process. However, you will need to start and stop Obsidian with your application. If you are using Spring, we recommend you use our [[Spring Integration]] instead, which will automatically start and stop the scheduler for you.

During your application startup, once it is fully initialized (or as close as possible), start Obsidian, and save a reference to the returned result so you can shut it down later:
<pre>
// This will start the scheduler on the first call to get().

com.carfey.ops.job.SchedulerStarter starter = com.carfey.ops.job.SchedulerStarter.get(com.carfey.ops.job.SchedulerStarter.SchedulerMode.EMBEDDED);

// ...

// Later, we need to gracefully shut down the scheduler
starter.shutDown();

</pre>

This will run Obsidian's scheduler process, but will not include any of the web application or the REST API. This functionality is provided by the admin web application.

== Standalone Admin Web Application ==

To deploy the standalone admin web application, simply deploy the <code>standaloneObsidianAdmin.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war" or "obsidian.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.

'''Note:''' If you selected the '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack, you can use the '''webObsidian''' scripts included in your installation instead of deploying the WAR. This will make the application accessible at http://localhost:8080.

* To start
** Linux: <code>./webObsidian.sh start adminOnly</code>
** Windows: <code>webObsidian.bat start adminOnly</code>
* To stop
** Linux: <code>./webObsidian.sh stop</code>
** Windows: <code>webObsidian.bat stop</code>

'''Security Note:''' By default, the admin web application allows non-secure connections. If you wish to force secure connections through HTTPS, you can edit the web.xml in your war and uncomment the <security-constraint> element in the file. This will force all requests to redirect to an encrypted connection. For details on setting up SSL on your servlet container, refer to its documentation.

== Standalone Scheduler ==

To deploy and run the standalone scheduler, you may use the provided scripts in your installation directory:
* Linux: <code>./standaloneObsidian.sh start</code>
* Windows: <code>standaloneObsidian.bat start</code>

You should always stop Obsidian gracefully when possible by using:
* Linux: <code>./standaloneObsidian.sh stop</code>
* Windows: <code>standaloneObsidian.bat stop</code>

Both the start and stop commands may be supplied an additional argument to override the <code>listenerPort</code> which defaults to 10451.

Rather than use one of the provided scripts, you can invoke the equivalent Java command:

<pre>
java com.carfey.ops.job.SchedulerStarter start <listenerPort>
java com.carfey.ops.job.SchedulerStarter stop <listenerPort>
</pre>

== Combined Scheduler and Admin Web Application ==

To deploy the combined scheduler and admin web application, simply deploy the <code>obsidian.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.

'''Note:''' If you selected the '''Obsidian Embedded Tomcat JAR''' pack, you can use the '''webObsidian''' scripts included in your installation instead of deploying the WAR. This will make the web application accessible at the URL http://localhost:8080.

* To start
** Linux: <code>./webObsidian.sh start scheduler</code>
** Windows: <code>webObsidian.bat start scheduler</code>
* To stop
** Linux: <code>./webObsidian.sh stop</code>
** Windows: <code>webObsidian.bat stop</code>

'''Security Note:''' By default, the admin web application allows non-secure connections. If you wish to force secure connections through HTTPS, you can edit the web.xml in your war and uncomment the <security-constraint> element in the file. This will force all requests to redirect to an encrypted connection. For details on setting up SSL on your servlet container, refer to its documentation.

== Embedding the Obsidian Web Application in Another Web Application ==

We do not generally recommend attempting to merge the Obsidian admin web application with another servlet web application, but it can be done by following these steps:

To embed the full Obsidian web application in an existing web application, you will need to extract the necessary sections from the <code>WEB-INF/web.xml</code> file in the <code>obsidian.war</code> file and merge them into your application's <code>web.xml</code> file. This includes all "listener", "servlet", "servlet-mapping", "jsp-config", "filter", "filter-mapping" elements, and optionally "welcome-file-list" and "error-page" elements. Ensure that all servlet paths are maintained. If you are using a different servlet specification version, you may need to update the mappings to the appropriate format.

Note the use of our <code>com.carfey.ops.servlet.StartupShutdownListener</code> which takes care of starting up the scheduler instance and using the web container's default shutdown mechanism to ensure graceful shutdown. This listener will start Obsidian's scheduler process and initialize the Obsidian web application.

If you wish to embed Obsidian's web application without the scheduler running, include the following parameter element in your <code>web.xml</code>:

<pre>
<context-param>
<param-name>schedulerEnabled</param-name>
<param-value>false</param-value>
</context-param>
</pre>

== Additional Deployment Details ==

=== Classpath Notes ===

To run a scheduler with your custom code and jobs, you need to ensure the scheduler process classpath includes your code packaged into JAR files, as described [[#Embedding_Obsidian_.26_Customizing_Artifacts|above]].

If a compiled job is updated, you will have to restart your application or the servlet container after deploying updated jars, unless you are using [[Job Forking]].

=== Setting Host Names ===
Obsidian instances will automatically assign themselves host names if no host name is explicitly set, but you may wish to give them explicit names to make scheduling and monitoring simpler.

If you wish to assign explicit names, simply set the Java system property <code>schedulerDesignation</code> to the host name of your choice. For example, if starting an instance using the standalone scheduler using <code>java</code> directly, simply add the value <code>-DschedulerDesignation=myHostName</code> to the end of the command.

You may also use a properties file setting for the host name as detailed in [[Advanced Configuration]].

=== Disabling Automatic Database Updates ===

Obsidian automatically applies schema updates and data upgrades to its database on startup. In some cases, it may be desirable to disable this once the database has been fully initialized and upgrades to new versions are not going to be deployed. For example, you may wish to run Obsidian with a user who does not have privileges to modify the database schema.

To do so, you can either set a Java system property, or if you are using the admin web application WAR, you can add a setting to your <code>WEB-INF/web.xml</code> within the archive.

As a system property:

<pre>
-DstartupRunnerClass=com.carfey.ops.run.NullRunner
</pre>

In <code>WEB-INF/web.xml</code>, after any <code>listener</code> elements:
<pre>

<context-param>
<param-name>startupRunnerClass</param-name>
<param-value>com.carfey.ops.run.NullRunner</param-value>
</context-param>

</pre>

=== Disabling DDL Updates ===

It may also be helpful to apply schema updates (DDL) outside Obsidian through a privileged account, but allow Obsidian upgrades to make the necessary data initialization/modifications. This can be done using a '''skipDDL''' configuration property documented under [[Advanced_Configuration#Miscellaneous_Properties | Advanced Configuration]].

=== Disabling Job Scheduling in the Web Application ===

If you have combined scheduler and admin web application WAR already built, you can easily tweak it to disable the scheduler process.

Simply add the following to your <code>WEB-INF/web.xml</code> within the WAR archive after any <code>listener</code> elements:

<pre>

<context-param>
<param-name>schedulerEnabled</param-name>
<param-value>false</param-value>
</context-param>

</pre>

= You’re Good to Go! =

You're now ready to log into the web application and start scheduling jobs! The URL you use to access Obsidian will depend on how it's been deployed, but will typically be something like http://localhost/obsidian, or http://localhost/standadminObsidianAdmin.

'''Default User:''' Each Obsidian installation using native authentication starts with a single default user named ''admin'' with password ''changeme''. You should change this after your first log in. See [[Admin_User_Management|User Management]] for how to change a user's password.

At this point we suggest you play around with the admin web application. Many screens offer inline help. Otherwise, you can refer to our [[Admin Web Application Guide]].

To get started writing jobs that you can run in Obsidian, see [[Implementing_Jobs|Implementing Jobs]].

See the '''[[User Guide]]''' if you have questions or wish to explore what Obsidian offers.

FAQ

2026-07-31T14:49:51Z

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

Some of the most common questions we receive about Obsidian are below. They range from questions about how Obsidian works, to how you go about taking advantage of different features. If you have a question not asked below, feel free to [[Contact_the_Obsidian_Scheduler_Team|contact us]]. During business hours, we usually have free support chat available which is linked on the left of the page.

If you are having a specific issue, see [[Troubleshooting]].

== What is Obsidian exactly? ==
Obsidian is a Java-based task/job scheduler. At its most basic level, it allows you to run jobs at certain recurring times, like Quartz or cron4j, but it goes well beyond what either provides. It has native, configuration-free clustering, which provides fail-over and load-sharing. In addition, it provides features like a full UI, job chaining, and event notification which are lacking in other popular schedulers.

Obsidian consists of two main parts - a scheduler service and an admin web application which provides a UI to configure and monitor the scheduler's operation. These two features can be run together or separately (see [[Getting Started]]).

== How do I set up Obsidian? ==
Check our [[Getting Started]] guide, or email us at our [https://web.obsidianscheduler.com/support/ support address].

== Is it free? ==
We grant free single-node licenses which you can use forever free of charge ([https://web.obsidianscheduler.com/download/ download here]). In addition, you get a second node that you can use for one year free of charge to allow you to evaluate Obsidian clustering.

For additional licenses, including clustering nodes, the cost starts at $649 CAD each. For example, if you want to run a 2-node cluster, after the first year you would need to purchase a single $649 license. This license gives you access to free support and all future versions of the product.

Obsidian also provides other licensing options which can be found on our [https://web.obsidianscheduler.com/pricing/ main site].

== Is it open source? ==
Obsidian is currently not open-source. While we support the open-source movement and have contributed to it, we have chosen not to open-source Obsidian so we could help fund our development and support costs.

== What technologies does Obsidian use? ==
Obsidian is currently built on Java 11, and will run on newer versions as well. The admin web application requires a servlet container, such as Tomcat or Jetty. Obsidian also requires a database such as MySQL or Oracle, where scheduling data is stored. Obsidian has a small set of [[Advanced_Configuration#Dependent_Libraries|library dependencies]] (.jar files), selected to avoid conflicts with our users' own libraries. See [[Getting Started]] for details on which versions of servlet containers and database platforms are supported.

== Why should I use Obsidian? ==
Obsidian provides a complete end-to-end solution for job scheduling. Often developers focus on the task in front of them and forget about the long-term costs of operations and maintenance. Job scheduling is about more than task execution - monitoring, recovery, notification, etc. are all crucial features to enterprise- or smaller-level infrastructures.

Obsidian is designed to reduce implementation and operations costs while also facilitating development. Our team's years of experience in the field have helped us pinpoint the common issues organizations have with job schedulers and design a product that eliminates those problems.

== How is Obsidian different from Quartz? ==
Quartz is mainly an embedded jar that provides you with the ability to schedule recurring jobs. Developers have to integrate it into their application and layer on code to do things like event notifications, job chaining, etc. In addition, database usage and clustering require additional configuration and, in our opinion, the available UIs are not complete. Quartz focuses primarily on the job execution side of scheduling, and provides extension points for developers to customize behaviour according to their needs.

Conversely, Obsidian is designed from the ground-up to provide clustering, chaining, a complete UI, event notifications, real-time administration, etc. right out of the box. While Obsidian is also embeddable, it is intended to provide a complete solution to job scheduling, including monitoring, high availability, and recovery. It is designed based on years of industry experience dealing with issues of reliability and operations issues. Obsidian doesn't just make your developers more productive, it eliminates work for your whole IT department by making the information they need to troubleshoot and resolve issues quickly available at a moment's notice.

== How does clustering work? ==
Obsidian's [[Clustering|clustering]] works by coordinating effort of various nodes through a central relational database such as MySQL. Each node periodically attempts to claim its share of work off of a work queue. The algorithm that performs this takes into account how many other nodes are running, and how many jobs need to be run at the current time in order to provide load balancing. That is one key difference in Obsidian since it values load-sharing over second-level precision, since most applications don't require it. Quartz, by contrast, does clustering by having all nodes immediately try to claim a job for execution, which can result in one node claiming multiple jobs while others remain idle.

You can add new cluster nodes at any time and they will automatically join the pool, and the load-sharing and scheduling algorithm will adapt right away.

== What's Obsidian's performance like and how does it scale? ==
Whether you are running a single node or using multiple clustered nodes, Obsidian is very efficient at scheduling and execution. We have successfully run thousands of jobs a minute on basic developer hardware without issue. Typically, our users are running a tiny fraction of that number, and we haven't received any reports of poor performance due to scheduling activity.

It is unlikely Obsidian's scheduling activity will have much of a performance impact, so most of our users are constrained by the resource requirements of their actual job code.

Obsidian can scale to many nodes without significant performance degradation. Most customers use 1 or 2 nodes, but running 10 nodes or more should pose no issue.

== How do I get my job application code running in the Obsidian WAR or standalone scheduler? ==
If you are running a Obsidian as a standalone scheduler, embedded in your application, or in the WAR with scheduling enabled, you need to ensure your application JARs are on the classpath. In the WAR, this means adding your JAR files to the <code>WEB-INF/lib</code> directory. If you are embedding Obsidian, it will already have access to the application's classpath. If running as a standalone scheduler, you will have to add your application JARs to the <code>/lib</code> directory. Note that you must include any JARs that contain your job classes, as well as those that contain dependent code.

If you are running a standalone web application that does not have a scheduler running, you do not have to update its classpath with your compiled jobs, unless you are running a version older than 2.6, but there are steps you need to take which are outlined in [[Implementing_Jobs#Classpath_for_Building|Classpath for Building]].

== How do scripting jobs work? ==
Just configure your job in the [[Admin Jobs|Jobs]] screen (or use the REST API) by entering the script itself and any configuration parameters. Then, Obsidian will run the script as if it's any other job.

Note that scripts will inherently run slower than Java code, so these are better suited to ad hoc jobs or operations type tasks.

== How can I send SMS notifications? I only see email support. ==
Virtually all carriers provide email addresses which will forward automatically to SMS. For example, in the United States, SMS text messages can be sent by emailing <code>domestic-number@txt.att.net</code>. Here is a full listing of [http://en.wikipedia.org/wiki/List_of_SMS_gateways SMS gateways].

== Why isn't my job showing up? ==

Out of the box, Obsidian will display any previously scheduled jobs and Obsidian's bundled jobs. You can type in your class name as described in [[Admin_Jobs#Nickname.2C_Class_and_Folder|Admin Jobs]].

You can take advantage of our [[Spring_Integration|Spring Integration]]. Jobs that have been wired into your <code>ApplicationContext</code> will be available in the list.

You can also use Obsidian's [[Implementing_Jobs#Classpath_Scanning|classpath scanning]] as of '''Obsidian 2.0'''. Note that for this feature to work, the user account running Obsidian must have read privileges to the <code>WEB-INF</code> directory of Obsidian's deployment directory.

== What libraries is Obsidian dependent on? ==
See [[Advanced_Configuration#Dependent_Libraries|Advanced Configuration]] for dependency details.

== How do I deploy changes to my jobs? Can I hotswap JARs? ==
Yes you can! [[Job Forking]] needs to be enabled and configured for your deployed environment(s). Since support in Java for reloading class definitions is too unreliable to offer our users, Obsidian doesn't support it. But you can use the Job Forking feature to benefit from updates to deployed classes. Of course, this is simply for job execution. If the job's configuration support needs to change (new parameters, new description for UI, etc), you will need to deploy the change to each scheduler node and restart each one.

== How can I deploy job changes without redeploying or restarting Tomcat? ==
Apart from using the [[Job Forking]] support noted above, if you want truly dynamic job changes that even support configuration additions/removals, the best approach we can offer for this is to use our embedded [[Scripting_Jobs|Scripting]] support.

You can either use something like the included <code>GroovyJob</code>, or write your own job that executes a job script on the file system. The latter approach lets you just replace script files on demand. If you use this approach, you can define a Java job which accepts a defined script name parameter, which you can then execute using [https://docs.groovy-lang.org/latest/html/documentation/guide-integrating.html Groovy], or one of our other supported scripting languages.

== What level of scheduling precision does Obsidian support? ==

Obsidian supports minute-level scheduling precision. Obsidian values a balanced load-sharing algorithm over second-level precision.

== What about Daylight Savings Time (DST) or Summer Time? Will Obsidian handle these gracefully? ==

We recommend against using DST time zones on scheduling servers as you will perhaps experience undesired side effects. For example, if you have a job that you want to run every hour, when a spring DST change pushes the clock back an hour, Obsidian will not execute it again since the time has repeated and it is viewed as having already run. Or you have a job scheduled to run during a window that ends up not occuring because of an autumnal time forward adjustment. If DST is absolutely required, Obsidian does handle it gracefully but we recommend you [[Contact_the_Obsidian_Scheduler_Team|contact us]] to discuss the full implications.

== How do I change the time zone that Obsidian uses? ==

Obsidian uses the Java timezone, which can be specified using the Java system property <code>user.timezone</code>. For example, in Tomcat you can append <code>-Duser.timezone=Europe/Sofia</code> to <code>JAVA_OPTS</code> in your startup script (e.g. startup.sh).

'''Note: ''' Changing your timezone in an existing Obsidian installation can result in undefined behaviour if it has been running recently. We suggest setting your timezone before database creation when possible.

As of Obsidian 4.2.0, Time Zone ID may be specified in [[Cron]] patterns themselves to request that Obsidian run the job's scheduled according to the time of the TimeZone specified regardless of the default TimeZone of the Obsidian cluster.

== How do I upgrade from a previous version of Obsidian? ==
See our [[Upgrading_Obsidian|Upgrade]] page for details.

== What does the acronym "XYZ" mean? ==

Here are definitions of some acronyms commonly used in Obsidian's documentation.

* DB/DBMS - [https://en.wikipedia.org/wiki/Database Database Management System]: A software application which provides storage and querying of a collection of data.
* SQL [https://en.wikipedia.org/wiki/SQL Structured Query Language]: A language used to query databases.
* API - [https://en.wikipedia.org/wiki/Application_programming_interface Application Programming Interface]: A set of code routines, protocols or tools used to build software applications.
* REST [https://en.wikipedia.org/wiki/Representational_state_transfer Representational State Transfer]: A style of building a web-based API using common practices which is typically available over HTTP.
* HTTP [https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol Hypertext Transfer Protocol]: The communication protocol used for the world wide web and most REST APIs.
* JRE - [https://en.wikipedia.org/wiki/Java_(software_platform)#Java_Runtime_Environment Java Runtime Environment]: Java applications run through a JRE.
* JDK - [https://en.wikipedia.org/wiki/Java_Development_Kit Java Development Kit ]: A set of Java tools which provide development and compilation support. Some applications require a JDK to run.
* JAR - [https://en.wikipedia.org/wiki/JAR_(file_format) Java Archive File ]: The standard packaging unit for Java code libraries.
* WAR - [https://en.wikipedia.org/wiki/WAR_(file_format) Web Application Archive ]: A way to package Java web applications which can be deployed in a standardized way.
* JDBC - [https://en.wikipedia.org/wiki/Java_Database_Connectivity Java Database Connectivity]: An API which provides database access to Java applications.

== What is the default username and password? ==

Each Obsidian installation using native authentication (the default) starts with a single default user named '''admin''' with password '''changeme'''. You should change this after your first login. See [[User Management]] for how to change a user's password.

Embedded API

2026-07-31T14:49:51Z

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

Obsidian provides a unified Embedded API which contains all the same actions and semantics as the [[REST API]].

This API is accessible through Java, and can be used in software environments where the [[REST API]] is unavailable or undesired.

[https://web.obsidianscheduler.com/obsidianapi/ Javadoc] is also available to supplement this page.

==Overview==

The Obsidian Embedded API allows your application to access Obsidian data, schedule jobs, and control Obsidian in a variety of ways.

The API gives users the power to do things like initialize scheduled jobs at deployment time, trigger jobs based on events in your applications, and expose pieces of the Obsidian API in their own custom user interfaces.

== Accessing the API ==

The Embedded API is written in Java and can be be accessed within the context of a running Obsidian node, although the scheduler itself need not be active. You can even call API operations from within jobs, which you can use to get custom chaining or workflow behaviour, or update configuration on certain types of events detected in a job.

In addition, it can be embedded in applications that are not running Obsidian, simply by including Obsidian's [[Advanced_Configuration#Dependent_Libraries|dependent libraries]] and [[Advanced_Configuration#Properties_File|properties file]].

==Authorization==

The Embedded API is '''not secured''', though all actions accept an audit user which is linked to actions which modify Obsidian state. Any code that has access to the Obsidian database via its defined credentials can manipulate Obsidian job configurations.

== Transactions ==

By default, when you invoke actions within the API, each individual call is in its own transaction which is committed when successful, and rolls back on failure.

However, you can wrap multiple API calls into a single transaction, so you get one unit of work which either is fully committed or rolled back. An example is shown below. For full semantics, see [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/AbstractAPIManager.html#withTransaction(java.lang.String,java.util.concurrent.Callable) AbstractAPIManager.withTransaction].

<pre>
final String auditUser = "Bob";

List<HostDetail> updated = new HostManager().withTransaction(auditUser, new Callable<<HostDetail>>() {

public List<HostDetail> call() throws Exception {

// disable some hosts in an atomic manner (does not have to be the same instance of even type of Manager class)
HostDetail hostA = new HostManager().updateHost("hostA", new HostUpdateRequest().withEnabled(false), auditUser );
HostDetail hostB = new HostManager().updateHost("hostB", new HostUpdateRequest().withEnabled(false), auditUser );

// this is within the same transaction
new JobManager().resubmitRuntime(jobToResubmit, auditUser);

return Arrays.asList(hostA, hostB);
}
});

System.out.println("Updated hosts: " + updated);
</pre>

==API Basics ==
The API is exposed through <code>Manager</code> classes in the package [https://web.obsidianscheduler.com/obsidianapi/index.html?com/carfey/ops/api/embedded/package-summary.html com.carfey.ops.api.embedded]:
* <code>JobManager</code> - Create and manage jobs, job conflicts and chaining.
* <code>RuntimeManager</code> - List job runtime history, resubmit jobs, preview scheduled times, etc.
* <code>HostManager</code> - Manage and list active scheduling hosts (i.e. nodes).
* <code>CustomCalendarManager</code> - Manage custom calendars.

To invoke an API method, simply create a new Manager instance, and invoke the appropriate method:

<pre>
RuntimeListing recentRuntimes = new RuntimeManager().listRuntimes(new RuntimeListingParameters());
</pre>

You can reuse manager instances if you like, but it is ultimately up to your preference.

=== Exceptions ===
API calls generally throw three types of exceptions:

* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/suite/action/ValidationException.html ValidationException] - some sort of validation error occurred.
* [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] - The requested entity could not be found by the ID supplied.
* All other Exception types - some other type of error that you probably can't do much with (database issues, etc.).

When integrating the API into your application, you may wish to apply appropriate handling to <code>ValidationException</code> and <code>MissingEntityException</code>, but otherwise you can treat exceptions as a generic server errors.

== Enumerations ==

Below are valid values for commonly used fields in the API. These are also used by the [[REST API]].

Corresponding Java enums can be found in the package [https://web.obsidianscheduler.com/obsidianapi/index.html?com/carfey/ops/api/enums/package-summary.html com.carfey.ops.api.enums].

'''Job [[Admin_Jobs#State|State]]'''
* <code>ENABLED</code>
* <code>DISABLED</code>
* <code>UNSCHEDULED_ACTIVE</code>
* <code>CHAIN_ACTIVE</code>
* <code>AD_HOC_ACTIVE</code>

'''Job History [[Job_Features#Execution_Statuses | Status]]'''
* <code>READY</code>
* <code>RUNNING</code>
* <code>COMPLETED</code>
* <code>FAILED</code>
* <code>MISSED</code>
* <code>DIED</code>
* <code>CONFLICTED</code>
* <code>OVERLAPPED</code>
* <code>ABANDONED</code>
* <code>CONFLICT_MISSED</code>
* <code>CHAIN_SKIPPED</code>
* <code>PENDING</code>

'''Job Submission Mode '''
* <code>CHAIN_SUBMISSION</code>
* <code>CONFLICTED_RECOVERY</code>

'''Job [[Job_Features#Recovery | Recovery Type]]'''
* <code>NONE</code>
* <code>LAST</code>
* <code>ALL</code>
* <code>CONFLICTED</code>

'''Job Parameter Type'''
* <code>STRING</code>
* <code>INTEGER</code>
* <code>LONG</code>
* <code>DECIMAL</code>
* <code>BOOLEAN</code>
* <code>CLASS</code>

'''Job Chain [[Job_Features#Execution_Statuses | Status]]'''
* <code>ABANDONED</code>
* <code>COMPLETED</code>
* <code>CONDITIONAL</code>
* <code>DIED</code>
* <code>FAILED</code>
* <code>MISSED</code>
* <code>OVERLAPPED</code>
* <code>CHAIN_SKIPPED</code>

'''Job Chain/Conditional Job Notification Operator'''
* <code>EQUALS</code>
* <code>NOT_EQUALS</code>
* <code>IN</code>
* <code>NOT_IN</code>
* <code>EXISTS</code>
* <code>NOT_EXISTS</code>
* <code>REGEXP</code>
* <code>STARTS_WITH</code>
* <code>ENDS_WITH</code>
* <code>CONTAINS</code>
* <code>GREATER_THAN</code>
* <code>LESS_THAN</code>
* <code>GREATER_THAN_OR_EQUAL</code>
* <code>LESS_THAN_OR_EQUAL</code>

'''Subscription/Log [[Event_Notifications#Category-Based_Subscriptions | Category]]'''
* <code>DASHBOARD</code>
* <code>DISPATCH</code>
* <code>JOB</code>
* <code>JOB_CHAIN</code>
* <code>JOB_CONFIG</code>
* <code>JOB_QUEUER</code>
* <code>JOB_RECOVERY</code>
* <code>JOB_RUN</code>
* <code>JOB_SPAWNER</code>
* <code>LICENCE</code>
* <code>SYSTEM_PARAMETER</code>
* <code>QUEUE</code>

'''Subscription/Log Level'''
* <code>FATAL</code>
* <code>ERROR</code>
* <code>WARNING</code>
* <code>INFO</code>
* <code>DEBUG</code>
* <code>TRACE</code>

'''User Role'''
* <code>ADMIN</code>
* <code>WRITE</code>
* <code>OPERATOR</code>
* <code>AUTHOR</code>
* <code>API</code>
* <code>LIMITED_READ</code>
As of ''Obsidian 5.0.0'', these are class constants instead of enums to support [[Admin_User_Management#Job_Folder_Rights|dynamic roles]].

'''Subscription Job Status'''
* <code>COMPLETED</code>
* <code>CONDITIONAL</code>
* <code>DIED</code>
* <code>FAILED</code>
* <code>RECOVERY</code>

'''Sort Direction'''
* <code>ASC</code>
* <code>DESC</code>

'''Event Hook Action'''
* <code>PAUSE</code>
* <code>RESUME</code>

'''Job Stats [[Job_Features#Execution_Statuses | Status]]'''
* <code>COMPLETED</code>
* <code>FAILED</code>
* <code>MISSED</code>
* <code>DIED</code>
* <code>OVERLAPPED</code>
* <code>ABANDONED</code>
* <code>CONFLICT_MISSED</code>
* <code>CHAIN_SKIPPED</code>

'''Job Stats Unit'''
* <code>SECONDS</code>
* <code>MINUTES</code>
* <code>HOURS</code>

'''Job Stats Duration'''
* <code>DAY</code>
* <code>TWO_DAY</code>
* <code>THREE_DAY</code>
* <code>FIVE_DAY</code>
* <code>WEEK</code>
* <code>MONTH</code>
* <code>TWO_MONTH</code>
* <code>THREE_MONTH</code>
* <code>SIX_MONTH</code>
* <code>YEAR</code>

= JobManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html JobManager] is used to manage job configurations, conflicts and chaining. If you are looking for ways to view or manage job runtimes, see [[#RuntimeManager API|RuntimeManager]].

== List Jobs ==

You can list or search existing jobs using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobs(com.carfey.ops.api.bean.job.JobListingParameters) JobManager.listJobs()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobListingParameters.html JobListingParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobListing.html JobListing].

You can limit the returned jobs by providing a <code>JobListingParameters</code>.

'''JobListingParameters Fields'''

{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| activeStatuses || N || Restricts the preview to the selected a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobStatus.html JobStatus] values
|-
| effectiveDate || N || If querying by activeStatuses, this allows you to indicate what point in time to compare against the job status. Defaults to next minute.
|-
| hosts || N || If specified, only jobs that run on the specified host name(s) are included.
|-
| nicknames || N || If specified, only jobs matching the supplied nicknames are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs containing the word "order", use "%order%".
|-
| jobClasses || N || If specified, only jobs matching the supplied job class are returned. Wildcards may be included to support partial matches by using %, or exact literals can be used. For example, to find all jobs with job classes containing the word "Export", use "%export%". Supports multiple values. ''Available from version 3.4.0 forward.''
|-
| folders || N || If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string or null is supplied, jobs with no folder will be returned. Supports multiple values. ''Available from version 4.1.0 forward.''
|-
| filterParameters || N || If specified, values supplied in this map can be used to match on job parameter values, either custom or defined. If multiple values for the same name (i.e. key) are supplied, a job is matched if any of its configured values match one of the supplied values. If multiple names are used, each must have a matching value for the job to be returned.

'''Usage note:''' This can be used to tag jobs with searchable metadata by configuring custom parameters. For example, if jobs belong to logical groups, you may create a custom parameter on applicable jobs named "group" and use ''filterParameters'' to locate jobs belonging to specific groups, such as "customer" or "order".
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_jobs|GET a list of jobs]]

== Get a Job's Details ==

To get full job information, including all historical schedules and parameter information, call [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#getJob(long) JobManager.getJob()] with the appropriate job ID. The method will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_job|GET details of an existing job]]

== Add a Job ==

You can add a new job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#addJob(com.carfey.ops.api.bean.job.JobCreationRequest,java.lang.String) JobManager.addJob()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobCreationRequest.html JobCreationRequest]. The method will return the job as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail].

When you create the job, you provide an initial schedule.

'''Note:''' When supplying effective and end dates for schedules, seconds must be omitted. To do so, use <code>com.carfey.jdk.lang.DateTime.clearSeconds()</code>, which returns a copy of the date with seconds removed.

'''JobCreationRequest Fields '''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobClass || Y || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || Y || Unique nickname for the job. Max 255 chars.
|-
| folder|| N || Folder in which to place the job. Paths are separated by forward-slashes. Back-slashes are automatically converted to forward-slashes, and leading or trailing slashes are removed. Max 255 chars. ''Available from version 4.1.0 forward.''
|-
| pickupBufferMinutes || N || Pickup buffer minutes which defaults to 2. Integer greater than zero.
|-
| recoveryType || Y || The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobRecoveryType.html JobRecoveryType] to use for the job.
|-
| state || Y || Initial schedule's [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobStatus.html JobStatus].
|-
| schedule || Y/N || If state is <code>ENABLED</code>, the mandatory cron-style schedule for the job. If not <code>ENABLED</code>, this should be omitted. You may specify multiple cron patterns delimiting them with a semi-colon.
|-
| effectiveDate || N || Optional effective date for the initial schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is <code>DISABLED</code>.
|-
| endDate || N || Optional end date for the initial schedule, with no seconds specified. If set, the job will become <code>DISABLED</code> after this date passes.
|-
| customCalendarId || N || Optional custom calendar id.
|-
| hosts || N || Zero or more host names that this job may run on. If none set, the job may run on any host.
|-
| minExecutionDuration || N || The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
|-
| maxExecutionDuration || N || The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
|-
| autoInterrupt || N || Boolean indicating whether auto interrupt functionality is desired. May only be true when the job is an interruptable job and a maxExecutionDuration has been specified. Defaults to false.
|-
| autoRetryCount|| N || Number of auto retries on non-interrupted execution failure. Defaults to 0, which means none are desired.
|-
| autoRetryInterval|| N || Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created. Defaults to false.
|-
| parameters || Y/N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Parameter definitions must have values for <code>name</code>, <code>type</code> and <code>value</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html ParameterType]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. Values may contain global parameter references (e.g. <code>{{globalParameterName}}</code>).
|}

REST equivalent: [[REST_Endpoints#POST_a_new_job|POST a new job]]

== Update a Job ==

You can update an existing job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateJob(long,com.carfey.ops.api.bean.job.JobUpdateRequest,java.lang.String) JobManager.updateJob()], which accepts a job ID and a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobUpdateRequest.html JobUpdateRequest]. The method will return the new state of the job as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

This does not support schedule changes or additions. For schedule changes, see [[#Add_a_New_Schedule_to_a_Job|Add a New Schedule to a Job]].

This method will only update fields that are supplied in the <code>JobUpdateRequest</code>. You may update one or more fields as desired.

'''JobUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobClass || N || Fully qualified class name of the job. Max 255 chars.
|-
| nickname || N || Unique nickname for the job. Max 255 chars.
|-
| folder|| N || Folder in which to place the job. Paths are separated by forward-slashes. Back-slashes are automatically converted to forward-slashes, and leading or trailing slashes are removed. Max 255 chars. ''Available from version 4.1.0 forward.''
|-
| pickupBufferMinutes || N || Pickup buffer minutes. Integer greater than zero.
|-
| recoveryType || N || The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobRecoveryType.html JobRecoveryType] to use for the job.
|-
| hosts || N || Zero or more host names that this job may run on. If none set, the job may run on any host.
|-
| minExecutionDuration || N || The minimum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "15m".
|-
| maxExecutionDuration || N || The maximum expected job runtime. Format is an integer greater than zero immediately followed by "s", "m" or "h". Example: "2h".
|-
| autoInterrupt || N || Boolean indicating whether auto interrupt functionality is desired. May only be true when the job is an interruptable job and a maxExecutionDuration has been specified. Defaults to false.
|-
| autoRetryCount || N || Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| chainAll || N || Boolean indicating whether all chained instances are triggered when job is currently running. Otherwise, only one newly chained record is created.
|-
| parameters || N || Zero or more parameter definitions. If a job defines required parameters with the <code>@Configuration</code> annotation, a job will fail to create unless they are supplied. Otherwise, this field is optional. Note that a null value will result in existing parameters being preserved, while an empty list is considered replacing existing parameters. Parameter definitions must have values for <code>name</code>, <code>type</code> and <code>value</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html ParameterType]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. Values may contain global parameter references (e.g. <code>{{globalParameterName}}</code>).
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_job|PUT updates to an existing job]]

== Delete a Job ==

You can delete an existing job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#deleteJob(long,boolean,java.lang.String) JobManager.deleteJob()], which accepts a job ID and ''cascade'' flag. The method will return the final state of the job before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

'''Parameters'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| cascade|| Y || If set to true, all job conflict and chain definitions for this job will also be deleted. If set to false, any existing job conflicts or chain definitions will cause the request to fail.
|}

REST equivalent: [[REST_Endpoints#DELETE_an_existing_job|DELETE an existing job]]

== List a Job's Schedules ==

You can access the full history of a job's schedules via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobSchedules(long) JobManager.listJobSchedules()] which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobScheduleListingParameters.html JobScheduleListingParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobScheduleListing.html JobScheduleListing].

Note that the full schedule history can also be obtained via the schedules field of the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobDetail.html JobDetail] returned by [[#Get_a_Job's_Details|JobManager.getJob()]].

REST equivalent: [[REST_Endpoints#GET_a_list_of_an_existing_job.27s_schedules|GET a list of an existing job's schedules]]

== Add a New Schedule to a Job ==

You can add a new schedule to a job via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#addJobSchedule(long,com.carfey.ops.api.bean.schedule.ScheduleCreationRequest,java.lang.String) JobManager.addJobSchedule()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleCreationRequest.html ScheduleCreationRequest].

This may be used to immediately change a job's scheduling state, or to schedule a future change. Creating a new schedule automatically splits and merges existing schedules. For example, if you have an enabled job and you disabled it for a day, the job will automatically re-enable after that day.

'''Note:''' When supplying effective and end dates for schedules, seconds must be omitted. To do so, use <code>com.carfey.jdk.lang.DateTime.clearSeconds()</code>, which returns a copy of the date with seconds removed.

'''ScheduleCreationRequest Fields '''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| state || Y || The schedule's [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobStatus.html JobStatus].
|-
| schedule || Y/N || If state is <code>ENABLED</code>, the mandatory cron-style schedule for the job. If not <code>ENABLED</code>, this should be omitted. You may specify multiple cron patterns delimiting them with a semi-colon.
|-
| effectiveDate || N || Optional effective date for the schedule, with no seconds specified. If not set, this defaults to next minute. Until this date is reached, the job is <code>DISABLED</code>.
|-
| endDate || N || Optional end date for the schedule, with no seconds specified. If set, the job will become <code>DISABLED</code> after this date passes.
|-
| customCalendarId || N || Optional custom calendar for schedule.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_schedule_to_an_existing_job|POST a new schedule to an existing job]]

== List Job Chains ==

You can list or search existing job chains using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listChains(com.carfey.ops.api.bean.job.JobChainListingParameters) JobManager.listChains()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainListingParameters.html JobChainListingParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainListing.html JobChainListing].

You can limit the returned job chains by providing a <code>JobChainListingParameters</code> instance with the fields below.

'''JobChainListingParameters Fields'''

{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Limits results to those matching the active flag (true/false).
|-
| sourceJobId || N || Limits results to those matching the supplied source job ID.
|-
| targetJobId || N || Limits results to those matching the supplied target job ID.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_chains| GET a list of job chains]]

== Add a Job Chain ==

You can add a new job chain using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#addChain(com.carfey.ops.api.bean.job.JobChainUpdateRequest,java.lang.String) JobManager.addChain()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainUpdateRequest.html JobChainUpdateRequest]. The method will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChain.html JobChain].

'''JobChainUpdateRequest Fields'''

{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| sourceJobId || Y || ID of the source job.
|-
| targetJobId || Y || ID of the target job to chain
|-
| schedule || N || Optional schedule that constrains when the job chain triggers.
|-
| triggerStates || Y || One or more [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobChainStatus.html JobChainStatus]. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.
|-
| resultConditions || Y/N || Conditions based on job results that apply to the <code>CONDITIONAL</code> trigger state. Must be supplied only when that state is used, in which case at least one condition must be supplied. Result conditions consist of a <code>variableName</code>, an <code>operator</code> as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobChainConditionOperator.html JobChainConditionOperator], and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_job_chain| POST a new job chain]]

== Update a Job Chain ==

You can add update an existing job chain using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateChain(long,com.carfey.ops.api.bean.job.JobChainUpdateRequest,java.lang.String) JobManager.updateChain()], which accepts a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChainUpdateRequest.html JobChainUpdateRequest]. The method will return the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChain.html JobChain].

The format of <code>JobChainUpdateRequest</code> is identical to that of [[#Add_a_Job_Chain|Add a Job Chain]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_job_chain| PUT updates to an existing job chain]]

== Delete a Job Chain ==

You can delete an existing job chain using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#deleteChain(long,java.lang.String) JobManager.deleteChain()]. The method will return the final state of the job chain before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobChain.html JobChain], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_job_chain| DELETE an existing job chain]]

== List Conflicts ==

You can access all configured job conflict configuration via [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listConflicts() JobManager.listConflicts()], which will return [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictListing.html ConflictListing].

The return value includes all job conflict sets, with each set in order of priority. Non-conflicted jobs are also returned.

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_conflicts| GET a list of job conflicts]]

== Update Conflicts ==

To update the configured job conflict sets, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateConflicts(com.carfey.ops.api.bean.job.ConflictUpdateRequest,java.lang.String) JobManager.updateConflicts()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictUpdateRequest.html ConflictUpdateRequest] which will return the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/ConflictListing.html ConflictListing].

The request replaces the current job conflict configuration with the supplied configuration. The return value includes all job conflict sets, with each set in order of priority. Non-conflicted jobs are also returned.

'''ConflictUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| conflicts || N || A list of ordered sets containing job IDs. Each inner set contains jobs that conflict with each other, in order of execution precedence. Jobs that do not conflict with any other jobs are simply omitted from this list. A job can exist in multiple conflict sets, but should only occur in a particular set once. To remove all job conflicts, an empty list can be supplied for this field.

When selecting available non-conflicted jobs to run, Obsidian inspects the conflict sets in the order provided when they are saved, and selects the highest priority available job before moving onto the next conflict set. When priority is significant and varies across different sets, ensure your conflict sets are in the desired order.
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_job_conflicts| PUT updates to job conflicts]]

== List a Specific Job's Conflicts ==

You can return conflicts for a specific job with [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobConflicts(long) JobManager.listJobConflicts(long)], which will return [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobConflictListing.html JobConflictListing].

Conflicting jobs are returned in priority order, including the job for which this request was made, in order that its priority within the set can be determined. Note that if the job has no conflicts, the returned conflicting jobs list will be empty, and will not contain the requested job.

REST equivalent: [[REST_Endpoints#GET_a_list_of_conflicts_for_a_specific_job| GET a list of conflicts for a specific job]]

== Update Global Parameters ==

To update the configured global parameters, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#updateGlobalParameters(com.carfey.ops.api.bean.job.GlobalParameterUpdateRequest,java.lang.String) JobManager.updateGlobalParameters()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameterUpdateRequest.html GlobalParameterUpdateRequest] which will return the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameterListing.html GlobalParameterListing].

The request replaces the current global parameters with the supplied configuration. Supplying an empty list of parameters will result in all global parameters being deleted.

'''Note:''' Calls to remove or alter global parameters may fail if jobs that use them do not pass parameter validation as a result of the change. This can be caused by removing a referenced global parameter or values that cannot be interpreted as the appropriate type in a job.

'''GlobalParameterListing Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| parameters || N || Zero or more [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameter.html GlobalParameter] instances. Each parameter must have values for <code>name</code>, <code>type</code> and <code>values</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html ParameterType].
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_global_parameters| PUT updates to global parameters]]

== List Global Parameters ==

You can list all configured global parameters using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listGlobalParameters() listGlobalParameters()], which will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/GlobalParameterListing.html GlobalParameterListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_configured_global_parameters| GET a list of configured global parameters]]

== List Job Folders ==

You can list all used job folders using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/JobManager.html#listJobFolders() listJobFolders()], which will return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/job/JobFolderListing.html JobFolderListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_folders| GET a list of job folders]]

= RuntimeManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html RuntimeManager] is used to manage and view scheduled job runtimes (i.e. history). If you are looking for ways to view or manage jobs, see [[#JobManager API|JobManager]].

== List Scheduled Runtimes ==

To get a list of scheduled or completed job runtimes (i.e. history), use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#listRuntimes(com.carfey.ops.api.bean.history.RuntimeListingParameters) RuntimeManager.listRuntimes()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeListingParameters.html RuntimeListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeListing.html RuntimeListing] are ordered by scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>RuntimeListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>RuntimeListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''RuntimeListingParameters Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobIds || N || Restricts the search to the selected jobs.
|-
| statuses || N || Restricts the search to the selected [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobRuntimeStatus.html JobRuntimeStatus] values.
|-
| hosts || N || If specified, only job runtimes that are assigned to the specified host(s) are included.
|-
| folders|| N || If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values. ''Available from version 4.1.0 forward.''
|-
| startDate || N || Start date for the job runtimes to return (inclusive). Defaults to 24 hours ago.
|-
| endDate || N || End date for the job runtimes to return (inclusive). Defaults to a day after the start time. Must be after the start time.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/SortDirection.html SortDirection], which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|-
| filterParameters || N || If specified, values supplied in this map can be used to match on runtime parameter values (not job-level parameters). If multiple values for the same name (i.e. key) are supplied, a runtime is matched if any of its configured values match one of the supplied values. If multiple names are used, each must have a matching value for the runtime to be returned.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_scheduled_runtimes_.28supports_multiple_jobs.29|GET a list of scheduled runtimes]]

== Get Details on a Scheduled or Completed Runtime ==

To get full details on a scheduled or completed job runtime, including job results and one-time run configuration, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#getRuntime(long) RuntimeManager.getRuntime()]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeResult.html RuntimeResult], which has a nested [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeDetail.html RuntimeDetail] containing the full job output and one-time run parameters, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_scheduled_.28or_completed.29_job_runtime|GET details of an existing scheduled or completed runtime]]

== Preview Runtimes ==

To preview future runtimes for one or more jobs, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#listRuntimePreviews(com.carfey.ops.api.bean.schedule.RuntimePreviewParameters) RuntimeManager.listRuntimePreview()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/RuntimePreviewParameters.html RuntimePreviewParameters] instance to filter the results. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/RuntimePreviewListing.html RuntimePreviewListing].

This method is useful to see when jobs will run during a given time period. Note that these are an estimate of runtimes and cannot account for overlapped jobs, schedule changes or other issues that may result in altered execution times. Results are ordered by scheduled time ascending.

'''Note:''' The capped field in the returned <code>RuntimePreviewListing</code> indicates that there were too many results to return (i.e. exceeded maxRecords as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). If you are hitting this condition, try limiting your date range or other parameters. Due to the nature of the runtime preview, paging is not feasible.

'''RuntimePreviewParameters Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobIds || N || Restricts the preview to the selected jobs.
|-
| startDate || N || Start date for the runtimes to preview (inclusive). Defaults to the current minute.
|-
| endDate || N || End date for the runtimes to preview (inclusive). Defaults to a day after the start time. Must be after the start time.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_runtime_previews_.28supports_multiple_jobs.29|GET a list of runtime previews]]

== Schedule a New Runtime for a Job ==

To submit an ad hoc job run (executed immediately), or a one-time run scheduled for a later time, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#submitRuntime(long,com.carfey.ops.api.bean.history.RuntimeSubmissionRequest,java.lang.String) RuntimeManager.submitRuntime()]. A [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeSubmissionRequest.html RuntimeSubmissionRequest] must be supplied. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeSubmissionResult.html RuntimeSubmissionResult] if it succeeds, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified job ID does not exist.

'''Note:''' The job must be in a valid state to allow for execution (i.e. <code>UNSCHEDULED_ACTIVE</code>, <code>ENABLED</code>, or <code>AD_HOC_ACTIVE</code>).

'''RuntimeSubmissionRequest Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| N || The scheduled time, when the request is for a scheduled one-time run. If not supplied, the runtime is submitted for immediate execution as an ad hoc job.
|-
| parameters || N || Zero or more parameter definitions. Parameter definitions must have values for <code>name</code>, <code>type</code> and <code>value</code>, where <code>type</code> is a valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/ParameterType.html ParameterType]. To define multiple values for a single parameter name, simply include multiple items in the parameters collection. If the parameter name matches a parameter defined for the job, it must be of the same type, and it will completely replace all configured values at the job level.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_scheduled_runtime_for_an_existing_job_.28i.e._submit_a_one-time_or_ad_hoc_run.29|POST a new scheduled runtime for an existing job]]

== Delete a Future Scheduled Runtime for a Job ==

''Since Obsidian 4.7.0''

To delete a future scheduled runtime, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#deleteOneTimeRun(long,com.carfey.ops.api.bean.history.OneTimeRunDeleteRequest,java.lang.String) RuntimeManager.deleteOneTimeRun()]. A [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/OneTimeRunDeleteRequest.html OneTimeRunDeleteRequest] must be supplied. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/OneTimeDeletionResult.html OneTimeDeletionResult] if it succeeds, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified job ID does not exist.

'''Note:''' When more than on runtime is scheduled for the given time, this function will remove gaps, that is ensure the remaining ordinals start at 0 and increment without skipping any values. For example, if you have 3 instances scheduled (ordinals 0, 1 & 2) and request ordinal 0 be deleted, the remaining two ordinals (1 & 2) will be renumbered to 0 & 1.

'''OneTimeRunDeleteRequestFields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| scheduledTime|| Y || The future scheduled runtime.
|-
| ordinal|| Y/N || The ordinal of future dated runtime. If only one runtime is scheduled for the given date, the value can be omitted or should be 0. If more than one instance is scheduled at the given time, the actual ordinal must be specified.
|}

REST equivalent: [[REST_Endpoints#DELETE_a_future_scheduled_runtime|DELETE a future scheduled runtime]]

== Resubmit a Failed Job Runtime ==

If a job execution fails and you wish to resubmit it, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#resubmitRuntime(long,java.lang.String) RuntimeManager.resubmitRuntime()] with the appropriate job runtime ID. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/RuntimeResubmissionResult.html RuntimeResubmissionResult] if the action succeeds, or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified job runtime ID does not exist.

REST equivalent: [[REST_Endpoints#POST_a_resubmission_request_for_a_failed_job_runtime|POST a resubmission request for a failed job runtime]]

== Interrupt a Running Job Runtime ==

To interrupt a currently running job runtime, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#interruptRuntime(long,java.lang.String) RuntimeManager.interruptRuntime()] with the appropriate job runtime ID. A [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/JobInterruptResult.html JobInterruptResult] is returned upon success, or a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] is thrown if the specified job runtime ID does not exist.

This request can only be made once successfully. An interruption request will result in the job being terminated, as long as it does not terminate naturally very soon after the request is made, and the job is capable of shutting down. Not all jobs can be terminated. See [[Implementing_Jobs#Interruptable_Jobs|Interruptable Jobs]] for full details.

REST equivalent: [[REST_Endpoints#POST_an_interruption_request_to_kill_a_running_job|POST an interruption request to kill a running job]]

== Post Results to a Pending (Async) Runtime ==

'''As of Obsidian 4.5.0'''

To indicate the final status of an [[Implementing_Jobs#Async_Jobs | Async Job]], use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#setAsyncRuntimeResults(long,com.carfey.ops.api.bean.history.AsyncJobRuntimeResultsRequest,java.lang.String) RuntimeManager.setAsyncRuntimeResults()] with the appropriate job runtime ID. An [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/AsyncJobRuntimeResultsRequest.html AsyncJobRuntimeResultsRequest] is returned upon success, or a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] is thrown if the specified job runtime ID does not exist.

This request can only be made once successfully. Final state can only be <code>COMPLETED</code> or <code>FAILED</code> as per [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/AsyncJobRuntimeStatus.html AsyncJobRuntimeStatus]. If <code>FAILED</code>, then a finalizationException must be provided. If <code>COMPLETED</code>, finalizationException must be null.

REST equivalent: [[REST_Endpoints#POST_async_results|POST async results]]

== List Job Dashboard (Latest Scheduled Runtime by Job) ==

'''As of Obsidian 4.10.2'''

To get a list of latest job runtimes by job(i.e. history), use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/RuntimeManager.html#listJobsDashboard(com.carfey.ops.api.bean.history.JobDashboardListingParameters) RuntimeManager.listJobsDashboard()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/JobDashboardListingParameters.html JobDashboardListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/history/JobDashboardListing.html JobDashboardListing] are ordered by scheduled time descending, unless overridden by the <code>sort</code> parameter.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>JobDashboardListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen, or the <code>quantity</code> parameter). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>JobDashboardListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''JobDashboardListingParametersFields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| jobIds || N || Restricts the search to the selected jobs. ''Do not combine with jobNicknames.''
|-
| jobNicknames || N || Restricts the search to the selected jobs. ''Do not combine with jobIds.''
|-
| hosts || N || If specified, only the latest job runtimes that are run on the specified host(s) are included.
|-
| folders|| N || If specified, only jobs matching the supplied folders are returned. If a parent path is supplied, all jobs containing that path or subpaths are included in the results. If an empty string is supplied, jobs with no folder will be returned. Supports multiple values.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|-
| quantity || N || Indicates the maximum number of results to return. This overrides the <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen.
|-
| sort || N || A valid [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/SortDirection.html SortDirection], which controls the ordering of returned results. In all cases, the job scheduled time is used to sort results.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_the_latest_scheduled_runtime_by_job_.28supports_multiple_jobs.29|GET a list of the latest scheduled runtime by job]]

= HostManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html HostManager] is used to manage and view scheduling hosts and see additional host details including event hooks.

== List Scheduling Hosts ==

To get a list of known hosts which are running or recently shut down abnormally, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listHosts() HostManager.listHosts()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostListing.html HostListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_known_scheduling_hosts|GET a list of known scheduling hosts]]

== Get a Specific Host ==

To get details on a host by ID or name, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHost(long) HostManager.getHost(id)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getHost(java.lang.String) or HostManager.getHost(String)].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostDetail.html HostDetail], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

REST equivalent: [[REST_Endpoints#GET_details_on_an_existing_scheduling_host|GET details on an existing scheduling host]]

== Get Licence Health by Host ==

'''As of Obsidian 4.3.0'''

Identical to [[Embedded_API#Get_a_Specific_Host | Get a Specific Host]], except it throws an Exception if the licence is invalid or expired.

To get licence health on a host by ID or name, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getLicenceHealth(long) HostManager.getLicenceHealth(id)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#getLicenceHealth(java.lang.String) or HostManager.getLicenceHealth(String)].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostDetail.html HostDetail], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

REST equivalent: [[REST_Endpoints#GET_licence_details_on_an_existing_scheduling_host|GET licence details on an existing scheduling host]]

== Update a Host ==

To enable or disable a scheduling host, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#updateHost(long,com.carfey.ops.api.bean.host.HostUpdateRequest,java.lang.String) HostManager.updateHost(long)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#updateHost(java.lang.String,com.carfey.ops.api.bean.host.HostUpdateRequest,java.lang.String) HostManager.updateHost(String)] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostUpdateRequest.html HostUpdateRequest]. Both methods return a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/HostDetail.html HostDetail], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

'''HostUpdateRequest Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| enabled || Y || Should this host should be enabled?
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_scheduling_host|PUT updates to an existing scheduling host]]

== List Event Hooks ==
''As of Obsidian 5.4.0''

To get a list of all event hooks against all hosts, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listEventHooksByHost() HostManager.listEventHooksByHost()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/EventHookListing.html EventHookListing].

REST equivalent: [[REST_Endpoints#GET_event_hooks|GET a list of event hooks]]

== Get Event Hooks on a specific Host ==
''As of Obsidian 5.4.0''

To get event hooks on a host by ID or name, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listEventHooksByHost(long) HostManager.listEventHooksByHost(id)] or [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#listEventHooksByHost(java.lang.String) or HostManager.listEventHooksByHost(String)].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/EventHookListing.html EventHookListing], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID or name does not exist.

REST equivalent: [[REST_Endpoints#GET_event_hooks_on_host|GET event hooks on host]]

== Event Hook Resume or Pause ==
''As of Obsidian 5.5.0''

To trigger a pause or resume of event hooks, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/HostManager.html#updateEventHook(com.carfey.ops.api.bean.host.UpdateEventHookRequest,java.lang.String) HostManager.updateEventHook(UpdateEventHookRequest,String)] which accepts an [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/UpdateEventHookRequest.html UpdateEventHookRequest].

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/host/EventHookListing.html EventHookListing], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified host ID/name does not exist or the event hook does not exist on the specified host.

REST equivalent: [[REST_Endpoints#POST_event_hook_pause_or_resume|POST event hook pause/resume]]

= CustomCalendarManager API =

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html CustomCalendarManager] allows for managing of [[Job_Features#Custom_Calendars|Custom Calendars]].

== List Calendars ==

To list existing custom calendars, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#listCalendars() CustomCalendarManager.listCalendars()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarListing.html CustomCalendarListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_custom_calendars|GET a list of custom calendars]]

== Get Details on a Calendar ==

To get details on an existing custom calendar, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#getCalendar(long) CustomCalendarManager.getCalendar()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified calendar ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_on_an_existing_custom_calendar|GET details on an existing custom calendar]]

== Add a Calendar ==

To add a new custom calendar, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#addCalendar(com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest,java.lang.String) CustomCalendarManager.addCalendar()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarUpdateRequest.html CustomCalendarUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar].

'''CustomCalendarUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name|| Y || Calendar name
|-
| dates|| Y || Dates to exclude
|}

REST equivalent: [[REST_Endpoints#POST_a_new_custom_calendar|POST a new custom calendar]]

== Update a Calendar ==

To update an existing calendar, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#updateCalendar(long,com.carfey.ops.api.bean.calendar.CustomCalendarUpdateRequest,java.lang.String) CustomCalendarManager.updateCalendar()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendarUpdateRequest.html CustomCalendarUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified calendar ID does not exist.

The format of <code>CustomCalendarUpdateRequest</code> is identical to that of [[#Add_a_Calendar|Add a Calendar]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_custom_calendar|PUT updates to an existing custom calendar]]

== Delete a Calendar ==

You can delete an existing job using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/CustomCalendarManager.html#deleteCalendar(long,java.lang.String) CustomCalendarManager.deleteCalendar()]. The method will return the final state of the calendar before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/calendar/CustomCalendar.html CustomCalendar] or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified calendar ID does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_custom_calendar|DELETE an existing custom calendar]]

= NotificationManager API =

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html NotificationManager] allows for managing of Obsidian [[Event_Notifications|event notifications]], including subscribers and templates used to send notifications, and allows searching of triggered notifications.

== List Subscribers ==

To list existing subscribers, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#listSubscribers() NotificationManager.listSubscribers()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/SubscriberListing.html SubscriberListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_subscribers|GET a list of subscribers]]

== Get Details on a Subscriber ==

To get details on an existing subscriber, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#getSubscriber(long) NotificationManager.getSubscriber()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified subscriber ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_subscriber|GET details of an existing subscriber]]

== Add a Subscriber ==

To add a new subscriber, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#addSubscriber(com.carfey.ops.api.bean.notification.SubscriberUpdateRequest,java.lang.String) NotificationManager.addSubscriber()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/SubscriberUpdateRequest.html SubscriberUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber].

'''SubscriberUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| emailAddress|| Y || Valid email address of the subscriber. Must be unique.
|-
| active || N || Whether the subscription is active. Defaults to false.
|-
| generalSubscriptions|| N || Zero or more instances of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/GeneralSubscriptionUpdateRequest.html GeneralSubscriptionUpdateRequest]. Each item contains a required subscription [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] and [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/LogLevel.html LogLevel] in the <code>category</code> and <code>level</code> fields respectively, an optional <code>jobId</code> and an optional <code>active</code> flag which defaults to false.

'''Note:''' Only <code>ERROR</code>, <code>WARNING</code> AND <code>INFO</code> are valid values for <code>level</code>. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values for <code>category</code>.
|-
| jobExecutionSubscriptions || N || Zero or more instances of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/JobExecutionSubscriptionUpdateRequest.html JobExecutionSubscriptionUpdateRequest]. Each item contains a required <code>triggerStates</code> field which uses the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/SubscriptionJobStatus.html SubscriptionJobStatus] enum. Note that <code>CONDITIONAL</code> and <code>COMPLETED</code> types cannot be used on the same chain.

If the <code>CONDITIONAL</code> state is selected, at least one [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/JobSubscriptionCondition.html JobSubscriptionCondition] must be supplied in the <code>resultConditions</code> field. Result conditions consist of a <code>variableName</code>, an <code>operator</code> using the [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/JobSubscriptionConditionOperator.html JobSubscriptionConditionOperator] enum, and for most operators, a list of <code>values</code>. The <code>EXISTS</code> and <code>NOT EXISTS</code> operators do not use values, so they must not be supplied. Operators <code>IN</code> and <code>NOT IN</code> support one or more values, and all other operators accept a single value in the <code>values</code> list.

In addition, two additional optional fields control which jobs the subscription applies to. <code>jobIds</code> is used to specify specific jobs, while <code>allJobs</code> may be set to true to make it apply to all jobs. If <code>jobIds</code> is supplied and <code>allJobs</code> is set to true, <code>jobIds</code> will be ignored.

Finally, the <code>active</code> flag may be supplied which defaults to true.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_subscriber|POST a new subscriber]]

== Update a Subscriber ==

To update an existing subscriber, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#updateSubscriber(long,com.carfey.ops.api.bean.notification.SubscriberUpdateRequest,java.lang.String) NotificationManager.updateSubscriber()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/SubscriberUpdateRequest.html SubscriberUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified subscriber ID does not exist.

The format of <code>SubscriberUpdateRequest</code> is identical to that of [[#Add_a_Subscriber|Add a Subscriber]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_subscriber|PUT updates to an existing subscriber]]

== Delete a Subscriber ==

You can delete an existing subscriber using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#deleteSubscriber(long,java.lang.String) NotificationManager.deleteSubscriber()]. The method will return the final state of the subscriber before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Subscriber.html Subscriber], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_subscriber| DELETE an existing subscriber]]

== List Templates ==

To list existing notification templates, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#listTemplates() NotificationManager.listTemplates()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/TemplateListing.html TemplateListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_templates|GET a list of templates]]

== Get Details on a Template ==

To get details on an existing template, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#getTemplate(long) NotificationManager.getTemplate()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified template ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_template|GET details of an existing template]]

== Add a Template ==

To add a new template, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#addTemplate(com.carfey.ops.api.bean.notification.TemplateUpdateRequest,java.lang.String) NotificationManager.addTemplate()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/TemplateUpdateRequest.html TemplateUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template].

'''TemplateUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| name || Y || Unique name of the template.
|-
| active || N || Whether the template is active. Defaults to false.
|-
| category || N || The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] for the template, or null if it is the default generic template. Supports multiple values. Not all categories are supported. Only <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>, <code>QUEUE</code>, <code>SYSTEM_PARAMETER</code> and null are valid values.
|-
| defaultForJobs || N || For job-related categories, setting this to true allows for a template to be used as the default template when one isn't assigned to a particular job. Defaults to false.
|-
| jobIds || N || For job-related categories, specific jobs may be assigned to use this template.
|-
| subjectTemplate || Y || A valid [[Email_Templates|Mustache template]] for the subject.
|-
| bodyTemplate || Y || A valid [[Email_Templates|Mustache template]] for the body.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_template|POST a new template]]

== Update a Template ==

To update an existing template, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#updateTemplate(long,com.carfey.ops.api.bean.notification.TemplateUpdateRequest,java.lang.String) NotificationManager.updateTemplate()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/TemplateUpdateRequest.html TemplateUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified template ID does not exist.

The format of <code>TemplateUpdateRequest</code> is identical to that of [[#Add_a_Template|Add a Template]].

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_template|PUT updates to an existing template]]

== Delete a Template ==

You can delete an existing template using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#deleteTemplate(long,java.lang.String) NotificationManager.deleteTemplate()]. The method will return the final state of the template before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Template.html Template], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_template| DELETE an existing template]]

== List Notifications==

To get a list notifications, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#listNotifications(com.carfey.ops.api.bean.notification.NotificationListingParameters) NotificationManager.listNotifications()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/NotificationListingParameters.html NotificationListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/NotificationListing.html NotificationListing] are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time. Note that existence of records does not necessarily indicate the notification was successfully sent or received.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>LogListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>LogListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''LogListingParameters Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| category || N || One or more notification log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] values used to limit the returned results.
|-
| level || N || One or more notification log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/LogLevel.html LogLevel] values used to limit the returned results.
|-
| start || N || Start date for the notifications to return (inclusive). Defaults to the current minute.
|-
| end || N || Start date for the notifications to return (inclusive). Defaults to a day after the start time. Must be after the start time.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_notifications|GET a list of notifications]]

== Get Details on a Notification ==

To get details on a single notification entry use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/NotificationManager.html#getNotification(long) NotificationManager.getNotification()]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/notification/Notification.html Notification] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist. Note that existence of a record does not necessarily indicate the notification was successfully sent or received.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_notification|GET details of an existing notification]]

= LogManager API =

[https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/LogManager.html LogManager] is used to retrieve event log entries.

== List Log Entries==

To get a list log entries, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/LogManager.html#listLogs(com.carfey.ops.api.bean.log.LogListingParameters) LogManager.listLogs()], which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/log/LogListingParameters.html LogListingParameters] instance. The results in the returned [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/log/LogListing.html LogListing] are ordered roughly according to when they were created, but ordering is not guaranteed to be in order of created time.

'''Note:''' The <code>nextPageStartKey</code> field in the <code>LogListing</code> indicates that there were too many results to return (i.e. exceeded <code>maxRecords</code> as configured in the [[Admin Scheduler Settings|scheduler settings]] screen). To fetch the next page of results, invoke the same method with the <code>startKey</code> field on <code>LogListingParameters</code> set to the returned <code>nextPageStartKey</code>.

'''LogListingParameters Fields'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| host || N || If specified, only logs from the specified host name(s) are included. Supports multiple values.
|-
| filterText || N || If specified, only messages containing the supplied filter text are returned. '%' can be used as a wildcard.
|-
| category || N || One or more log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Category.html Category] values used to limit the returned results.
|-
| level || N || One or more log [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/LogLevel.html LogLevel] values used to limit the returned results.
|-
| start || N || Start date for the logs to return (inclusive). Defaults to the current minute.
|-
| end || N || Start date for the logs to return (inclusive). Defaults to a day after the start time. Must be after the start time.
|-
| startKey || N || If requesting the next page of results from a previous call, set it to the returned <code>nextPageStartKey</code>.
|}

REST equivalent: [[REST_Endpoints#GET_a_list_of_logs|GET a list of logs]]

== Get Details on a Log Entry ==

To get details on a single log entry use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/LogManager.html#getLog(long) LogManager.getLog()]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/log/Log.html Log] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_log|GET details of an existing log]]

= SystemParameterManager API =

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html SystemParameterManager] allows for listing and updating Obsidian [[Admin_Scheduler Settings|scheduler settings]].

== List System Parameters ==

To list editable system parameters, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html#listParameters() SystemParameterManager.listParameters()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameterListing.html SystemParameterListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_system_parameters|GET a list of system parameters]]

== Get Details on a System Parameter ==

To get details on specific system parameter, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html#getParameter(java.lang.String) SystemParameterManager.getParameter()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameter.html SystemParameter], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified system parameter does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_a_system_parameter|GET details of system parameter]]

== Update a System Parameter ==

To update a system parameter's value, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemParameterManager.html#updateParameter(java.lang.String,java.lang.String,java.lang.String) SystemParameterManager.updateParameter()] with a value supplied as a String. The supplied value must be a valid String representation of the type for the system parameter (e.g. Integer, Boolean).

The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/SystemParameter.html SystemParameter] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified system parameter does not exist.

REST equivalent: [[REST_Endpoints#PUT_updates_to_a_system_parameter|PUT updates to a system parameter]]

= UserManager API =

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html UserManager] allows for managing of Obsidian [[Admin_User_Management|users]] when native authentication is used. This API cannot be used when using LDAP or other custom authentication methods.

== List Users ==

To list existing users, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#listUsers() UserManager.listUsers()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserListing.html UserListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_users|GET a list of users]]

== Get Details on a User ==

To get details on an existing user, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#getUser(long) UserManager.getUser()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User], or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified user ID does not exist.

REST equivalent: [[REST_Endpoints#GET_details_of_an_existing_user|GET details of an existing user]]

== Add a User ==

To add a new user, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#addUser(com.carfey.ops.api.bean.user.UserCreationRequest,java.lang.String) UserManager.addUser()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserCreationRequest.html UserCreationRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User].

'''UserCreationRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| userName || Y || Unique user name used to log in.
|-
| active || N || Whether the user is enabled. Defaults to false.
|-
| roles || N ||Zero or more [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Role.html Role] values. Supplying no roles indicates it is a normal read-only user.
|-
| password || Y || A password at least 6 characters long.
|}

REST equivalent: [[REST_Endpoints#POST_a_new_user|POST a new user]]

== Update a User ==

To update an existing user, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#updateUser(long,com.carfey.ops.api.bean.user.UserUpdateRequest,java.lang.String) UserManager.updateUser()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/UserUpdateRequest.html UserUpdateRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User] or throws a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if the specified user ID does not exist.

Note that only supplied fields are updated. If a field is left null, the existing value will be left unchanged.

'''UserUpdateRequest Format'''
{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| active || N || Whether the user is enabled. Defaults to the existing active state.
|-
| roles || N || Zero or more [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/enums/Role.html Role] values. Supplying an empty list of roles indicates it is a normal read-only user. Supplying null indicates that the roles should not be updated.
|-
| password || N || A password at least 6 characters long. If not supplied, the password is not changed.
|}

REST equivalent: [[REST_Endpoints#PUT_updates_to_an_existing_user|PUT updates to an existing user]]

== Delete a User ==

You can delete an existing user using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#deleteUser(long,java.lang.String) UserManager.deleteUser()]. The method will return the final state of the user before deletion as a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/User.html User], or throw a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/MissingEntityException.html MissingEntityException] if it does not exist.

REST equivalent: [[REST_Endpoints#DELETE_an_existing_user| DELETE an existing user]]

== List Known MFA Users ==

''As of Obsidian 5.0''

To list all known MFA users, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#listMfaUsers() UserManager.listMfaUsers()], which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/MfaUserListing.html MfaUserListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_known_MFA_users|GET a list of known MFA users]]

== Reset Users' MFA State ==

''As of Obsidian 5.0''

You can reset one or more users' MFA state using [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/UserManager.html#resetMfa(com.carfey.ops.api.bean.user.ResetMfaRequest,java.lang.String) UserManager.resetMfa()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/ResetMfaRequest.html ResetMfaRequest]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/user/MfaUserListing.html MfaUserListing] which echoes the user names that were reset.

REST equivalent: [[REST_Endpoints#PUT_MFA_user_resets| PUT MFA user resets]]

= SystemRestore API =

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html SystemRestoreManager] allows for importing and exporting full Obsidian configuration. See [[Initializing_and_Restoring|Initializing and Restoring]] for more details.

== Get System Restore Configuration ==

To extract the current system restore configuration, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#getConfiguration() SystemRestoreManager.getConfiguration()] which accepts an optional [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreParameters.html SystemRestoreParameters] and returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration].

You can limit the returned configuration by providing a SystemRestoreParameters.

'''SystemRestoreParameters Fields'''

{| class="wikitable leftAlignTable"
! Field || Required? || Notes
|-
| excludeItems || N || Allows filtering out of specific groups of system configuration items. Supported values are <code>jobs</code>, <code>chains</code>, <code>conflicts</code>, <code>systemParameters</code>, <code>customCalendars</code>, <code>globalParameters</code>, <code>users</code>, <code>templates</code>, <code>subscribers</code>. Filtering out jobs automatically also filters out chains and conflicts and drops any other job references (such as in templates and subscribers).
|-
| jobNicknames || N || Allows targeting only specific jobs in the jobs export. Filtering out any jobs automatically filters out all conflicts, any chains where these jobs exist and and drops any other references to these jobs (such as in templates and subscribers).
|}

REST equivalent: [[REST_Endpoints#GET_a_system_restore_configuration|GET a system restore configuration]]

== Update System Restore Configuration ==

To import a system restore configuration (partial or complete), use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,java.lang.String) SystemRestoreManager.updateConfiguration()] with a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration]. The method returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/system/restore/SystemRestoreConfiguration.html SystemRestoreConfiguration] representing the full system state, which may not be the same as the input value.

REST equivalent: [[REST_Endpoints#PUT_a_system_restore_configuration|PUT a system restore configuration]]

= ScheduleAliasManager API =

''As of Obsidian 5.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html ScheduleAliasManager] allows for retrieving, creating, editing and deleting schedule aliases. See [[Admin_Schedule_Aliases|Schedule Aliases]] for more information.

== List Schedule Aliases ==

To list the current schedule aliases, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#listScheduleAliases() ScheduleAliasManager.listScheduleAliases()] which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAliasListing.html ScheduleAliasListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_schedule_aliases|GET a list of schedule aliases]]

== Create or Update Schedule Alias ==

To create or update a schedule alias, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#addOrUpdateScheduleAlias(java.lang.String,java.lang.String,java.lang.String) ScheduleAliasManager.addOrUpdateScheduleAlias()]. The method returns the updated [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAlias.html ScheduleAlias] representing the full system state, which may not be the same as the input value.

REST equivalent: [[REST_Endpoints#PUT_a_schedule_alias|PUT a schedule alias]]

== Get a Schedule Alias ==

To retrieve a current schedule alias, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#getScheduleAlias(java.lang.String) ScheduleAliasManager.getScheduleAlias()] which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAlias.html ScheduleAlias].

REST equivalent: [[REST_Endpoints#GET_a_schedule_alias|GET a schedule alias]]

== Delete a Schedule Alias ==

To delete an unused schedule alias, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/ScheduleAliasManager.html#deleteScheduleAlias(java.lang.String,java.lang.String) ScheduleAliasManager.deleteScheduleAlias()] which returns the deleted [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/schedule/ScheduleAlias.html ScheduleAlias].

REST equivalent: [[REST_Endpoints#DELETE_a_schedule_alias|DELETE a schedule alias]]

= StatsManager API =

''As of Obsidian 6.4.0''

The [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/StatsManager.html StatsManager] allows for retrieving job execution statistics. Assumes the [[Built-in_Jobs#Obsidian_Execution_Statistics_Job|Execution Statistics Job]] has run at least once successfully.

== List Stats ==

To list the job execution statistics, use [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/StatsManager.html#listStats(com.carfey.ops.api.bean.stats.StatsListingRequest) StatsManager.listStats()] which returns a [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/api/bean/stats/StatsListing.html StatsListing].

REST equivalent: [[REST_Endpoints#GET_a_list_of_job_execution_statistics|GET a list of job execution statistics]]

Email Templates

2026-07-31T14:49:50Z

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

Obsidian supports customizable templates for all email notifications.

If you have questions or require help building your own templates, please [[Contact Carfey Software|contact us]] for free support.

== Template Basics & Language ==

Obsidian comes with two basic email templates that are suitable for most users. For those that wish to have more control, templates can be configured in the '''[[Admin Templates|Email Templates]]''' screen.

Both subject and body fields can be customized through templates. Note that body templates are used for '''HTML only'''.

Obsidian email templates use [http://mustache.github.io/ Mustache], which is a logic-less templating language commonly used in various applications. Specifically, Obsidian uses [https://github.com/samskivert/jmustache jMustache], and it can be referred to when looking for feature support and general syntax in your templates.

'''Note:''' Obsidian cannot guarantee that configured templates are valid. You are responsible for ensuring the correctness or your templates according to the information provided below. If you have configured Obsidian to use invalid templates that fail, Obsidian will fall back to internal templates so that notifications are not lost.

== Templating Variables ==

The following table documents all data elements that are available in email templates. Note that some data elements are only available in certain contexts, so your templates should be written accordingly. The ''Available Scope'' column indicates which types of events the variables are used in. For example, some variables are only present for job-related event categories, and some are only present for Job Run events.

If you wish to see a sample template, simply navigate to the '''[[Admin Templates|Email Templates]]''' screen in the admin UI, and take a look at the default templates that are pre-installed.

{| class="wikitable leftAlignTable"
! Variable Name || Type || Available Scope || Notes
|-
| subject || Text || Always || This the basic event summary message.
|-
| detailItems || Text (multiple) || Always || The list of all detail messages provided with the event. For example, when a job's configuration is updated, a separate item for each change will be represented here. For job execution failures, this will contain the stack trace. In some cases, this may be empty.
|-
| detail || Text || Always || This the combined form of <code>detailItems</code>. In some cases, this may be empty.
|-
| hostName || Text || Always || The host name / designator that originated the event.
|-
| hostUrl || Text || Always || The host URL as configured in the [[Admin Scheduler Settings|scheduler settings]] screen. This can be used to link to the Obsidian installation in emails.
|-
| hasDetail || Boolean || Always || Indicates if any <code>detailItems'</code> exist. Can be used for conditionals.
|-
| level || Text || Always || Indicates the level of the event. One of: <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code>, <code>FATAL</code>.
|-
| category || Text || Always || Indicates the category of the event. One of: <code>SYSTEM_PARAMETER</code>, <code>QUEUE</code>, <code>JOB</code>, <code>JOB_CHAIN</code>, <code>JOB_CONFIG</code>, <code>JOB_RUN</code>, <code>JOB_RECOVERY</code>, <code>LICENCE</code>.
|-
| levelDisplayName || Text || Always || Indicates the level of the event, in a pretty format. One of: <code>Info</code>, <code>Warning</code>, <code>Error</code>, <code>Fatal</code>.
|-
| categoryDisplayName || Text || Always || Indicates the category of the event, in a pretty format. One of: <code>System Parameter</code>, <code>Queue</code>, <code>Job</code>, <code>Job Chain</code>, <code>Job Config</code>, <code>Job Run</code>, <code>Job Recovery</code>, <code>Licence</code>.
|-
| recipients || Text (multiple) || Always || The email addresses of all recipients of this message.
|-
| fatal || Boolean || Always || Indicates if the level was <code>FATAL</code>.
|-
| error || Boolean || Always || Indicates if the level was <code>ERROR</code>.
|-
| errorOrHigher || Boolean || Always || Indicates if the level was <code>FATAL</code> or <code>ERROR</code>.
|-
| warn || Boolean || Always || Indicates if the level was <code>WARNING</code>.
|-
| warnOrHigher || Boolean || Always || Indicates if the level was <code>FATAL</code>, <code>ERROR</code> or <code>WARNING</code>.
|-
| info || Boolean || Always || Indicates if the level was <code>INFO</code>.
|-
| job || Complex Object || Job Events only || For any job-related category, this object provides the basic job configuration. Attributes that can be accessed on the job are: <code>id</code>, <code>jobClass</code>, <code>minExecutionDuration</code>, <code>maxExecutionDuration</code>, <code>nickname</code>, <code>pickupBufferMinutes</code> and <code>recoveryType</code>.
|-
| jobState || Complex Object || Job Events only || For any job-related category, this object provides the current job schedule configuration, or for Job Run events, the schedule applicable to that job history record. Attributes that can be accessed on the jobState are: <code>effectiveDate</code>, <code>endDate</code>, <code>jobStatus</code> and <code>schedule</code>.
|-
| currentSchedule || Text || Job Events only || This is a simplified way to access <code>jobState.schedule</code>.
|-
| jobHistory || Complex Object || Job Run Events only || For any Job run events (i.e.. completion or failure), this object contains information on the job execution (aka history). Attributes that can be accessed on the job are: <code>adHoc</code> (boolean), <code>resubmission</code> (boolean), <code>runningHost</code>, <code>scheduledTime</code> and <code>submissionMode</code>. The field <code>chainedFrom</code> provides access to the source chain job history when applicable, which has the same format as this <code>jobHistory</code> object. From either this object or <code>chainedFrom</code>, the <code>job</code> field provides access to the job configuration in the same format as the <code>job</code> element described above.
|-
| jobResults || List of Objects || Job Run Events only || This field contains saved job results as a list of objects with two attributes: <code>key</code> for the name and <code>value</code> for a list of the applicable values. Example: iterate over all results and output the values separated by commas: <pre>{{#jobResults}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobResults}}</pre>
|-
| jobResultMap || Map Object || Job Run Events only || This is an alternate format of <code>jobResults</code> stored in a map. This allows you to easily access a specific result by name. Example: <pre>{{#jobResultMap.outputFiles}}{{.}}{{/jobResultMap.outputFiles}}</pre>
|-
| jobParameters || Complex Object || Job Events only || This field contains saved job parameters as a list of objects with two attributes: <code>key</code> for the name and <code>value</code> for a list of the applicable values . Example: iterate over all results and output the values separated by commas: <pre>{{#jobParameters}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobParameters}}</pre>
|-
| jobParameterMap || List of Objects|| Job Events only || This is an alternate format of <code>jobParameters</code> stored in a map. This allows you to easily access a specific parameter by name. Example: <pre>{{#jobParameterMap.archiveDirectory}}{{.}}{{/jobParameterMap.archiveDirectory}}</pre>
|}

== Sample Syntax ==

The following shows various ways data can be accessed from within an Obsidian email template. This example lacks HTML formatting and is meant to show how to access and display different variables available to your templates.

<pre>
Current Job Schedule: {{currentSchedule}}
Detail: {{detail}}
{{#detailItems}}
Detail {{-index}}: {{.}}
{{/detailItems}}
Error: {{#error}}true{{/error}}{{^error}}false{{/error}}
Error or Higher: {{#errorOrHigher}}true{{/errorOrHigher}}{{^errorOrHigher}}false{{/errorOrHigher}}
Fatal: {{#fatal}}true{{/fatal}}{{^fatal}}false{{/fatal}}
Warn: {{#warn}}true{{/warn}}{{^warn}}false{{/warn}}
Warn or Higher: {{#warnOrHigher}}true{{/warnOrHigher}}{{^warnOrHigher}}false{{/warnOrHigher}}
Info: {{#info}}true{{/info}}{{^info}}false{{/info}}
Host Name: {{hostName}}
Host Url: {{hostUrl}}
Level: {{level}} - {{levelDisplayName}}
Category: {{category}} - {{categoryDisplayName}}
Recipients: {{#recipients}}{{^-first}}, {{/-first}}{{.}}{{/recipients}}
Subject: {{subject}}
Job: {{#job}}{{id}} {{nickname}} {{pickupBufferMinutes}} {{recoveryType}} {{jobClass}} {{minExecutionDuration}} {{maxExecutionDuration}}{{/job}}
Job State: {{#jobState}}{{effectiveDate}}-{{endDate}} {{jobStatus}} {{schedule}}{{/jobState}}
Job History: {{#jobHistory}}{{adHoc}} {{resubmission}} {{scheduledTime}} {{submissionMode}} {{runningHost}}{{#chainedFrom}}; Chained from: {{this.job.nickname}} ({{this.scheduledTime}}){{/chainedFrom}}{{/jobHistory}}
Job Results: {{#jobResults}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobResults}}
Job Results by Name: {{#jobResultMap}}{{#result1}}{{^-first}}, {{/-first}}{{.}}{{/result1}}{{/jobResultMap}}
Job Results by Name (short): {{#jobResultMap.result2}}{{.}}{{/jobResultMap.result2}}
Job Parameters: {{#jobParameters}}{{^-first}}; {{/-first}}{{key}}={{#value}}{{^-first}}, {{/-first}}{{.}}{{/value}}{{/jobParameters}}
Job Parameters by Name: {{#jobParameterMap}}{{#param1}}{{^-first}}, {{/-first}}{{.}}{{/param1}}{{/jobParameterMap}}
Job Parameters by Name (short): {{#jobParameterMap.param2}}{{.}}{{/jobParameterMap.param2}}
</pre>

Cron

2026-07-31T14:49:49Z

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

Job schedules in Obsidian are specified using [http://en.wikipedia.org/wiki/cron cron] syntax, with some custom extensions to support [[#Recurrence|recurrence]]. This page provides a reference for writing your own cron expressions, and documents the cron extensions that Obsidian supports.

= Basic Format =

Cron expressions are written using 5 fields separated by spaces, as indicated below.

<pre>
.------------------------- minute (0 - 59)
| .--------------------- hour (0 - 23)
| | .----------------- day of month (1 - 31)
| | | .------------- month (1 - 12)
| | | | .--------- day of week (0 - 7) (Sunday = 0 or 7)
| | | | | .----- year (optional)
| | | | | | .- TimeZone ID (optional) * available as of Obsidian 4.2.0
| | | | | | |
* * * * * * *
</pre>

Ordinals indicate specific times, days or months that apply, while an asterisk (*) means there is no restriction on that field. For example, using an asterisk for the month field means the schedule runs during all months, while using "1" would mean it only runs in January. Using 5 asterisks will cause a job to run every minute.

The most basic cron expressions use simple ordinals or an asterisk for each field. As an example, the pattern <code>30 19 * * 5</code> means 7:30 PM on all Fridays.

Multiple Cron patterns may be specified for a single schedule by delimiting them with a semi-colon (e.g. <code>35 8 * * * *;20 12 * * *;40 16 * * *</code>). This means that the job will fire if it matches any of the supplied patterns.

As of '''Obsidian 4.2.0''', '''TimeZone ID''' support was added. This allows for a cron pattern to be associated with a specific TimeZone. The job will fire according to the timing of the TimeZone specified regardless of the default TimeZone of the Obsidian cluster. Supported TimeZone IDs can be found by running [https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs() TimeZone.getAvailableIDs()] in your runtime JVM.

= Special Characters and Allowed Values =

In addition to ordinals and asterisks, Obsidian supports special characters to support clearer or more complex expressions, as indicated below. These characters allow for ranges, lists and other special handling.

{| class="wikitable leftAlignTable"
! Field Name || Allowed Ordinal Values || Allowed Special Characters || Required
|-
| Minute || 0-59 || * / , - || Yes
|-
| Hour || 0-23 || * / , - || Yes
|-
| Day of Month || 1-31 || * / , - L W LW < > ≥ ≤ ~ SUN-SAT || Yes
|-
| Month || 1-12 or JAN-DEC || * / , - || Yes
|-
| Day of Week || 0-7 or SUN-SAT || * / , - L # || Yes
|-
| Year || 2010-2999 || * / , - || No
|-
| TimeZone ID || [https://docs.oracle.com/javase/7/docs/api/java/util/TimeZone.html#getAvailableIDs() TimeZone.getAvailableIDs()] || None || No
|}

== Special Character Usage ==

{| class="wikitable leftAlignTable"
! Special Character || Examples || Description
|-
| Asterisk (*) || <code>0 0 * * *</code><br/>(run every midnight) || Asterisks indicate that the expression will match for all values of the field. For example, using an asterisk in the 4th field (month) would indicate every month.
|-
| Forward slash (/) || <code>0/2 * * * *</code><br/>(every even minute) || Forward slashes are used to describe increments. For example, 0/15 or */15 in the 1st field (minutes) would indicate the 0th minute of the hour and every 15 minutes thereafter. The value before the slash indicates the start value, so 1/2 for the 1st field (minutes) would indicate every odd minute.
|-
| Comma (,) || <code>0/5,7 * * * *</code><br/>(every 5 minutes, and at 7th minute) || Commas are used to separate items of a list. For example, using "MON,WED,FRI" in the 5th field (day-of-week) would mean Mondays, Wednesdays and Fridays. Commas can also be used to combine ranges and increments.
|-
| Hyphen (-) || <code>0-15 * * * *</code><br/>(run from 0th to 15th minute inclusive) || Hyphens are used to define ranges. For example, 1-3 in the 4th field (month) would indicate January through March inclusive. This could also be written as JAN-MAR.
|-
| Hyphen (-) with forward slash (/) || <code>0 8-20/3 * * * *</code><br/>(every 3rd hour from 8AM and 10PM) || Forward slashes are used to describe increments. The hyphen provides the boundaries for the increments. For example, 1-15/3 would be the equivalent of 1,4,7,10,13.
|-
| L || <code>0 0 * * 5L</code><br/>(midnight on last Friday of the month) || "L" stands for last, and can be used in the day-of-week or day-of-month fields. For example, "5L" in the day-of-week field would mean the last Friday of a given month. In the day-of-month field, "L" is used alone to specify the last day of the month.
|-
| W || <code>0 0 15W * *</code><br/> (midnight on weekday closest to the 15th of the month) || "W" is allowed for the day-of-month field. This is used to specify the weekday nearest the given ordinal. For example,specifying "15W" for the day-of-month field, the meaning is "the nearest weekday to the 15th of the month". If the 15th is a Saturday, the trigger will fire on Friday the 14th. If the 15th is a Sunday, the trigger will fire on Monday the 16th. If the 15th is a Tuesday, then it will fire on Tuesday the 15th. However if you specify "1W" as the value for day-of-month, and the 1st is a Saturday, the trigger will fire on Monday the 3rd, as it will not jump over the boundary of a month's days. The "W" character can only be specified when the day-of-month is a single day, not a range or list of days, or in reference to a proximity expression ( ≥ ≤ < > )
|-
| LW || <code>0 0 LW * *</code><br/> (midnight on weekday closest to the last day of the month) || "LW" is allowed for the day-of-month field. This is used to specify the weekday nearest the last day of the month. The "LW" instruction can only be specified when it is the only day-of-month value. Cannot be combined with a day-of-week value.'''As of Obsidian 4.10.5'''
|-
| Hash (#) || <code>0 0 * * 5#2</code><br/>(midnight on 2nd Friday of month) || The hash character is allowed for the day-of-week field, and must be followed by a number between one and five. It allows you to specify constructs such as "the second Friday" (5#2) of a given month.
|-
| Greater Than (>) || <code>0 0 TUE>10 * * *</code><br/>(midnight on the first Tuesday after the 10th) || The greater than character is allowed for the day-of-month field, must be preceded by a W or Day of Week expression (SUN-SAT) and followed by a day of month ordinal. It allows you to specify constructs such as "the first Tuesday after the 10th" or "the first weekday after the 20th". '''As of Obsidian 6.2.0.'''
|-
| Less Than (<) || <code>0 0 SAT<15 * * *</code><br/>(midnight on the first Saturday before the 15th) || The less than character is allowed for the day-of-month field, must be preceded by a W or Day of Week expression (SUN-SAT) and followed by a day of month ordinal. It allows you to specify constructs such as "the first Saturday before the 15th" or "the first weekday before the 5th". '''As of Obsidian 6.2.0.'''
|-
| Less Than Or Equal To (≤) || <code>0 0 W≤20 * * *</code><br/>(midnight on the first weekday on or before the 20th) || The less than or equal to character is allowed for the day-of-month field, must be preceded by a W or Day of Week expression (SUN-SAT) and followed by a day of month ordinal. It allows you to specify constructs such as "the first weekday on or before the 20th" or "the first Wednesday on or before the 9th". '''As of Obsidian 6.2.0.'''
|-
| Greater Than Or Equal To (≥) || <code>0 0 MON≥5 * * *</code><br/>(midnight on the first Monday on or after the 5th) || The greater than or equal to character is allowed for the day-of-month field, must be preceded by a W or Day of Week expression (SUN-SAT) and followed by a day of month ordinal. It allows you to specify constructs such as "the first Monday on or after the 5th" or "the first weekday on or after the 22nd". '''As of Obsidian 6.2.0.'''
|-
| Closest to (~) || <code>0 0 THU~5 * * *</code><br/>(midnight on the Thursday closest to the 5th) || The tilde is allowed for the day-of-month field, must be preceded by a W or Day of Week expression (SUN-SAT) and followed by a day of month ordinal. It allows you to specify constructs such as "the Sunday closest to the 8th" or "the weekday closest to the 14th". '''As of Obsidian 6.3.0.'''
|}

==Examples==

{| class="wikitable"
!Cron Pattern
!Explanation
|-
|style="white-space:nowrap"|<code>5 8 TUE≤14 2 * * America/Toronto</code>
|At 8:05AM on the Tuesday on or before the 14th during February in Eastern Standard Time
|-
|style="white-space:nowrap"|<code>0 12 W≥1,W≥15 * *</code>
|At 12:00PM on the weekday on or after the 1st, the weekday on or after the 15th
|-
|style="white-space:nowrap"|<code>0 16 SUN~5,W~10 * *</code>
|At 4:00PM on the Sunday closest to the 5th, the weekday closest to the 10th
|}

= Shortcut Expressions =

Obsidian supports some shorthand expressions to easily input common expressions. These start with the at sign (@).

{| class="wikitable leftAlignTable"
! Shortcut || Long-Form Expression || Description
|-
| @yearly || 0 0 1 1 * || Run once a year, on Jan 1st at midnight.
|-
| @annually || 0 0 1 1 * || Same as @yearly.
|-
| @monthly || 0 0 1 * * || Run once a month, on the 1st at midnight.
|-
| @weekly || 0 0 * * 0 || Run once a week, on Sunday at midnight.
|-
| @daily || 0 0 * * * || Run once a day, at midnight.
|-
| @midnight || 0 0 * * * || Same as @daily.
|-
| @hourly || 0 * * * * || Run on the hour, every hour.
|}

= Recurrence =

In addition to Cron syntax, Obsidian supports special recurrence syntax to allow expression of recurring intervals that can't be defined in a single Cron pattern. For example, if you wanted to run a job every 7 minutes, every 2 weeks or every 5 months, none of these can be expressed in a single Cron pattern.

Obsidian recurrence patterns always start with <code>@recur</code> and are followed by an interval type. Recurring intervals are calculated from the last execution time, if available. Otherwise, the initial execution will be at the start time of the job schedule. This means that when you schedule a new recurrence, it will execute first when the schedule starts, and then at the interval specified after that.

'''Note:''' If an ad hoc job is submitted or a failed job is resubmitted, it will cause the next recurrence interval to be delayed since the next execution time will be based on the last available job.

== Interval Types ==
* <code>min</code> or <code>minute</code> or <code>minutes</code> - minutes
* <code>h</code> or <code>hour</code> or <code>hours</code> - hours
* <code>d</code> or <code>day</code> or <code>days</code> - days
* <code>w</code> or <code>week</code> or <code>weeks</code> - weeks
* <code>mon</code> or <code>month</code> or <code>months</code> - months

==Sample Patterns==

* <code>@recur 7 minutes</code> - every 7 minutes
* <code>@recur 7 h</code> - every 7 hours
* <code>@recur 3 day</code> - every 3 days
* <code>@recur 3 weeks</code> - every 3 weeks
* <code>@recur 5 mon</code> - every 5 months

==Recurrence Start DateTime==
The recurrence pattern may include an optional start datetime. This datetime would be used as a basis for calculating recurrence (if before the effective date of the schedule window), or as the initial recurrence datetime (if after the effective datetime of the schedule window). Without this value, any recurrence pattern without history for the given schedule window will have its first runtime at the effective datetime of the schedule window. When the schedule effective date is greater than the start datetime specified, the first calculated recurrence value that is greater than or equal to the schedule effective datetime will be the first scheduled runtime. See examples below.

This functionality can be used to ensure a job fires on consistent recurrence intervals when migrating between environments, perhaps using the [[Initializing and Restoring]] functionality.

'''DateTime Format''' is <code>yyyy-MM-dd HH:mm</code>

===Examples===

{| class="wikitable"
!Recur Pattern
!Effective Date
!End Date
!First Runtime
!Explanation
|-
|style="white-space:nowrap"|<code>@recur 5 month 2015-02-01 02:00</code>
|style="text-align:center;white-space:nowrap"|<code>2015-03-15 12:00</code>
|style="text-align:center;white-space:nowrap"|∞
|style="text-align:center;white-space:nowrap"|<code>2015-07-01 02:00</code>
|The recurrence start datetime is less than the effective date, but the first calculated recurrence is greater than the schedule effective window.
|-
|style="white-space:nowrap"|<code>@recur 20 weeks 2015-01-15 00:00</code>
|style="text-align:center;white-space:nowrap"|<code>2015-12-20 00:00</code>
|style="text-align:center;white-space:nowrap"|∞
|style="text-align:center;white-space:nowrap"|<code>2016-03-10 00:00</code>
|The recurrence start datetime is less than the effective date, but the first (<code>2015-06-04 00:00</code>) and second(<code>2015-10-22 00:00</code>) calculated recurrences are also less than the schedule effective window.
|-
|style="white-space:nowrap"|<code>@recur 20 weeks 2015-01-15 00:00</code>
|style="text-align:center;white-space:nowrap"|<code>2015-12-20 00:00</code>
|style="text-align:center;white-space:nowrap"|<code>2016-01-31 23:59</code>
|style="text-align:center;white-space:nowrap"|'''None'''
|The recurrence start datetime is less than the effective date, as are the first (<code>2015-06-04 00:00</code>) and second (<code>2015-10-22 00:00</code>) calculated recurrences. The third calculated recurrence (<code>2016-03-10 00:00</code>) is greater than the effective date but is also greater than the ''end date''. This results in no scheduled executions.
|-
|style="text-align:center;white-space:nowrap"|<code>@recur 20 weeks 2015-01-15 00:00</code>
|style="text-align:center;white-space:nowrap"|<code>2015-01-01 00:00</code>
|style="text-align:center;white-space:nowrap"|<code>2016-01-31 23:59</code>
|style="text-align:center;white-space:nowrap"|<code>2015-01-15 00:00</code>
|The recurrence start datetime is greater than the effective date and less than the end date. Initial recurrence will start at the specified start datetime.
|}

Conflicts

2026-07-31T14:49:49Z

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

Obsidian supports completely customizable job conflict configuration combined with custom prioritization. The web application contains an [[Admin_Job_Conflicts|easy-to-use interface]] to configure these conflicts.

Any number of jobs can be configured to not run concurrently, even if scheduled to run at the same time. When jobs are set as conflicting and are scheduled to run at the same time, the chosen prioritization will determine the order of execution of the scheduled jobs. Any termination state, either success or failure, will release the next lower priority job to complete. These conflicts work even across multiple hosts.

If a job which isn't using the ''Conflicted'' recovery type cannot be executed within its [[Job_Features#Recovery|Pickup Buffer]], it will be marked as ''Conflict Missed'', though it can be resubmitted later if desired. When you configure job conflicts, you will want to choose [[Job_Features#Recovery|Recovery]] settings carefully (''Recovery Type'' and ''Pickup Buffer'').

== Using Conflicted Recovery Type ==
If you are using ''Conflicted'' recovery type, the ''Pickup Buffer'' minute setting is not used when determining whether to run a job that had been conflicted. When the higher priority conflict(s) clear, a job with ''Conflicted'' recovery will always run, though the ''Pickup Buffer'' is still used in other scenarios, such as outages.

== Using Non-Conflicted Recovery Types ==
When using ''Recovery Types'' other than ''Conflicted'', in the event of a conflict, if the waiting lower-priority job cannot be picked up and started within the configured number of ''Pickup Buffer Minutes'' past the original scheduled time, the scheduled job will be marked as ''Conflict Missed'' and will not be run.

== Jobs in Multiple Conflict Groups ==
A job can be put into multiple conflict groups, each having their own separate priority ordering.

When selecting available non-conflicted jobs to run, Obsidian inspects the conflict groups in the order provided when they are saved (from left to right in the user interface), and selects the highest priority available job before moving onto the next conflict group. When priority is significant and varies across different groups, ensure your conflict groups are in the desired order.

=== Example ===
To demonstrate, in the example below, if Jobs 2 and 3 are ready for execution, the configuration below will cause Job 3 to be executed first since it is found in the first conflict group. If the conflict groups were saved in the reverse order, Job 2 would be executed first. In addition, if Job 1 were also available for execution in the example below, it would prevent Job 3 from executing, which would result in Job 2 running simultaneously with Job 1.

[[Image:MultiConflictExample.png]]

Clustering

2026-07-31T14:49:48Z

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

Obsidian provides zero-configuration clustering. If you want to add a new scheduler to the cluster or replace an existing node, simply start it up pointing to your Obsidian database, and it will join the pool and begin executing jobs immediately. You may wish to consult [[Recovery_%26_Failover|Recovery & Failover]] for additional details on scheduler behaviour.

Obsidian's clustering works by coordinating effort of various nodes through a central relational database such as MySQL or Oracle. Each set of Obsidian tables corresponds to a separate cluster instance. For example, you may have separate QA and production databases. If you run multiple Obsidian schedulers pointing to the same database, they will run in the same cluster. This can also be accomplished by having Obsidian tables in the same database but using a separate [[Advanced_Configuration#Table Prefixes|table prefix]].

No cluster configuration is ever required, allowing you to adapt quickly to new needs.

'''All scheduler nodes, any [[Deployment_Diagram|deployed]] Web Admin WARs and the database should be time synchronized from the same source and to the same timezone.'''

Scheduler nodes may have different timezones that adhere to the same time rules (are functionally equivalent). This is implemented via the [[https://docs.oracle.com/javase/6/docs/api/java/util/TimeZone.html#hasSameRules(java.util.TimeZone) TimeZone.hasSameRules(TimeZone)]] method.

== Load Sharing Algorithm ==
The clustering algorithm in Obsidian is designed to take full advantage of the available nodes in the cluster. The scheduler takes into account how many other nodes are running, and how many jobs need to be run at the current time in order to provide load balancing. That is one key difference in Obsidian since it values load-sharing over second-level precision, since most applications don't require it. Other schedulers, by contrast, do clustering by having all nodes immediately try to claim a job for execution, which can result in one node claiming multiple jobs while others remain idle.

You can add new cluster nodes at any time and they will automatically join the pool, and the load-sharing and scheduling algorithm will adapt right away.

==Host Restrictions ==
Jobs can be restricted to run only on specified hosts. This allows you to use Obsidian in a multi-host environment, even when certain jobs can only run on one of the hosts in the cluster. More details can be found at [[Job Features#Host Restrictions|Job Features]], or you can view details on the corresponding [[Admin_Jobs#Adding_.26_Editing_Jobs|configuration screen]].

==Host Preference ==
In addition to host restrictions, Obsidian supports the concept of host preference. For each job, you can select this option to enable prioritizing specific hosts for job execution. When a job configured with this setting is ready for execution, Obsidian will select the most preferred host to execute the job on, and if no preferred host is available, execution will fall back to any available host. This is configurable on the [[Admin_Jobs#Adding_.26_Editing_Jobs|job configuration screen]].

Chaining

2026-07-31T14:49:48Z

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

Obsidian supports dynamic job chaining between two jobs. All chaining configuration is managed in the [[Admin Job Chains|job chains]] portion of the admin web application.

Chaining can be triggered simply by the state of the queued job, or conditionally, based on the saved results of a successfully completed job.

A job can be chained to any other job. By default, chaining between two jobs will trigger when the source job either completes or fails, but any source termination state can be selected to trigger the chain. Chain configurations can be disabled and re-enabled at any time. Chaining can also be constrained to a schedule, using a standard cron schedule.

Chaining will only trigger for a target job if the job has the state Enabled or Chain Active at the trigger time. A job that is Disabled or Ad Hoc Active will not be chained.

=Conditional Chaining=

Release 1.4 introduced conditional chaining. This feature allows for jobs to be triggered when a successfully completed source job saves [[Implementing_Jobs#Job_Results|job results]] which match a set of defined conditions. When setting up the conditional evaluations, you specify one or more variable evaluations that must be matched to cause the chain to fire. A condition is comprised of the variable name, an operator, and one or more values

For numeric operators, your conditions are coerced to the numeric value types that your source job saves (e.g. integer, etc.).

'''Note:''' All conditions must be met for the chain to be successfully triggered (i.e. they are ANDed together). Additionally, operators match if ''any'' saved value matches the operator. This is important to remember if a job saves more than one value under the same variable name.

The supported operators are:
* '''Equals/Not Equals''' - A direct equality comparison (case-sensitive). If no value is saved, Not Equals evaluates to true.
* '''Exists/Not Exists''' - Uses presence of a saved variable to match.
* '''In/Not In''' - Triggered if ''any'' saved job result value under the name matches a defined value (case-sensitive). If no value is saved, Not In evaluates to true.
* '''Contains''' - String contains (case-sensitive).
* '''Starts With/Ends With''' - String starts with/ends with match (case-sensitive). An equal string will also trigger either of these operators.
* '''Regexp''' - Regular expression match based on Java's Pattern class.
* '''Less Than/Less Than Or Equal/Greater Than/Greater Than Or Equal''' - Numeric only: values are coerced to an integer or decimal value.

=Chaining Results=
All chaining evaluations are stored. If chaining is triggered, or if it fails based on a conditional evaluation, the [[Admin Job Activity|job activity]] view shows which jobs a source job triggered and also which job triggered a chained job. When chaining misses because the source state didn't match any of those configured, target job is in an unchainable state, chaining configuration is disabled or source completion time was outside the constraints of a provided chaining schedule, a detail record with state Chain Skipped will still be available for review with the detail of why chaining was not triggered.

Built-in Jobs

2026-07-31T14:49:47Z

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

Obsidian comes bundled with free [[Admin_Jobs|jobs]] for common tasks. These are provided in addition to [[Scripting Jobs]] to reduce implementation and testing time for common job functions.

We have open-sourced our built-in convenience jobs 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>.

= File Processing Jobs =

These jobs are provided to provide common basic file operations, such as file cleanup (deletion) and archiving. These jobs can be used to reduce the amount of code your organization needs to write.

== File Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileCleanupJob</code>

This job deletes files in specified paths based on one or more file masks (using regular expressions).

It supports the following configuration options:

* ''Directory (1 or more Strings)'' - A directory to scan for files. If recursive processing is enabled, child directories are also scanned.
* ''File Mask (0 or more Strings)'' - A regular expression that files must match to be deleted. This is based on <code>java.util.regex.Pattern</code>. To match all files, remove all configured values or use ".*" without quotes. If multiple values are used, files are eligible for deletion if they match any of the file masks.
* ''Abort on Deletion Failure (Boolean)'' - If deletion fails, should we fail the job?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb).
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d).
* ''Recursive (Boolean)'' - Whether files in subdirectories of the configured directories should be checked for matching files.

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''shouldDelete'' - Determines if a file should be deleted.
* ''deleteMatchingFile'' - Deletes a matching file and saves a job result for its path.
* ''matchesAge'' - Determines if a file matches any age conditions (i.e. ''Minimum Time Since Modified''), or true if none are configured.
* ''matchesMask'' - Determines if a file matches any configured file masks, or true if none are configured.
* ''matchesSize'' - Determines if a file matches size conditions, or true if none are configured.
* ''processDirectory'' - Enumerates files in configured directories and calls ''shouldDelete'' and ''deleteMatchingFile'' as necessary.

'''Sample Configuration'''

[[Image:FileCleanup.png]]

== File Archive Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileArchiveJob</code>

This job archives files passed in via a chained job's saved results. Therefore, it is intended to be used as a chained job only. One or more accessible absolute file paths can be passed in via job results called 'file'. Each one will be processed for archiving. For example, if you have a job that generates two files called 'customers.txt' and 'orders.txt', you will use <code>Context.saveJobResult(String, Object)</code> to save a value for each absolute file path (e.g. 'C:/customers.txt' and 'C:/orders.txt').

It supports the following configuration options:

* ''Archive Directory (1 or more Strings)'' - A directory to where an archive copy is placed.
* ''Rename Pattern (String)'' - How should we name the archive file? Rename patterns support the following tokens delimited by < and >:
** <code><filename></code> is the full original file name (e.g. 'abc.v1.txt')
** <code><basename></code> is the file with the last extension stripped (e.g. 'abc.v1')
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
** For example, to archive a GZIP version of a file with a timestamp with the extension 'gz', you can use the rename pattern <code><basename>.<ts:yyyy-MM-dd-HH-mm-ss>.<ext>.gz</code>.
** To maintain the original name, simply use the pattern <code><filename></code>.
* ''Delete Original File (Boolean)'' - Should we remove the original file after archiving?
* ''GZIP (Boolean)'' - Should the target archive file be compressed using GZIP?
* ''Overwrite Target File (Boolean)'' - If the archive file to be created already exists, should we overwrite it, or fail instead?
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''determineArchiveFilename'' - Determines the name of the archive file based on the configured "Rename Pattern".
* ''processFile'' - For each input file, determines the archive file name and copies the original file to the archive.
* ''processDelete'' - If the original file is to be deleted, this method handles deleting the original file. If deletion fails, the job will fail, so if you wish to change his behaviour, you can override this method.

'''Sample Configuration'''

[[Image:FileArchiveJobConfig.png]]

== File Scanner Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.FileScannerJob</code>

This job locates files in a directory matching one or more file masks (using Java regular expressions) and stores the result via source job results stored under the name <code>file</code> as absolute paths (Strings).

This job is intended to be conditionally chained to a job that knows how to process the results.

''Go File Pattern'' may used to ensure that files in the configured ''Directory'' are only picked up and saved if an expected token file exists. If ''Delete Go File'' is set to true, any found token files will be deleted. If this deletion fails, the job will abort and no <code>file</code> results are saved. Successfully deleted go files are stored as job results under the name <code>deletedGoFile</code>.

The job supports the following configuration options:

* ''Directory (String)'' - A directory to scan for files.
* ''File Pattern (1 or more Strings)'' - One or more file patterns (using <code>java.util.regex.Pattern</code>) that a file name must match to be considered a match. If any one of the configured patterns is a match, the file is considered a match.
* ''Go File Pattern (String)'' - A file pattern (using <code>java.util.regex.Pattern</code>) that must match at least one file in in the ''Go File Directory'' (or main ''Directory'' if not supplied) in order for files to be processed and saved as job results.
* ''Go File Directory (optional String)'' - The directory where we look for files matching the ''Go File Pattern''. If missing, the value for ''Directory'' is used.
* ''Delete Go File (Boolean)'' - If we find one or more go files, should we delete them? If deletion fails, the job will fail.
* ''File Size Minimum (String)'' - The minimum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''File Size Maximum (String)'' - The maximum size in bytes a file must be to be deleted. File sizes can be specified in bytes, kilobytes, megabytes or gigabytes (e.g. 10b, 100kb, 20mb, 2gb). As of Obsidian 6.0.1
* ''Minimum Time Since Modified (String)'' - The minimum age of a file to be deleted, based on the modified time. This can be specified in seconds, minutes, hours and days (e.g. 10s, 5m, 24h, 2d). As of Obsidian 6.0.1

=== Customization ===
If you wish to tweak or customize behaviour of this job, it can be subclassed. The following methods may be overridden or extended by calling ''super'' methods:

* ''onStart'' - Called on job startup.
* ''onEnd'' - Called on job end, regardless of success or failure.
* ''listFiles'' - Lists files within the directory using the supplied patterns.
* ''postProcessFiles'' - This is a hook method called after all job results are saved and go files are deleted if applicable. It is called with all valid files that were found.
* ''deleteGoFiles'' - Deletes all found go files, saving a result if successful and throwing a RuntimeException if failing. This can be overriden to customize handling of failures.

'''Sample Configuration'''

[[Image:FileScannerConfig.png]]

= Maintenance Jobs =

These jobs are provided to help maintain the Obsidian installation. Automatic schedule configuration can be disabled via <code>com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true</code> configuration.

== Job History Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.JobHistoryCleanupJob</code>

This job will delete job history and related records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain, including expired job schedules. By default it is set to 366, but you may configure it to any desired value.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run '@daily' keeping the last 380 days of history.

== Log Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.LogCleanupJob</code>

This job will delete log database records beyond a configurable age in days. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>level</code> corresponds to the logging level of events to delete. You may specify multiple values, and the "ALL" option will result in all records matching the age setting being deleted. Valid levels to configure are: <code>FATAL</code>, <code>ERROR</code>, <code>WARNING</code>, <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>.

It is common to only delete lower severity level events, such as <code>INFO</code>, <code>DEBUG</code>, and <code>TRACE</code>, but retain higher severity messages.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations as follows:
* 1:00 AM for DEBUG/TRACE keeping the last 30 days of event logs.
* 1:30 AM for INFO keeping the last 60 days of event logs.
* 2:00 AM for WARNING/ERROR keeping the last 120 days of event logs.
* 2:30 AM for FATAL keeping the last 185 days of event logs.

== Notification Cleanup Job ==

''Introduced in Obsidian 4.9.0''

'''Job Class:''' <code>com.carfey.ops.job.maint.NotificationCleanupJob</code>

This job will delete notification database records beyond a configurable age in days. Optionally you may constrain this to specific subscribers. This is useful for keeping the database compact and clearing out old, unneeded data.

The value for <code>maxAgeDays</code> corresponds to the maximum age for records to retain. By default it is set to 365, but you may configure it to any desired value.

The value for <code>subscriber</code> corresponds to the subscriber address(es) of whose notifictaions should be deleted. No validation is performed against this value to allow for subscriber changes without requiring corresponding job configuration changes.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:30 AM on the 1st of the month keeping the last 120 days of history.

== Disabled Job Cleanup Job ==

'''Job Class:''' <code>com.carfey.ops.job.maint.DisabledJobCleanupJob</code>

This job cleans up jobs that have been disabled for the last configured number of days and have no future non-disabled schedule windows.

The value for <code>maxDisabledDays</code> corresponds to how many days in the past a job must have been disabled to be a candidate for being deleted.

'''Note:''' We recommend high volume users schedule the job weekly or less frequently and to schedule it for a non-peak time.

'''As of Obsidian 5.2.1''', this job is configured during new installations to run at 3:00 AM on the 1st of the month keeping the last 185 days of history.

= Script Job =
This job is a convenience job to execute any script, command or other executable file on any platform.

'''Job Class:''' <code>com.carfey.ops.job.script.ScriptFileJob</code>

This job enables you to specify an existing script, command or other executable to invoke/execute. Validation of the file's existence and executable state is done only at runtime. You must ensure that the file exists or is accessible via environment variables and in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Advanced_Options|Fixed Hosts]]. This job uses [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html ProcessBuilder], so refer to it for expected behaviour.

This job supports best-effort interruption as an [[Implementing_Jobs#Interruptable_Jobs|Interruptable job]]. It is best effort in that it only destroys the underlying process that invoked the script, but cannot ensure that anything the script has invoked has terminated.

* ''Script with Arguments (1 or more Strings)'' - The first value is a path to the execution script (or other executable), which is typically fully qualified, or relative to the working directory. The additional values are any required arguments for the command. On *nix, if you are invoking a script, you may need to prefix the command with "./", e.g. <code>./script.sh</code>. Corresponds to the [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#ProcessBuilder(java.lang.String...) ProcessBuilder(java.lang.String...) constructor].
* ''Copy Obsidian Process' Environment (Boolean)'' - Do you want the runtime environment to be copied from that which is running the Obsidian process? Defaults to ''true''. If set to ''false'', the environment is cleared. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].
* ''Success Exit Code (Integer)'' - The exit code that designates success. Any exit code not matching this value will result in a job failure. Defaults to ''0''.
* ''Working Directory (String)'' - The desired working directory for the script. If no special working directory is required, set to the directory containing the target script. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#directory() ProcessBuilder.directory()].
* ''Environment Parameter Key Value Pairs (0 or more pairs of Strings)'' - Key/Value pairs to be set on the execution environment. These values are set just before execution and will override any existing values copied from the Obsidian Process if ''Copy Obsidian Process' Environment'' was set to true. See [http://docs.oracle.com/javase/7/docs/api/java/lang/ProcessBuilder.html#environment() ProcessBuilder.environment()].

'''Sample Configuration'''

[[Image:ScriptFileJobConfig.png]]

== Note on Windows ==
When running the job on Windows, users often encounter an error like the following:

<pre>Cannot run program "run.bat" (in directory "C:\test"): CreateProcess error=2, The system cannot find the file specified.</pre>

This normally means you need to run the command through the Windows command interpretor, using <code>cmd /C</code>.

To do this, instead of supplying the file to execute as a first value for ''Script with Arguments'', the supply the values "cmd" and "/C" as separate values, then any others you require, as illustrated below.

<pre>
Script with Arguments:
cmd
/C
run.bat
</pre>

= MySqlBackupJob =

This is a convenience job to utilize the mysqldump utility to extract a backup and store on the filesystem. A timestamp is appended to the filename prefix specified to protect against overwrites. The optional mysqldump options are not validated and will result in runtime failures if they are invalid. Likewise, all paths specified are not verified and are only required to be available on the scheduler host at runtime. If the mysqldump executable is not found at runtime, change the ''mysqldump Executable'' to have the fully qualified path.
* ''Fully qualified export path (String)'' - The directory where you want the backups stored.
* ''Filename prefix (String)'' - The filename prefix to use for the backup files.
* ''Username (String)'' - The user for the mysqldump command.
* ''Password (String)'' - The user's password for the mysqldump command.
* ''Database (String)'' - The database to backup.
* ''Hostname or IP Address (optional String)'' - The host of the MySQL database. If not provided, assumes localhost.
* ''GZip file? (Boolean)'' - Determines whether the backup file is compressed using GZip.
* ''mysqldump option (0 or more Strings)'' - Any number of desired mysqldump options can be specified.
* ''mysqldump Executable (String)'' - Fully qualified path to mysqldump executable.

'''Sample Configuration'''

[[File:MySqlBackupJobConfig.png]]

= Shell Script Jobs =
'''Deprecated.''' Use [[#Script_Job|Script Job]] instead.

These jobs are provided to give convenient access to shell scripting. ''Not supported on Windows-based platforms.''

== Shell Script Job ==

'''Deprecated.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptJob</code>

This job enables you to specify the actual contents of a shell script and have it execute on the runtime host. At runtime, the script will be written to disk, marked as executable and then executed. The script is then cleaned up. The shell script provided should be completely self-sufficient with any desired interpreter directives included and no assumptions or expectations of environment variables.

== Shell Script Execution Job ==
'''Deprecated.''' Use [[#Script_Job|Script Job]] instead.

'''Job Class:''' <code>com.carfey.ops.job.script.ShellScriptExecutionJob</code>

This job enables you to specify an existing shell script to execute. Validation of the script's existence and executable state is done only at runtime. You must ensure that the script exists in an executable state on all Obsidian Hosts in the cluster or restrict the job to the necessary [[Admin_Jobs#Execution_.26_Pickup|Fixed Hosts]].

= Miscellaneous Jobs =

== Database File Export Job ==

'''Job Class:''' <code>com.carfey.ops.job.db.DatabaseFileExportJob</code>

''Introduced in Obsidian 5.1.0''

This job produces a file export based on a database connection and a query.

The job supports the following configuration options:

* ''SQL Query (String)'' - The source query that produces the desired export results.
* ''JDBC Connection Provider (optional Class)'' - A class implementation of [https://web.obsidianscheduler.com/obsidianapi/com/carfey/ops/job/db/DatabaseConnectionProvider.html DatabaseConnectionProvider] that provides a connection - allows for use of an existing connection pool or other means of obtaining a connection. If not used, must used the URL/username/password configuration for connections.
* ''JDBC DB URL (optional String)'' - JDBC URL. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB username (optional String)'' - JBDC database username. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''JDBC DB password (optional String)'' - JBDC database password. Relies on JDBC driver class being available on the classpath. If not used, must used the JDBC Connection Provider for connections.
* ''File type (String)'' - One of CSV, JSON, XML.
* ''File name pattern (String)'' Filename patterns for the generated filename support the following tokens delimited by < and >:
** <code><custom:paramname></code> is a means of automatically substituting in other parameters defined on the job.
** <code><ext></code> is the last file extension (e.g. 'txt')
** <code><ts:dateformat></code> corresponds to a timestamp formatted in the supplied SimpleDateFormat pattern (e.g. <code><ts:yyyy-MM-dd-HH-mm:ss></code>)
** other literals outside of < or >, or inside of < and > but not matching any preceding tokens.
* ''CSV Delimiter (optional String)'' - If CSV export is selected, can choose an alternative delimiter other than comma (,). Single character.
* ''CSV Quote Character (optional String)'' - If CSV export is selected, can choose an alternative quote character other than double quotes ("). Single character.
* ''CSV Escape Character (optional String)'' - If CSV export is selected, can choose an alternative escape character other than double quotes ("). Single character.
* ''CSV Line End String (optional String)'' - If CSV export is selected, can choose an alternative line end string other than newline (\n).
* ''Datetime format (String)'' - SimpleDateFormat format applied to java.sql.Timestamps.
* ''Date format (String)'' - SimpleDateFormat format applied to java.sql.Dates.

== REST Invocation Job ==

'''Job Class:''' <code>com.carfey.ops.job.rest.RESTInvocationJob</code>

''Introduced in Obsidian 5.1.0''

This job calls a REST endpoint using the designated method and payload, if applicable. Expects the response code to be in the 2xx series to be a success, all others are treated as failures. Expects payload and response to always be Strings. Supports basic authentication. Response is saved to job results to allow for use by chained jobs.

The job supports the following configuration options:

* ''URL Target (String)'' - Endpoint URL.
* ''REST API Method (String)'' - GET, PUT, POST, DELETE supported.
* ''Payload (optional String)'' - Required for PUT/POST, not permitted for GET/DELETE.
* ''Basic Authentication Username (optional String)'' - If wanting to add basic authentication, provide username and password.
* ''Basic Authentication Password (optional String)'' - If wanting to add basic authentication, provide username and password.

== Obsidian Execution Statistics Job ==

'''Job Class:''' <code>com.carfey.ops.job.schedule.ObsidianExecutionStatisticsJob</code>

''Introduced in Obsidian 6.4.0''

This job runs against the job activity stored in Obsidian to collect execution statistics. These statistics are then available via the UI, the [[REST_API|REST API]] and [[Embedded_API|Embedded API]]. Job statistics use the data stored in job activity (history) and will not collect statistics for any history removed via [[Built-in_Jobs#Job_History_Cleanup_Job|Job History Cleanup Job]]. Likely you should align the ''maximumDurationLookback'' configuration value with a value that represents the most data kept. For example, if you keep 6 months of job history, you wouldn't benefit from a ''year'' lookback as the stats would match the ''six month'' stats.

The job supports the following configuration options:

* ''durationUnit (String)'' - What statistics unit to calculate. Valid values: seconds, minutes, hours. Defaults to minutes. Multiple allowed.
* ''maximumDurationLookback (String)'' - How far back to collect statistics. One of day, two day, three day, five day, week, month, two month, three month, six month, year. Defaults to three month. Large durations will calculate and store stats for smaller durations; e.g. two day includes day.

[[File:Obsidian-6.4.0-Obsidian-Execution-Job-Statistics-Config.png]]

Authenticator

2026-07-31T14:49:47Z

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

Obsidian ships with four built-in authenticators: native (database), LDAP, OAuth (OIDC), and SAML 2.0. A custom authenticator can also be implemented by extending the authenticator interface. The active authenticator is selected by the ''com.carfey.suite.security.Authenticator'' property in the Obsidian configuration file (''com.carfey.properties'' or YAML equivalent).

== OAuthAuthenticator (OIDC SSO) ==

''OAuthAuthenticator'' enables Single Sign-On via any OIDC-compliant identity provider. It implements OAuth 2.0 Authorization Code + PKCE (S256). Full configuration reference: [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Advanced Configuration — OAuth / OIDC Authentication Properties]].

=== How browser login works ===

When ''OAuthAuthenticator'' is active, the Obsidian login page shows a single "Sign in with <displayName>" button instead of a username/password form. Clicking the button redirects the user to the identity provider's login page. After successful authentication at the IdP, the browser is redirected back to Obsidian with an authorization code. Obsidian exchanges the code for tokens at the IdP token endpoint and validates the id_token signature, issuer, audience, expiry, and nonce.

No Obsidian database user record is created or required. Identity and roles come entirely from the validated token.

=== User identity and display ===

Obsidian uses the ''sub'' claim of the id_token as the stable internal user ID (stored in audit logs and session state). The ''sub'' claim is IdP-guaranteed unique and is never reassigned. A separate ''claim.displayName'' property (default: ''preferred_username'') controls what name appears in the Obsidian UI nav bar. Changing ''claim.displayName'' does not affect audit logging.

=== Roles from IdP groups ===

After the code exchange, Obsidian reads a configured groups claim from the id_token (or access token, or userinfo endpoint). Each group value is mapped to an Obsidian role via indexed ''role.<idx>.group'' / ''role.<idx>.roleName'' properties. At least one mapping to the ''Admin'' role is required. A user whose groups do not match any mapping authenticates successfully but has no access to role-gated actions (same behavior as a DB/LDAP user with no assigned roles).

Valid Obsidian roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles following the ''<folder>-(Write|Author|Operator)'' convention (e.g. ''Maintenance-Author'').

=== REST API Bearer authentication ===

REST clients can authenticate to Obsidian's REST API using a signed JWT access token in the ''Authorization: Bearer <token>'' header. Obsidian validates the token locally using cached JWKS keys. The userinfo endpoint is not called on the Bearer path. The client must have the ''API'' Obsidian role.

=== Logout modes ===

Two logout modes are supported:

* '''local''' (default) — Obsidian invalidates its own session. The IdP session remains active (useful for SSO environments where other applications share the IdP session).
* '''rp''' — RP-initiated logout. Obsidian redirects the browser to the IdP's ''end_session_endpoint'', which terminates the IdP session. Requires the IdP to expose ''end_session_endpoint'' in its discovery document.

=== v1 limitations ===

* Opaque (non-JWT) access tokens are not supported on the REST/Bearer path.
* No ''jti'' replay protection (mitigate with short token lifetimes at the IdP).
* Microsoft Entra multi-tenant apps are not supported.
* No post-login IdP session validity check (mitigate with a short session timeout in ''web.xml'').
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static group→role pairs; the runtime supports unlimited.

== SAMLAuthenticator (SAML 2.0 SSO) ==

''SAMLAuthenticator'' enables Single Sign-On via any SAML 2.0 identity provider, using Service Provider (SP) initiated browser flows. The class to configure is ''com.carfey.suite.security.saml.SAMLAuthenticator''. Full configuration reference: [[Advanced_Configuration#SAML_Authentication_Properties|Advanced Configuration — SAML Authentication Properties]].

=== How browser login works ===

When ''SAMLAuthenticator'' is active, the Obsidian login page shows a single "Sign in with <displayName>" button instead of a username/password form. If ''displayName'' is left blank the button reads "Sign in with SSO". Clicking it has Obsidian build a SAML ''AuthnRequest'' — signed with the SP keystore when ''signRequests'' is enabled — and redirect the browser to the identity provider using the HTTP-Redirect binding. After successful authentication at the IdP, the IdP posts a SAML response back to Obsidian's Assertion Consumer Service (ACS) endpoint.

Obsidian validates the response status, the assertion signature against the IdP signing certificate published in the IdP's federation metadata, the issuer, the ''Destination'' and ''Recipient'' values, the ''AudienceRestriction'' against your SP entity ID, and the ''NotBefore'' / ''NotOnOrAfter'' time window (widened by ''clockSkewSeconds'', default 60 seconds). On success Obsidian replaces the browser session with a new one and returns the user to the page originally requested, or to ''/''.

No Obsidian database user record is created or required. Identity and roles come entirely from the validated assertion.

A failed callback invalidates the session and returns the browser to the login page. The underlying cause is written to the Obsidian log with a short correlation id that is not shown to the user.

=== Service Provider endpoints ===

All SAML endpoints live under ''/saml'' in the Obsidian web application:

* ''/saml/login'' — starts SP-initiated login and issues the ''AuthnRequest''.
* ''/saml/callback'' — the Assertion Consumer Service, receiving the IdP's ''SAMLResponse'' by HTTP-POST. Your ''assertionConsumerServiceUrl'' must point here.
* ''/saml/logout'' — starts logout from the Obsidian UI.
* ''/saml/slo'' — single logout endpoint, handling an IdP-initiated ''LogoutRequest'' and the IdP's ''LogoutResponse''.
* ''/saml/metadata'' — serves Obsidian's SP metadata document for registration at the IdP.

=== Identity provider metadata ===

Obsidian reads IdP federation metadata from either ''idpMetadataUrl'' or ''idpMetadataFile'', and caches it for ''metadata.ttlHours'' (default 24). Signing certificates come from that metadata, so key rotation at the IdP is picked up on the next refresh. If a refresh fails, Obsidian logs a warning and continues with the cached copy.

=== User identity and display ===

By default Obsidian uses the assertion's ''NameID'' as the stable internal user ID stored in audit logs and session state. Binding a different attribute with ''attribute.user'' is supported but logs a warning at startup, because a value the IdP may reassign risks one user inheriting another's history. A transient ''nameIdFormat'' also logs a warning: transient NameIDs are regenerated for each session, so every login appears as a new user. ''attribute.displayName'' optionally supplies the name shown in the Obsidian UI nav bar.

=== Roles from SAML attributes ===

Obsidian reads group memberships from the assertion attribute named by ''attribute.groups'', or matched by ''attribute.groups.friendlyName''. ''attribute.groups.valuePath'' and ''attribute.groups.stripPrefix'' help with structured or prefixed values such as directory distinguished names. Each group value is mapped to an Obsidian role via indexed ''role.<idx>.group'' / ''role.<idx>.roleName'' properties, exactly as for OAuth, and at least one mapping to the ''Admin'' role is required.

By default ('''requireRole=true'''), a user whose groups match no role mapping cannot complete login. Setting ''requireRole=false'' lets such a user authenticate but with no access to role-gated actions, the same behavior as a DB or LDAP user with no assigned roles.

''dynamicRole.prefix'' and ''dynamicRole.suffix'' derive folder role mappings from your root job folders at startup, so adding a new root folder requires a restart before its roles resolve. Either ''attribute.groups'' or ''dynamicRole.prefix'' must be configured — with neither, every SAML user would resolve to zero roles, so the authenticator fails validation at startup.

Valid Obsidian roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles following the ''<folder>-(Write|Author|Operator)'' convention (e.g. ''Maintenance-Author'').

=== Request signing and assertion trust ===

''signRequests'' (default enabled) signs the outbound ''AuthnRequest'' and SP ''LogoutRequest'', and requires ''keystore.path'', ''keystore.password'' and ''keystore.alias''. ''wantAssertionsSigned'' (default enabled) requires the IdP to sign assertions. Disabling both is accepted but logs a warning at startup, because assertions are then neither signed nor verified — do not do this in production.

Encrypted assertions are '''not''' supported. The IdP must send signed, unencrypted assertions. Publish signing-capable key material in your SP metadata so that IdPs such as AD FS do not choose to encrypt.

=== Logout modes ===

Two logout modes are supported:

* '''local''' (default) — Obsidian invalidates its own session. The IdP session remains active.
* '''slo''' — SP-initiated single logout. Obsidian sends a signed ''LogoutRequest'' to the IdP's HTTP-Redirect ''SingleLogoutService''. If the IdP metadata advertises no HTTP-Redirect SLO endpoint, Obsidian logs a warning and falls back to local logout. ''postLogoutRedirectUri'' sets the landing page after the IdP's ''LogoutResponse''; when blank the browser returns to ''/''.

An IdP-initiated ''LogoutRequest'' posted to ''/saml/slo'' is honoured in either mode.

=== No REST API access ===

Obsidian's REST API is '''unavailable''' while ''SAMLAuthenticator'' is active. There is no SAML equivalent of the OAuth JWT Bearer path, and REST credential authentication is refused outright. Deployments that need REST access must run a separate Obsidian instance with an authenticator that supports it.

=== v1 limitations ===

* The REST API is not available while ''SAMLAuthenticator'' is active.
* SP-initiated login only. The callback requires an existing browser session, and a response carrying ''InResponseTo'' must match a pending ''AuthnRequest'' from that session, which is single-use and expires after five minutes.
* Encrypted assertions are not supported.
* Replay protection relies on that single-use ''AuthnRequest'' match plus the assertion time window; there is no persistent assertion ID store, so keep assertion lifetimes short at the IdP.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static group→role pairs; the runtime supports unlimited.

== Developing an Authenticator ==
Obsidian uses any valid implementation of the <code>com.carfey.suite.security.Authenticator</code> or <code>com.carfey.suite.security.remember.Authenticator</code> interface.

=== Implementation of a Custom Authenticator ===
'''<code>com.carfey.suite.security.User authenticate(String username, String pass) throws com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>'''

As of Obsidian 6.1.1, you may optionally implement REST authentication distinctly. Defaults to standard authentication when not implemented.
'''<code>com.carfey.suite.security.User authenticateREST(String username, String pass) throws com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>'''

This method authenticates and returns a user with roles defined. Given a user name and a password either return a valid <code>com.carfey.suite.security.User</code> object or throw a <code>com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>.

If authentication is successful, the <code>com.carfey.suite.security.User</code> returned must have all its role memberships defined. This is done using the <code>com.carfey.suite.security.Role</code> class. The assignment of <code>Role</code>s to a <code>User</code> can be done using any of the public constructors/setters or logical combination thereof defined below.

'''<code>public boolean supportsRememberMe()</code>'''

From <code>com.carfey.suite.security.remember.Authenticator</code>, available from Obsidian 3.5.0 and '''removed in Obsidian 7.0.0'''.

This method indicated whether the Authenticator supported Obsidian's remember me feature in the Web Admin login. The Remember Me feature and the <code>com.carfey.suite.security.remember.Authenticator</code> interface were removed in Obsidian 7.0.0, so this method is no longer part of the authenticator contract.

=== Users ===

<pre>
public User(String userId)

public User(String userId, Set<Role> roles, String firstName, String lastName, String email, boolean active*)

public User(String userId, List<Role> roles, String firstName, String lastName, String email, boolean active*)

public void setRoles(Set<Role> roles)

public void setRoles(List<Role> roles)
</pre>
''* Note: If you wish to implement active user enabling/disabling, you must do so in your <code>Authenticator</code> throwing <code>com.carfey.suite.security.Authenticator.AuthenticationFailedException</code> when inactive users attempt to login.

=== Roles ===
There are convenience constants that you should use in defining your role memberships. They can be found at <code>com.carfey.ops.Constant</code>. The constants are <code>ADMIN_ROLE</code>, <code>WRITE_ROLE</code>, <code>LIMITED_READ_ROLE</code> and <code>API_ROLE</code>. As of ''5.0.0'', you can also use <code>OPERATOR_ROLE</code> and <code>AUTHOR_ROLE</code>. ''Default'' rights are assumed for any authenticated user. Therefore, if someone authenticates that should not have access, throw a <code>com.carfey.suite.security.Authenticator.AuthenticationFailedException</code>.

When assigning the user's <code>com.carfey.suite.security.Role</code>s, use the constructor <code>public Role(String roleId, String roleName)</code> using the appropriate constant for both the <code>roleId</code> and <code>roleName</code>. Role meanings are defined in [[Admin_User_Management#User_Rights | User Rights]].

=== Putting it All Together ===

Finance attempts to log in to Obsidian, gives valid credentials but should not be accessing Obsidian.

<pre>
import static com.carfey.ops.Constant.*;

import com.carfey.suite.security.Authenticator.AuthenticationFailedException;
import com.carfey.suite.security.Role;
import com.carfey.suite.security.User;

public User authenticate(String username, String pass) throws AuthenticationFailedException {
//usernameis "financeGuy"
//pass is "mystrongpass"
//credentials are valid, but user does not have any rights to Obsidian

throw new AuthenticationFailedException(String.format("User [%s] is not authorized to use Obsidian Scheduler.", username));
}
</pre>

Fred logs in using his username ''fredScheduler'' and his password ''badpass''. You determine that his password is invalid.

<pre>
import static com.carfey.ops.Constant.*;

import com.carfey.suite.security.Authenticator.AuthenticationFailedException;
import com.carfey.suite.security.Role;
import com.carfey.suite.security.User;

public User authenticate(String username, String pass) throws AuthenticationFailedException {
//usernameis "fredScheduler"
//pass is "badpass"
//credentials are invalid

throw new AuthenticationFailedException(String.format("User [%s] could not be authenticated.", username));
}
</pre>

Fred logs in using his username ''fredScheduler'' and his password ''mystrongpassword''. You determine that his password is valid and matches with the user and he has ''WRITE_ROLE'' rights.

<pre>

public User authenticate(String username, String pass) throws AuthenticationFailedException {
//usernameis "fredScheduler"
//pass is "mystrongpassword"
//credentials are valid, he has WRITE_ROLE

User user = new User(username);
user.setRoles(Arrays.asList(new Role(WRITE_ROLE, WRITE_ROLE)));
return user;
}
</pre>

Tina logs in using her username ''tinaOperator'' and her password ''mystrongpassword''. You determine that her password is valid and matches with the user and she has ''Default'' rights.

<pre>

public User authenticate(String username, String pass) throws AuthenticationFailedException {
//usernameis "tinaOperator"
//pass is "mystrongpassword"
//credentials are valid, Tina has default access

return new User(username);
}
</pre>

The intern logs in using his username ''newGuy'' and his password ''mystrongpassword''. You determine that his password is valid and matches with the user and he has ''LIMITED_READ_ROLE'' rights.

<pre>

public User authenticate(String username, String pass) throws AuthenticationFailedException {
//usernameis "newGuy"
//pass is "mystrongpassword"
//credentials are valid, the intern has LIMITED_READ_ROLE access

User user = new User(username);
user.setRoles(Arrays.asList(new Role(LIMITED_READ_ROLE, LIMITED_READ_ROLE)));
return user;
}
</pre>

The new hire logs in using her username ''newHire'' and her password is ''i am a new hire''. You determine that her password is valid and matches with the user and she has ''OPERATOR_ROLE'' rights only for the job folder roots ''DevOps'' and ''FinOps''.

private static final String DEV_OPS_OPERATOR = "DevOps-" + OPERATOR_ROLE;
private static final String FIN_OPS_OPERATOR = "FinOps-" + OPERATOR_ROLE;
public User authenticate(String username, String pass) throws AuthenticationFailedException {
//usernameis "newHire"
//pass is "i am a new hire"
//credentials are valid, the new hire has OPERATOR_ROLE access for job folder roots ''DevOps'' and ''FinOps''

User user = new User(username);
user.setRoles(Arrays.asList(new Role(DEV_OPS_OPERATOR, DEV_OPS_OPERATOR), new Role(FIN_OPS_OPERATOR, FIN_OPS_OPERATOR)));
return user;
}

== Customizing our LDAP Authenticator ==

<code>com.carfey.suite.security.LdapAuthenticator</code> is Obsidian's LDAP Authentication class that, when combined with its configurability that is documented [[Advanced_Configuration#Configuration_Details|here]], meets most needs. But with the large variety of LDAP servers and potential implementations of ''dn'' strings, role and group definition and membership and even authentication methods supported, you may need to tweak its use somewhat. Rather than require you to write your own LDAP Authenticator, we have made efforts to make ours flexible enough to be specialized.

=== Specialization points ===
====<code>protected void buildUpContextEnvironment(String pass, String dn, Hashtable<String, String> environment)</code>====

Stores needed environment attributes for authentication using <code>javax.naming.directory.InitialDirContext</code>.

Currently stores:
<pre>
Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory"
Context.PROVIDER_URL, {{ldap_url}}
Context.SECURITY_AUTHENTICATION, "simple" //or overridden securityAuthentication by configuration com.carfey.suite.security.LdapAuthenticator.securityAuthentication
Context.SECURITY_PRINCIPAL, {{user_dn}}
Context.SECURITY_CREDENTIALS, {{user_pass}}
</pre>

====<code>protected boolean isMemberOfGroup(DirContext authContext, String groupName, String dn) throws NamingException</code>====

Checks the authenticated <code>DirContext</code> for group membership. Used to determine ''Default'' rights to Obsidian, in addition to its defined rights [[Admin_User_Management#User_Rights|roles]]. Currently queries <code>"uniquemember"</code>,<code>"uniqueMember"</code>,<code>"member"</code>,<code>"roleOccupant"</code>, <code>"memberOf"</code> and <code>"MemberOf"</code> attributes for any match on the ''dn''.

== Deploying your Authenticator ==
Once your authenticator class is written, you need to deploy the compiled class and any dependent libraries to your admin web application instances as JAR files. These should be placed under the <code>/WEB-INF/lib</code> directory of either the Obsidian web application directory or WAR file.

Advanced Configuration

2026-07-31T14:49:46Z

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

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# You can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# You can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# You can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# This is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# This determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# If anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# We support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# We support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# You can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# If you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# You can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

You may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. Our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Markdown rendering for job and parameter descriptions ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Groovy libraries''': Obsidian no longer ships '''apache-groovy-all-4.0.24.jar'''. Groovy scripting now uses 13 modular JARs (see ''Scripts'' above). When Groovy is disabled at install time, all 13 modules are excluded.
* '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Markdown rendering for job and parameter descriptions now uses 12 modular Flexmark JARs (see ''Web Admin'' above).
* '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Admin Web Application Guide

2026-07-31T14:49:45Z

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

'''Important: This guide is for Obsidian 4.0 and newer versions.

Obsidian's administration web application lets you manage scheduler settings, monitor job execution, create and update jobs, and manage various notification settings.

It uses a sidebar on the left hand side of each page for primary navigation. This sidebar has parent menu items which are expanded by clicking on them. The sidebar can be hidden via the arrow at the bottom of the menu, or the hamburger icon on the right side of the screen.

It supports modern browsers including Chrome, Firefox, Edge, and more. It is a responsive mobile application, so you can use it on your phone or tablet.

'''Note:''' Though Obsidian is fully functional in other browsers, we recommend you use browsers such as Chrome or Firefox since they provide a better user experience and vastly superior performance.

[[Image:ObsidianNav_4.0.png|400px]]

To set up the web application, see '''[[Getting Started]]'''.

Screens available in Obsidian's web application are discussed on the following pages:

* '''[[Admin Login|Login]]'''
* '''[[Admin Job Activity|Job Activity]]'''
* '''[[Admin Jobs|Jobs]]'''
* '''[[Admin Job Stats|Job Stats]]'''
* '''[[Admin Global Parameters|Job Global Parameters]]'''
* '''[[Admin Schedule Aliases|Schedule Aliases]]'''
* '''[[Admin Job Run Time Preview|Job Run Time Preview]]'''
* '''[[Admin Job Conflicts|Job Conflicts]]'''
* '''[[Admin Job Chains|Job Chains]]'''
* '''[[Admin Custom Calendars|Calendars]]'''
* '''[[Admin Logs|Logs]]'''
* '''[[Admin Notifications|Sent Notifications]]'''
* '''[[Admin Subscribers|Subscribers ]]'''
* '''[[Admin Templates|Email Templates]]'''
* '''[[Admin Scheduler Settings|Scheduler Settings]]'''
* '''[[Admin Host Status|Host Status]]'''
* '''[[Admin User Management|User Management (including MFA)]]'''

Admin User Management

2026-07-31T14:49:45Z

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

User management can be accessed by ''Admin'' users from the primary navigation sidebar. The current user may view their rights and/or change their password by using the user name drop-down in the top right corner of the screen.

All users may see their current rights. In addition, if native authentication is used, all users may change their password. ''Admin'' users may also view and manage users when native authentication is used.

== Viewing Rights & Changing Your Password ==

Selecting ''My User'' from the user name dropdown in the top right of the screen will bring you to the page which lists your user rights. If native authentication is used, you may also change your password from this page.

[[Image:UserChangePassword_4.0.png]]

[[Image:UserChangePasswordFull_4.0.png]]

== Listing Users ==

''Admin'' users may view current users, add users, and update settings and passwords of existing users.

[[Image:UserListing_4.0.png]]

=== Exporting Results ===
The current contents of the table can be exported to Excel, CSV or XML by clicking on export icon displayed at the far right of the table header. The download will automatically begin and will include all pages of the current table of results.

== Changing or Adding Users ==

Clicking the (+) button in the table header will bring you to the New User screen. Clicking a user in the table will allow you to edit or view a user. For security reasons, you must always enter your current user password to make user changes.

'''Note:''' The question mark icon that appears next to the form title indicates inline help. Click on the icon to see help related to the current page.

[[Image:AddUserSave_4.0.png]]

When saving changes, you may receive error notifications. In this case, no changes were saved and you may correct your user setup and resubmit.

'''Note:''' When editing existing users, you may change their password by entering the new password and confirmation. If you leave both blank, the password will remain unchanged.

[[Image:AddUserEnterPassword_4.0.png]]

== Deleting Users ==

You can also delete users from the edit page. For security reasons, you must always enter your current user password before deleting a user. You will be prompted to confirm the delete action.

'''Note:''' Deleting users can make tracking down who made changes more difficult. Consider making a user inactive instead.

[[Image:DeleteUser_4.0.png]]

== User Rights ==

Rights are broken out into these categories: ''Default'' (read), ''Write'', ''Admin'', ''API Access'', ''Author'' and ''Operator''. In addition, ''Default'' read access can be limited using the ''Limited Read Access'' setting.

* ''Default'' rights allow you read access to most parts of the application, with the exception of user lists and the [[Admin Scheduler Settings|Scheduler Settings]] screen.

* ''Write'' rights allow you perform most operations, with the exception of viewing and changing users, and the [[Admin Scheduler Settings|Scheduler Settings]] screen.

* ''Admin'' rights allow you access to view and change [[Admin Scheduler Settings|Scheduler Settings]], pause/resume [[Admin Host Status|scheduler hosts]] and manage users.

* ''API Access'' grants the user the ability to use the full [[REST API]]. In addition, this role grants the ''Default'' read access to the admin application.

* ''Limited Read Access'' prevents the user from seeing potentially sensitive job configuration parameters. If you wish to hide these values from a user, grant them this right, otherwise leave it unselected. Note that if a user has Write or API Access, this setting has no effect.

* ''Author'' rights allow you to create and modify jobs, job chains and conflicts. '''As of Obsidian 5.0.0'''

* ''Operator'' rights allow a user to resubmit failed jobs, submit ad-hoc jobs, interrupt running jobs and pause/resume scheduling hosts. '''As of Obsidian 5.0.0'''

=== Job Folder Rights ===

Understand the [[Admin_Jobs#Nickname.2C_Class_and_Folder|job folder]] feature.

'''As of Obsidian 5.0''', more granular rights can be assigned to users that are based on the root job folder specified on a job. Any job that doesn't have a job folder specified will require the standard rights listed in [[Admin_User_Management#User_Rights|User Rights]] above. For example, if a job has the folder ''Maintenance'' or ''Maintenance/BackOffice'', a user with the role ''Maintenance-Author'' has the Author permissions as noted below.

For rights that allow creation/modification of jobs, the job folder can only be set/changed by the user if it continues to respect the user's job folder authoring permissions. This also implies the job folder cannot be cleared by this user. For example, if a user has the roles ''Maintenance-Write'' and ''DevOps-Write'', they can create a job that has a root folder ''Maintenance'' or ''DevOps'', optionally with any subpath. The user cannot create a job with no job folder, nor can they change a job's folder to something other than a root of ''Maintenance'' or ''DevOps''.

The 3 permissions supported by folder convention roles are similar, but not identical to the broader roles listed in [[Admin_User_Management#User_Rights|User Rights]] above.

* ''Write'' access by root job folder allows a user to create/modify, submit for ad-hoc and resubmit failed jobs that have a matching root job folder.

* ''Author'' access by root job folder allows a user to create and modify jobs that have a matching root job folder.

* ''Operator'' access by root job folder allows a user to resubmit, interrupt and submit ad-hocs that have a matching root job folder.

== Multi-Factor Authentication (MFA) ==

'''As of Obsidian 5.0'''

'''Note:''' MFA does not apply to the [[REST API]], and any user with API privileges will be able to invoke endpoints without an MFA code.

Obsidian supports multi-factor authentication via [https://en.wikipedia.org/wiki/Google_Authenticator Google Authenticator], which generates rotating one-time codes on your mobile device. Other MFA approaches such as email and SMS are not supported, as they have inherent security issues.

To enable MFA, simply configure the [[Admin_Scheduler_Settings|Scheduler Settings]] ''mfaSetupDays'' and ''mfaEnabled''. Once MFA is enabled, the ''mfaSetupDays'' setting controls how long users have to log in and set up MFA for their account. If they do not log in and complete setup within this time, they will be locked out and an [[#MFA Resets|MFA Reset]] will have to be performed.

[[File:MFA scheduler settings.png|1000px]]

=== Completing MFA Setup ===

Once MFA is enabled, when you log in you will see the typical login screen. After entering your user name and password, you will be prompted to perform set up with Google Authenticator. Simply follow the on-screen instructions to scan the presented QR code. Once setup is complete, you will be logged in.

[[File:MFA setup prompt.png]]

=== Logging in After Setup ===

After initial setup is complete, when you log in you will still see the typical login screen. After entering your user name and password, you will be prompted to enter the appropriate code from Google Authenticator to complete login.

=== MFA Resets ===

If a user does not complete MFA setup within the allowed time, or a new user is added when not using Obsidian native authentication, you may need to perform an MFA reset so that they may complete MFA setup and log in. It can also be used to force a user to re-perform MFA setup and invalidate any existing Google Authenticator entries for the account.

When MFA is enabled, the typical user listing table will include a button to perform MFA Resets.

[[File:MFA user listing reset button.png]]

The screen presented after clicking this button will allow you to reset one or more users' MFA state. Either select a known user from the list, or type a user name and click the plus button. Your current user password must also be entered for security reasons.

[[File:MFA reset page.png]]

When you are happy with your changes, click the Reset button.

[[File:MFA reset success.png]]

Users will then be allowed to perform MFA setup for the number of days configured via ''mfaSetupDays''.

Admin Jobs

2026-07-31T14:49:44Z

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

The job screens give you access to the core of Obsidian's functionality - scheduling and configuring jobs. This screen can be accessed from the primary navigation sidebar, underneath the Configuration parent menu item.. This page discusses listing and modifying jobs. Other job-related features are discussed on other pages in the [[Admin Web Application Guide|guide]].

= Job Listing =

The default screen shows you a table of existing configured jobs.

[[Image:JobListing_4.1.png]]
== Fields ==

Fields shown in the job table are:

* Job Nickname (links to job configuration screen)
* Job Class
* Folder
* Status (current)
* Schedule (current)
* Submit Run Link (users with Write role only)
* Clone Job Link (users with Write role only)

''Submit Run'' either provides the option to submit a job for immediate or scheduled one-time execution. A job's current state must be either Enabled, Ad Hoc Active or Unscheduled Active to support immediate one-time execution. Otherwise, only future scheduled one-time execution is supported.

''Clone Job'' opens up the a new job edit screen pre-populated with the selected job's configuration, including parameters and schedules.

== Filtering ==

Job records can be optionally filtered by host, status and folder. In the case of each, selecting no options is equivalent to choosing all options . Selected options may be cleared by clicking the (X) next to the dropdown arrow.

When filtering by folder, subfolders are matched when searching by a parent folder. Note that intermediate folders with no contents will be suppressed if they do not offer any search value.

== Exporting Results ==
The current contents of the table can be exported to Excel, CSV or XML by clicking on export icon displayed at the far right of the table header. The download will automatically begin and will include all pages of the current table of results.

== Ad Hoc & One-Time Run Submission ==

You may submit a job for a single execution by clicking the ''Submit Run'' link in the job listing, which will bring you to a screen to configure your submission.

One-time runs can be submitted either for immediate or scheduled one-time execution. A job's current state must be either Enabled, Ad Hoc Active or Unscheduled Active to support ad hoc or one-time runs.

The Scheduled Time can be omitted when immediate execution is desired, assuming it is supported as just described.

[[Image:AdHocJobSubmission_4.0.png]]

=== Run Parameters ===
Obsidian allows you to specify [[Implementing_Jobs#Ad_Hoc_.26_One-Time_Run_Parameters|run parameters]] which are supplied to the job for a single execution. To add a parameter, click the ''Add Parameter'' button. You may add values by clicking the (+) and trash buttons to the right of the field. Any entered values will be validated against the selected type, plus against any parameter of the same name defined at the job level, to ensure data types and other restrictions are enforced. If a parameter name for a run parameter has the same name as a configured job parameter, the job parameter values are dropped, and the run parameter values are used instead.

To remove a parameter and its values, click the ''Remove'' button.

If you reference a [[Admin_Global_Parameters|global parameter]] by entering a value surrounded by double curly braces (e.g. <code>{{param}}</code>), Obsidian will resolve this to the values that are configured for the corresponding global parameter (e.g. <code>param</code>). When the job is executed, Obsidian will use the global parameter's values in place of the global parameter reference. You may use multiple global parameters for a given run parameter by specifying each in its own value field, and they can be combined with regular parameter values, also in their own fields. All imported global parameter values will be validated against applicable job parameter definitions and data types.

= Adding & Editing Jobs =

To add a new job, click the (+) button in the job listing table header.

To edit or view a job's configuration, click the nickname in the results table.

The job edit screen contains multiple configuration items with which you should be familiar. They are outlined in the sections below.

'''Note:''' The question mark icon next to form titles indicates inline help. Click on the icon to view help related to the current item. This is your best source of help when making changes to job details.

[[Image:AddJob_4.1.png|300px]]

== Job Settings ==

=== Nickname, Class and Folder ===
All jobs must have a unique job nickname which identifies the job in logs and event notifications.

The ''Job Class'' selector allows you to choose existing jobs that Obsidian knows about, and you may also manually type in a custom job (hit enter to confirm and validate). When selecting a job, note that it must be available to all the scheduler nodes (i.e. on the classpath) so that it can retrieve parameter information and validate your configuration. It is not required, nor is it suggested, to keep these classes in the web admin application.

'''Note:''' When selecting or choosing a new job, the defined and custom parameters sections will refresh based on that specific job's parameter definitions.

The ''Folder'' selector allows you to select an in use folder, or type in a new folder. Clicking the (x) button will clear the selection so you can type in a custom folder. Jobs can be assigned to folders to help grouping and searching for them. You can use nested paths (e.g. A/B) using forward-slashes. Note that back-slashes will be automatically converted to forward slashes, and multiple slashes in succession are collapsed into a single slash. Leading and trailing slashes are stripped for consistency.

=== Advanced Options ===

This section allows you to specify options related to how jobs are picked up and recovered in exceptional circumstances. Click on ''Advanced Options'' or the chevron next to it to expand or collapse this section.

''Recovery Type'' allows you to specify how the job will be handled when execution does not happen normally within the ''Pickup Buffer'' because of conflicts, server downtime, etc.

''Startup/Shutdown Mode'' allows you to specify if the job should fire automatically, independently of any defined schedule, in various startup and shutdown scenarios.

''Pickup Buffer'' indicates for how many minutes the job is considered within normal execution time from the exact scheduled time. This allows for leniency when dealing with conflicting jobs or with short-term downtime. If a minor delay isn't significant to your job, using a higher buffer can help prevent jobs from being marked missed or conflict missed unnecessarily.

''Auto Retries - #'' allows you to indicate the number of times you wish Obsidian to automatically resubmit (retry) the job for execution when triggered by a non-interrupted execution failure.

''Auto Retries - Interval'' allows you to indicate the minimum interval in minutes from the point in time the job failed and the job will be retried.

''Auto Retries - Exponential'' allows you to indicate if you desire the auto retries interval to exponentially increase as retries are attempted. For example, if you set the interval minutes to 5 and check ''Exponential'', the first retry will be 5 minutes after failure, the second retry after a subsequent failure will be 10 minutes later, then 20 minutes, and so on.

''Expected Length'' allows you to trigger event notifications in the event that the job execution is shorter or longer than the durations specified. Both fields are optional, and you are permitted to specify only one of the two. Specify a duration followed by a unit indicator (s-seconds, m-minutes, h-hours), e.g. 45s, 10m or 1h. To receive notifications based on the job running outside these parameters, configure [[Admin Subscribers|subscribers]] at the Warning level or above.

''Auto Interrupt'' allows you to specify if you wish an [[Implementing_Jobs#Interruptable_Jobs|Interruptable Job]] to be interrupted when its maximum expected run length is exceeded. Only available as an option for those jobs that adhere to the [[Implementing_Jobs#Interruptable_Jobs|Interruptable Job]] requirements and have a maximum expected length specified.

''Fixed Hosts'' allows you to indicate that only certain hosts should run this job. You can select one or more hosts which Obsidian knows about. If a host is not listed and will be started later, simply type in the name and click the (+) button to add it to the list. A configuration item allows you to specify whether you wish host restrictions to apply on AdHoc jobs or not. It defaults to TRUE on new installations. This can be found under '''[[Admin_Scheduler_Settings|Scheduler Settings]]/Job/adHocJobsRespectFixedHostsRestrictions'''. As of version 4.4, you may use a Java regular expression to use pattern matching on the host name. For example, a wildcard match for hosts that start with "abc" can be done with a pattern like "abc.*". To implement a blacklist of hosts that the job should not run on, a single pattern with negation can be used: "(?!(blacklist-one|blacklist-two)).*".

''Host Preference'' indicates that Fixed Hosts are only preferred hosts, and that other available hosts can run the job when none of the preferred hosts are running. When selected, you can also order the hosts using drag & drop. Obsidian will always choose the highest priority host to run the job if one is available.

''Chain All'' allows you allows you specify the behaviour when this job is to be chained but is executing another instance at that moment. By default, only one newly chained instance will be queued. Choose this option to chain all such occurrences. Each chained target instance is queued for the same minute. Ensure your Pickup Buffer is set large enough for these to be picked up and run in sequence.

== Schedule ==

When adding a new job, the schedule section will allow you to specify the initial schedule. You will have the ability to overwrite, adjust or add new schedules after initial creation. Schedule is required only for enabled jobs and is ignored for other states. See [[#Date Fields|Date Fields]] for details on how the date and time fields can be used. [[Cron]] patterns are used to specify the schedule or you may use custom [[Cron#Recurrence | Recurrence]] expressions.

Multiple cron patterns may be specified for a single schedule by delimiting them with a semi-colon (e.g. <code>35 8 * * * *;20 12 * * *;40 16 * * *</code>). This means that the job will fire if it matches any of the supplied patterns.

If you specify start and end dates, any dates outside this range will be initially set to the Disabled States.

=== State ===

''Enabled'' is the standard state that allows scheduling, chaining, and one-time run submissions. This is the only state that takes a schedule [[Cron]] pattern.

''Disabled'' allows you to disable the job completely during the specified window.

''Chain Active'' allows the job to be executed as a chain target only.

''Ad Hoc Active'' allows the job to be submitted and executed for one-time runs only. Note that a one-time run must be requested after saving your job configuration for the job to be executed.

''Unscheduled Active'' allows the job to be executed as a chain target and also allows the job to be submitted and executed for one-time runs upon request. Note that a one-time run must be requested after saving your job configuration for the job to be executed.

'''Note:''' When editing a job, the schedule section shows a read-only view of the active schedule, or if one is not active yet, the first schedule that will become active.

=== Date Fields ===

Dates and times are used to specify schedule start and end times.

From and To fields will show user-friendly date and time selectors which enforce a valid date range. If you cannot select a date in the past or future, it is because the date widget is enforcing a valid time, and you may need to edit your from or to times appropriately.

'''Note:''' If you wish minute-level specificity, simply manually type your time into the time field in the 24-hour format HH:MM. You do not have to use the time selector.

There is some helpful behaviour when you wish a schedule to be indefinite and immediately active. You do not have to specify times in this common case:

* Blank from dates will be treated as today's date.
* Blank from times will be treated as the next valid minute, unless a non-current date is specified, in which case it is treated as midnight.
* Blank to dates will be considered as indefinite (no end).
* Blank to times will be considered as end of day (11:59 PM), or indefinite when the to date is blank.

=== Edit, View & Change Schedules ===

After you have saved the initial job configuration, you can then make schedule changes and additions.

When saving a new job or loading an existing job's configuration, you will see the current schedule in a read-only view in the ''Schedule'' section.

To update the current schedule or create a future schedule, click the ''Edit'' button, then make your changes. New schedules may overlap, contain or be within existing schedules with no issue. Obsidian will automatically split and merge schedules to create a complete schedule based on your changes.

[[Image:JobSchedule_4.0.png]]

If you wish to abandon your schedule changes, click the ''Revert'' button.

[[Image:JobScheduleRevert_4.0.png]]

To simply replace any current schedules with a new permanent schedule, leave the time fields blank, and it will become active indefinitely at the beginning of the next minute.

Clicking the ''View All'' button will show all schedules that have been configured that are active now or in the future. The ''Include Expired'' checkbox can be used to include expired schedules in the listing. This will be the existing schedules if no new schedule is entered, or a preview of the new altered schedules based on your input if specified. This allows you to view the effect of your changes before confirming them.

'''Note:''' In order to save your schedule changes, you'll need to save the job itself. If you click the ''Revert'' button after making schedule changes, they will be discarded and will not be included if you then click Save.

Below you can see the ''View All'' button being used to view the current schedules without making any changes.

[[Image:NewJobSchedule_4.0.png]]

=== Custom Calendar Assignment ===

An Enabled Schedule may also be assigned a [[Admin_Custom_Calendars|Custom Calendar]]. Use this to prevent scheduling/execution on the dates specified by the Custom Calendar.

[[Image:CustomCalendarAssignment_4.0.png]]

== Parameters ==

=== Defined Parameters ===

If a job has defined parameters as discussed in [[Implementing Jobs]], this section will show the configurable parameters. The label on the left will indicate the name and type of the parameter.

If the parameter definition allows multiple values, buttons to the right of the text field will allow you to add or remove values. Note that remove will not appear for the first item, and if you wish to omit the parameter value, simply leave the first field blank.

If the parameter is defined to use a [[Implementing_Jobs#List_Parameterization|list of values]], a select list will be presented instead of a text box.

Asterisks indicate required values.

=== Custom Parameters ===

In addition to defined parameters, you always have the option of specifying custom parameters, which the job may use in a dynamic fashion. In the ''Parameters'' section, click on ''Custom'' or the chevron next to it to expand or collapse this section.

To add a custom parameter, click the ''Add Custom Parameter'' button. Custom parameters always allow multiple values since they have no fixed definition, and you may add values by clicking the (+) and trash buttons to the right of the field. Any entered values will be validated against the selected type, and the selected type will determine how they are stored and provided to the job.

To remove a custom parameter and its values, click the ''Remove'' button.

Custom parameters support global parameter references. As of Obsidian 7.0.0, autocomplete and hover tooltips for global parameter references are also available on custom parameter fields (see [[#Global_Parameters|Global Parameters]] above).

=== Global Parameters ===

Both defined and custom parameters support the usage of [[Admin_Global_Parameters|global parameters]]. These let you configure job parameters globally, and then simply import them into jobs as needed.

To use a global parameter in a job, simply enter its name surrounded by double curly braces (e.g. <code>{{param}}</code>) in the value field, and Obsidian will locate the matching global parameter (e.g. <code>param</code>). When the job is executed, Obsidian discards the global parameter reference and replaces it with the current global parameter values. You may use multiple global parameters for a given parameter by specifying each in its own value field, and they can be combined with regular parameter values, also in their own fields. All imported global parameter values will be validated against applicable job parameter definitions and data types. 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.

When you save your job changes, Obsidian will validate that any reference global parameter values match your defined data types and other parameter restrictions.

See [[Implementing_Jobs#Global_Parameters|Parameterization - Global Parameters]] for more details on type handling and validation of global parameters.

As of Obsidian 7.0.0, when editing a job, typing ''{{'' in a parameter value field opens an autocomplete suggestion list of available global parameter names. Select a name with Enter or a click, or dismiss with Esc. The suggestions are subject to your user's permissions and configuration settings — see [[Advanced_Configuration|Advanced Configuration]] for details.

On the job '''view''' screen (read-only), hovering over a parameter value that contains ''{{Name}}'' shows a tooltip with the resolved global parameter value, when your user has the necessary permissions.

== Saving ==

To save your configuration changes, click the Save button at the bottom of the form or in the left navigation area. If there are problems with your changes, you will be notified at the top of the screen. You can then correct your entered information and re-save. Upon success, you will see a success confirmation.

== Deleting ==

You can delete a job and all its history and configuration from Obsidian. We recommend you use this feature sparingly. It is most useful on long-obsolete jobs. When you attempt to delete a job, Obsidian will ask for your confirmation along with prompting you with a choice.

Deleting a job in Obsidian assumes you are fine with losing all runtime results, defined parameters and any schedules and states. You will also lose any chain references from this job, i.e if a job was chained from the job you're deleting, it will show as chained, but the source job information will be lost. Since jobs can have an impact on other jobs, namely chaining and conflict configuration, the default delete will fail to complete if there are any active chains referencing the job in question or if the job is included in any conflict groups. Optionally, you can also select the option ''Delete all active job configuration?'' in the Delete Job window and this will delete any of these as well.

[[Image:DeleteJobWindow_4.0.png]]

Advanced Configuration

2026-07-31T02:18:21Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. As of Obsidian 2.5.0, our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Markdown rendering for job and parameter descriptions ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Groovy libraries''': Obsidian no longer ships '''apache-groovy-all-4.0.24.jar'''. Groovy scripting now uses 13 modular JARs (see ''Scripts'' above). When Groovy is disabled at install time, all 13 modules are excluded.
* '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Markdown rendering for job and parameter descriptions now uses 12 modular Flexmark JARs (see ''Web Admin'' above).
* '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Advanced Configuration

2026-07-31T02:16:12Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. As of Obsidian 2.5.0, our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Markdown rendering for job and parameter descriptions ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Groovy libraries''': Obsidian no longer ships '''apache-groovy-all-4.0.24.jar'''. Groovy scripting now uses 13 modular JARs (see ''Scripts'' above). When Groovy is disabled at install time, all 13 modules are excluded.
* '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Markdown rendering for job and parameter descriptions now uses 12 modular Flexmark JARs (see ''Web Admin'' above). * '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Advanced Configuration

2026-07-31T02:10:45Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. As of Obsidian 2.5.0, our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Markdown rendering for job and parameter descriptions ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Markdown rendering for job and parameter descriptions now uses 12 modular Flexmark JARs (see ''Web Admin'' above).
* * '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Web Admin UI rendering now uses 12 modular Flexmark JARs (see ''Scripts'' above).
* '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Advanced Configuration

2026-07-31T02:10:13Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. As of Obsidian 2.5.0, our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Markdown rendering for job and parameter descriptions ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Groovy libraries''': Obsidian no longer ships '''apache-groovy-all-4.0.24.jar'''. Groovy scripting now uses 13 modular JARs (see ''Scripts'' above). When Groovy is disabled at install time, all 13 modules are excluded.
* * '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Web Admin UI rendering now uses 12 modular Flexmark JARs (see ''Scripts'' above).
* '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Advanced Configuration

2026-07-31T02:09:16Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. As of Obsidian 2.5.0, our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Wiki rendering ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Groovy libraries''': Obsidian no longer ships '''apache-groovy-all-4.0.24.jar'''. Groovy scripting now uses 13 modular JARs (see ''Scripts'' above). When Groovy is disabled at install time, all 13 modules are excluded.
* * '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Web Admin UI rendering now uses 12 modular Flexmark JARs (see ''Scripts'' above).
* '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].

Advanced Configuration

2026-07-31T02:04:01Z

Craig: /* Dependent Libraries */

Obsidian requires some initial configuration parameters for database connection information and desired authentication mechanisms. The installer takes care of configuring these as provided. For your reference should you wish to manually create/edit these, note the details below.

== Configuration Details ==

The following sections show the available properties and sample values that can be used in the <code>com.carfey.properties</code> properties file. While properties format is shown, all the same configuration items apply to yaml support. See [[#Properties.2FYaml_File|Properties/Yaml File]] for more details on this file.

=== Authentication Properties ===
<pre>
# Comment out the native authenticator setup
#com.carfey.suite.security.Authenticator=com.carfey.suite.security.DBAuthenticator
</pre>

==== LDAP Authentication Properties ====
<pre>
#Set your LDAP info here
com.carfey.suite.security.Authenticator=com.carfey.suite.security.LdapAuthenticator
# As of Obsidian 2.1.1, you can specify the attribute type used in building up the distinguished name (dn). If unspecified, defaults to cn
com.carfey.suite.security.LdapAuthenticator.dn.attribute=uid
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of dn.bases to search.
com.carfey.suite.security.LdapAuthenticator.dn.base=ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.url=ldap://localhost:10389
# As of Obsidian 2.1.1, you can specify the SECURITY_AUTHENTICATION. Defaults to simple.
com.carfey.suite.security.LdapAuthenticator.securityAuthentication=simple
# Any necessary additional information such as Provider, Principal and Host will need to be handled in your custom class extending LdapAuthenticator.

# As of Obsidian 3.5.1, you can login via an LDAP attribute that is not part of the dn. A matching entry is found in the LDAP Directory (using anonymous or a fixed lookup account)
# after which the dn attribute above is retrieved to perform the user's authentication. The following 5 attributes are only used for this type of lookup and authentication.
com.carfey.suite.security.LdapAuthenticator.lookupDnAttribute=false
# As of Obsidian 3.5.1, this is the attribute name that is being searched for in the LDAP directory to build the dn for eventual authentication.
com.carfey.suite.security.LdapAuthenticator.loginAttribute=sAMAccountName
# As of Obsidian 3.5.1, this determines if these lookups will be done anonymously (without a session authenticated by user/password)
com.carfey.suite.security.LdapAuthenticator.anonymousEnabled=false
# As of Obsidian 3.5.1, if anonymous lookups are not permitted or desired, provide the dn and password to be used for lookups. Typically, a read-only account with
# read rights to the LDAP entries and attributes in question is sufficient.
com.carfey.suite.security.LdapAuthenticator.searchUserFullDn=cn=ObsidianLDAPReadOnly,ou=people,o=MyOrgHere
com.carfey.suite.security.LdapAuthenticator.searchPassword=password
# As of Obsidian 4.5.1, an alternate search base configuration parameter is used for the searchUser
com.carfey.suite.security.LdapAuthenticator.searchUserDnBase=ou=people,o=MyOrgHere
# As of Obsidian 4.7.1, you may specify one or more additional group membership attributes beyond the defaults
com.carfey.suite.security.LdapAuthenticator.groupMembershipAttribute=businessGroup~~~departmentName

# Configure who may access the web app, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.accessDN=cn=SchedulerAccess,ou=groups,o=MyOrgHere

# Configure the Write role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.write.dn=cn=SchedulerWrite,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.write.roleName=Write

# Configure the Admin role used in the admin web app, based on LDAP group membership (users may configure system parameters, etc).
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.admin.dn=cn=SchedulerAdmin,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.admin.roleName=Admin

# Configure the LimitedRead role used in the admin web app, based on LDAP group membership (by default, users may only read)
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.dn=cn=SchedulerLimitedRead,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.limitedRead.roleName=LimitedRead

# Configure the APIrole used by the REST API, based on LDAP group membership
# As of Obsidian 4.5.0, you can provide a delimited list (delimiter is 3 tildes ~~~) of groups to search.
com.carfey.suite.security.LdapAuthenticator.role.api.dn=cn=SchedulerAPI,ou=groups,o=MyOrgHere
# No need to alter this
com.carfey.suite.security.LdapAuthenticator.role.api.roleName=API

</pre>

==== OAuth / OIDC Authentication Properties ====

To use OAuth / OIDC SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.OAuthAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.OAuthAuthenticator.'' (shown
without prefix in the table for brevity).

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''issuer'' || OIDC Issuer URL. Obsidian fetches ''<issuer>/.well-known/openid-configuration'' lazily on first use and caches it.
|-
| ''clientId'' || Client ID registered at the IdP.
|-
| ''clientSecret'' || Client secret. Keep out of version control.
|-
| ''redirectUri'' || Exact callback URL registered at the IdP (e.g. ''https://app.example.com/oauth/callback'').
|-
| ''scopes'' || Space-separated OAuth scopes (e.g. ''openid profile email groups''). Must include ''openid''.
|-
| ''claim.groups'' || Name of the token claim that carries group memberships (e.g. ''groups'').
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive).
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. At least one ''Admin'' mapping is required. Valid roles: '''Admin''', '''API''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)'').
|}

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates Obsidian session only. ''rp'': RP-initiated logout via IdP ''end_session_endpoint''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after RP-initiated logout. Ignored when ''logout.mode=local''.
|-
| ''claim.user'' || ''sub'' || Claim used as the internal user ID in audit logs. '''Strongly recommend keeping as ''sub'''''.
|-
| ''claim.displayName'' || ''preferred_username'' || Claim shown in the Obsidian UI nav bar. Separate from ''claim.user''.
|-
| ''claim.validateTyp'' || ''true'' || When ''true'', rejects Bearer tokens where ''typ'' is present but not ''at+JWT''. Set ''false'' only for legacy IdPs that omit ''typ''.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''exp''/''nbf'' validation (seconds).
|-
| ''metadata.ttlHours'' || ''24'' || OIDC discovery document cache TTL in hours.
|-
| ''expectedAccessTokenAudience'' || ''clientId'' || Expected ''aud'' for Bearer access tokens. See security note below.
|-
| ''claim.groupsSource'' || ''idtoken'' || Where to read groups during browser SSO: ''idtoken'', ''accesstoken'', or ''userinfo''.
|-
| ''claim.groupsBearerSource'' || ''accesstoken'' || Where to read groups on the Bearer path: ''idtoken'' or ''accesstoken''. '''userinfo is not permitted on the Bearer path.'''
|-
| ''claim.groupsValuePath'' || (none) || Sub-field name when groups is an array of objects (e.g. ''name'').
|-
| ''claim.groupsStripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''claim.groupsUserinfoTimeout'' || ''5'' || HTTP timeout in seconds for the userinfo endpoint. Only used when ''claim.groupsSource=userinfo''.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Requires ''dynamicRole.suffix''. Map is rebuilt at startup; adding a new root folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if IdP groups map to no Obsidian roles. Does not apply to REST Bearer tokens.
|}

===== Security notes =====

'''expectedAccessTokenAudience and cross-JWT confusion'''

When ''expectedAccessTokenAudience'' is not set it defaults to ''clientId''. In many OIDC
configurations the id_token also carries ''aud=clientId'', which could allow an id_token
to be submitted as a Bearer token. The ''claim.validateTyp=true'' default mitigates this
for compliant IdPs (access tokens carry ''typ=at+JWT''; id_tokens carry ''typ=JWT'').

For maximum defence, set ''expectedAccessTokenAudience'' to a distinct resource-server
identifier if your IdP supports it.

If ''claim.validateTyp=false'' AND ''expectedAccessTokenAudience'' is not explicitly set,
Obsidian logs a mandatory startup WARN advising you to set ''expectedAccessTokenAudience''.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.OAuthAuthenticator
com.carfey.suite.security.OAuthAuthenticator.issuer=http://localhost:8081/realms/obsidian
com.carfey.suite.security.OAuthAuthenticator.clientId=obsidian-client
com.carfey.suite.security.OAuthAuthenticator.clientSecret=test-client-secret-local
com.carfey.suite.security.OAuthAuthenticator.redirectUri=http://localhost:8080/oauth/callback
com.carfey.suite.security.OAuthAuthenticator.scopes=openid profile email groups
com.carfey.suite.security.OAuthAuthenticator.claim.groups=groups
com.carfey.suite.security.OAuthAuthenticator.claim.groupsSource=idtoken
com.carfey.suite.security.OAuthAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.OAuthAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.OAuthAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.OAuthAuthenticator.role.2.roleName=Write
com.carfey.suite.security.OAuthAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.OAuthAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.OAuthAuthenticator.role.4.group=Obsidian-API
com.carfey.suite.security.OAuthAuthenticator.role.4.roleName=API
com.carfey.suite.security.OAuthAuthenticator.displayName=Keycloak
com.carfey.suite.security.OAuthAuthenticator.logout.mode=local
com.carfey.suite.security.OAuthAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': groups claim contains GUIDs by default; configure Optional
Claims for display names. Accounts with 200+ groups trigger overage. Multi-tenant apps not
supported in v1.

'''Auth0''': opaque access tokens (Auth0 default) are not supported on the Bearer path.
Configure a custom API audience to get JWT access tokens.

'''Okta''': use the Custom Authorization Server URL, not the Org Authorization Server.

===== v1 limitations =====

* Opaque access tokens not supported on the REST/Bearer path.
* No ''jti'' replay protection.
* Microsoft Entra multi-tenant apps not supported.
* No post-login IdP session validity check.
* Dynamic role map requires restart for new root folders.
* Installer UI supports up to 10 static role pairs; runtime supports unlimited.

==== SAML Authentication Properties ====

To use SAML 2.0 SSO, set the ''Authenticator'' property to
''com.carfey.suite.security.saml.SAMLAuthenticator'' and add the properties below. All
properties are prefixed with ''com.carfey.suite.security.saml.SAMLAuthenticator.'' (shown
without prefix in the table for brevity). Note the ''.saml.'' package segment in both values.

Obsidian acts as a SAML Service Provider and supports SP-initiated browser login only. See
[[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)|Authenticator — SAMLAuthenticator]] for how the
login and logout flows behave and for the list of ''/saml'' endpoints.

===== Required properties =====

{| class="wikitable"
|-
! Property !! Description
|-
| ''entityId'' || SP entity ID registered at the IdP (e.g. ''https://app.example.com/obsidian''). Obsidian also requires this value to appear in the assertion's ''AudienceRestriction'' when the IdP sends one.
|-
| ''assertionConsumerServiceUrl'' || Exact ACS URL where the IdP posts responses. This must be Obsidian's callback endpoint, e.g. ''https://app.example.com/obsidian/saml/callback''.
|-
| ''idpMetadataUrl'' '''or''' ''idpMetadataFile'' || Source of the IdP federation metadata: an HTTP(S) URL, or an absolute path to a local XML file. Set exactly one of the two.
|-
| ''attribute.groups'' || Name of the assertion attribute carrying group memberships (e.g. ''groups''). Required unless ''dynamicRole.prefix'' is set instead.
|-
| ''role.<idx>.group'' || IdP group value for this mapping. ''<idx>'' is an arbitrary stable label (numeric or descriptive). Not needed if all roles come from ''dynamicRole''.
|-
| ''role.<idx>.roleName'' || Obsidian role for this mapping. The installer requires at least one ''Admin'' mapping, and you need one in practice so that somebody can administer Obsidian. Valid roles: '''Admin''', '''Write''', '''LimitedRead''', '''Operator''', '''Author''', and folder-based roles (''<folder>-(Write|Author|Operator)''). The ''API'' role has no effect on a SAML install, because the REST API is unavailable.
|}

Because ''signRequests'' defaults to enabled, a default configuration also requires the three
''keystore'' properties below. Disable ''signRequests'' only if your IdP does not require signed
authentication requests.

===== Optional properties =====

{| class="wikitable"
|-
! Property !! Default !! Description
|-
| ''displayName'' || (none) || Label on the SSO button: "Sign in with ''<displayName>''". Defaults to "Sign in with SSO".
|-
| ''signRequests'' || ''true'' || Signs the outbound ''AuthnRequest'' and SP ''LogoutRequest''. Requires the three ''keystore'' properties.
|-
| ''keystore.path'' || (none) || Path to the keystore holding the SP signing key. Required when ''signRequests'' is enabled.
|-
| ''keystore.password'' || (none) || Keystore password. Keep out of version control.
|-
| ''keystore.alias'' || (none) || Alias of the SP signing key within the keystore.
|-
| ''wantAssertionsSigned'' || ''true'' || Requires the IdP to sign assertions, verified against the signing certificate in the IdP metadata.
|-
| ''singleLogoutServiceUrl'' || (none) || SP single logout URL. When set it is published in Obsidian's SP metadata and is matched against the ''Destination'' of an incoming ''LogoutRequest''.
|-
| ''logout.mode'' || ''local'' || ''local'': invalidates the Obsidian session only. ''slo'': SP-initiated single logout via the IdP's HTTP-Redirect ''SingleLogoutService''.
|-
| ''postLogoutRedirectUri'' || (none) || Where to redirect after the IdP's ''LogoutResponse''. When blank the browser returns to ''/''.
|-
| ''nameIdFormat'' || ''urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified'' || ''NameIDPolicy'' format requested from the IdP. A transient format logs a startup warning, because transient NameIDs cannot serve as stable user IDs.
|-
| ''attribute.user'' || ''nameId'' || Assertion attribute used as the internal user ID in audit logs. '''Strongly recommend keeping as ''nameId'''''; any other value logs a startup warning.
|-
| ''attribute.displayName'' || (none) || Attribute shown in the Obsidian UI nav bar. Separate from ''attribute.user''.
|-
| ''attribute.groups.friendlyName'' || (none) || Match the groups attribute on its ''FriendlyName'' instead of its ''Name''.
|-
| ''attribute.groups.valuePath'' || (none) || Sub-field name when the groups attribute holds structured values.
|-
| ''attribute.groups.stripPrefix'' || (none) || Prefix to strip from each group value (e.g. ''/'' for Keycloak full-path style).
|-
| ''metadata.ttlHours'' || ''24'' || IdP federation metadata cache TTL in hours. A failed refresh falls back to the cached copy with a warning.
|-
| ''clockSkewSeconds'' || ''60'' || Clock skew tolerance for ''NotBefore'' / ''NotOnOrAfter'' validation (seconds).
|-
| ''forceAuthn'' || ''false'' || Sets ''ForceAuthn="true"'' on the ''AuthnRequest'', asking the IdP to reauthenticate the user.
|-
| ''authnContextClassRef'' || (none) || Requests a specific ''RequestedAuthnContext''. A differing context in the response is logged as a warning, not rejected.
|-
| ''dynamicRole.prefix'' || (none) || Prefix for auto-generated folder-role group mappings. Usable on its own. The map is built at startup, so adding a new root job folder requires a restart.
|-
| ''dynamicRole.suffix'' || (none) || Optional suffix for auto-generated folder-role group mappings. Requires ''dynamicRole.prefix''.
|-
| ''requireRole'' || ''true'' || When ''true'', browser SSO fails if the user's group attributes map to no Obsidian roles.
|}

===== Security notes =====

'''Encrypted assertions are not supported'''

Obsidian requires signed, unencrypted assertions. If your SP metadata carries no signing key
material, Obsidian logs a startup warning: IdPs such as AD FS may then choose to encrypt the
assertion, which this release cannot process. Configure the SP keystore and register the
generated metadata so the IdP sees a signing ''KeyDescriptor''.

'''Do not disable both signature settings'''

Setting ''signRequests'' and ''wantAssertionsSigned'' both to ''false'' is accepted but logs a
startup warning. In that state assertions are neither signed nor verified, which is not safe for
production.

'''SP-initiated flows and replay'''

Obsidian issues an ''AuthnRequest'' and tracks its ID in the browser session for five minutes.
When the IdP's response carries ''InResponseTo'', it must match one of those pending IDs and is
consumed on use, so the same response cannot be replayed. There is no persistent store of
processed assertion IDs, so keep assertion lifetimes short at the IdP.

'''Clustered deployments and IdP-initiated logout'''

An IdP-initiated ''LogoutRequest'' can only end the Obsidian session on the node that receives
it. Use sticky sessions if you rely on single logout across a cluster.

===== Keycloak example =====

<pre>
com.carfey.suite.security.Authenticator=com.carfey.suite.security.saml.SAMLAuthenticator
com.carfey.suite.security.saml.SAMLAuthenticator.entityId=https://app.example.com/obsidian
com.carfey.suite.security.saml.SAMLAuthenticator.assertionConsumerServiceUrl=https://app.example.com/obsidian/saml/callback
com.carfey.suite.security.saml.SAMLAuthenticator.idpMetadataUrl=https://keycloak.example.com/realms/obsidian/protocol/saml/descriptor
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.path=/opt/obsidian/saml-sp.p12
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.password=changeit
com.carfey.suite.security.saml.SAMLAuthenticator.keystore.alias=obsidian-sp
com.carfey.suite.security.saml.SAMLAuthenticator.attribute.groups=groups
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.group=Obsidian-Admins
com.carfey.suite.security.saml.SAMLAuthenticator.role.1.roleName=Admin
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.group=Obsidian-Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.2.roleName=Write
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.group=Obsidian-Read
com.carfey.suite.security.saml.SAMLAuthenticator.role.3.roleName=LimitedRead
com.carfey.suite.security.saml.SAMLAuthenticator.displayName=Keycloak
com.carfey.suite.security.saml.SAMLAuthenticator.logout.mode=local
com.carfey.suite.security.saml.SAMLAuthenticator.requireRole=true
</pre>

===== Provider notes =====

'''Microsoft Entra ID''': group claims are omitted from SAML assertions once an account belongs to
roughly 150 groups. Filter the groups sent to the application, or map app roles instead. Note this
threshold differs from the OIDC one described above.

'''AD FS''': the federation metadata document is normally at
''/FederationMetadata/2007-06/FederationMetadata.xml''. Register signing-capable SP metadata so AD FS
does not encrypt the assertion, which Obsidian cannot decrypt.

'''Okta''': use the application's SAML metadata URL for ''idpMetadataUrl''. Okta's logout endpoints
may be POST-only; if no HTTP-Redirect ''SingleLogoutService'' is advertised, ''logout.mode=slo''
falls back to local logout.

'''Auth0''': federation metadata is served at ''samlp/metadata/<client-id>''. Group memberships must
be added to the assertion with an Auth0 Action or rule.

'''Keycloak and other generic IdPs''': Keycloak publishes a SAML descriptor at
''/realms/<realm>/protocol/saml/descriptor''. Any IdP that publishes SAML 2.0 metadata with an
HTTP-POST ''AssertionConsumerService'' target and a signing certificate will work.

===== v1 limitations =====

* The REST API is unavailable while ''SAMLAuthenticator'' is active — there is no Bearer or JWT equivalent.
* SP-initiated login only.
* Encrypted assertions are not supported.
* No persistent assertion replay store beyond the single-use ''InResponseTo'' match and the assertion time window.
* Dynamic role map (''dynamicRole.prefix''/''suffix'') requires a server restart when new root job folders are added.
* Installer UI supports up to 10 static role pairs; the runtime supports unlimited.

=== SMTP Mail Properties ===

<pre>
# Email configuration for notifications, if desired
#for straight up open relay, just specify the host using
mail.smtp.host=smtp.myopenrelayhost.com
mail.smtp.port=port
#(standard ports are 25, 465 for SSL, 587 for TLS)

#for using TLS and SSL, provide these as necessary
mail.smtp.socketFactory.port=port
mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory
mail.smtp.auth=true
mail.smtp.user=myauthenticatedemailuser@email.com
mail.smtp.password=PASSWORD

# As of Obsidian 2.5.0, we support JNDI lookups for email sessions. All other email properties can be excluded.
mail.session.jndi.path=java:comp/env/mail/session
</pre>

=== Database Properties ===

<pre>
# Database configuration
com.carfey.obsidian.db.url=jdbc:mysql://localhost/obsidian
com.carfey.obsidian.db.userId=user
com.carfey.obsidian.db.password=pass

# Sample JDBC URL formats for all platforms
#com.carfey.obsidian.db.url=jdbc:mysql://localhost:3306/obsidian
#com.carfey.obsidian.db.url=jdbc:h2:C:/dev/workspace/obsidian;MVCC=TRUE
#com.carfey.obsidian.db.url=jdbc:oracle:thin:@localhost:1521:obsidian
#com.carfey.obsidian.db.url=jdbc:postgresql://localhost:5432/obsidian
#com.carfey.obsidian.db.url=jdbc:sqlserver://localhost:1433;databaseName=obsidian

# As of Obsidian 6.3.0, we support constructing simple JDBC urls from component properties
# Only supports basic URL formats noted above and does not support H2
#com.carfey.obsidian.db.host=localhost
#com.carfey.obsidian.db.port=3306
#com.carfey.obsidian.db.databaseName=obsidianDB
#com.carfey.obsidian.db.dbType=mariadb/mysql/oracle/postgresql/sqlserver
#com.carfey.obsidian.db.oracleSid=SIDORCL

# As of Obsidian 2.5.0, we support JNDI lookups for database connectivity.
com.carfey.obsidian.db.url=java:comp/env/jdbc/obsidian
com.carfey.obsidian.db.jndiType=mysql
#com.carfey.obsidian.db.jndiType=mysql is also used for MariaDB
#com.carfey.obsidian.db.jndiType=oracle
#com.carfey.obsidian.db.jndiType=postgresql
#com.carfey.obsidian.db.jndiType=h2
#com.carfey.obsidian.db.jndiType=sqlserver

# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_

# For Oracle databases, when Obsidian's tables exist in a different schema from the user specified above, or if the user does not default to the schema matching its name, specify the target schema here. Available as of version 2.1.
# For details on the required privileges to run with an alternate user, see https://wiki.obsidianscheduler.com/docs/Obsidian_Tables#Oracle_Privileges
# This same configuration item can be used to configure the Postgresql schema. If unspecified, the default is public. Available as of Obsidian 2.1.1.
# If using JNDI and Oracle/Postgresql, we recommend you set this value to ensure best performance.
com.carfey.obsidian.db.schema=obsidian

#default max connections per pool if not specified is 50
com.carfey.obsidian.db.maxConnections=40

#default millis timeout to retrieve available connection from pool if not specified is 2000
com.carfey.obsidian.db.connectionTimeout=2000

# As of 3.4.0, you can disable pooling of connections, which is suggested only if using another connection pool through JNDI. When true, maxConnections is ignored.
# When a JNDI data source is selected in the installer, this is set to true by default.
com.carfey.obsidian.db.disablePooling=true

# As of 4.3.0, Oracle database supports configured wait time.
com.carfey.obsidian.db.timedLockWaitEnabled=true (default)
com.carfey.obsidian.db.timedLockWaitSeconds=1 (default, prior to 4.3.0, indefinite wait)

</pre>

=== Logging Properties ===
As of '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/2.x/manual/configuration.html Log4j2 configuration]

Before '''Obsidian 5.0.0'''

Please see [https://logging.apache.org/log4j/1.2/manual.html Log4j Configuration]

=== Miscellaneous Properties ===

<pre>
# If you wish to change the tokens used to reference global parameters in your job configuration, use the following two values:
global.param.start.token={{
global.param.end.token=}}

# Populated by the installer, these values can be used to initialize licence key information into the database.
com.carfey.obsidian.licence.key=licenceKey
# Name is only required for hardware-linked or site licenses. Use the name exactly as provided by Carfey Software Corporation in your license email.
com.carfey.obsidian.licence.name=licenceeName

# As of 2.8.0, if you have issues with classloading (e.g. in Grails or Spring), this flag enables usage of the context classloader .
com.carfey.jdk.useContextClassLoader=true

# As of 2.9.0, you can set the scheduler host designator name multiple times in the same JVM by using this parameter:
com.carfey.obsidian.schedulerDesignation=obsidian-dev

# As of 3.0.0, Job Forking can be enabled and configured per node
com.carfey.obsidian.jvmJobForkingEnabledOnThisNode=true
# This property is the location of the fork scripts. Obsidian is bundled with obsidianForkedJob.bat and obsidianForkedJob.sh. These are the expected script names.
com.carfey.obsidian.forkedJobScriptLocation=/Obsidian-3.0.0
# Use the following optional property if you need to override the default classpath that is built using the contents of the standalone directory.
# This allows for job forking support in embedded and even webapp deployments. Use the classpath format supported by your operating system.
#com.carfey.obsidian.forkedJobscriptClasspathOverride=
# Use the following optional property if you wish to include database configuration parameters as arguments passed to the forking scripts and the target forked Obsidian class.
# For example, you may need to do this if your configuration is done via System Property overrides or programmmatically in your embedded Obsidian instance.
#com.carfey.obsidian.jvmJobForkingIncludeDbSysParms=true

# Obsolete as of 4.0.0. As of 3.4.0, the base URL used to resolve links in the Obsidian web app can be overridden. This is typically only required when a load balancer or proxy is used to access Obsidian.
com.carfey.obsidian.baseHrefUrl=http://myhost:8080/obsidian

# As of 4.3.0, description/parameter formatting is supported. Custom formatter (com.carfey.ops.job.config.formatter.Formatter) supported via this parameter.
com.carfey.obsidian.formatterClass=com.carfey.ops.job.config.formatter.MarkdownFormatter (default)

# As of 4.4.0, support for running DDL outside Obsidian and applying only the data portion of upgrades. May require incremental upgrades. Contact support for assistance. Enabled with the following:
com.carfey.obsidian.runner.skipDDL=true

# As of 4.5.0, Slack notifications can be automatically configured for FATAL, ERROR and WARN events by setting this property with a Slack incoming web hook URL. The user name property is optional and defaults to Obsidian Scheduler
com.carfey.obsidian.slack.webhookUrl=https://hooks.slack.com/services/XXXXXXX/YYYYYYYY/ZZZZZZZZZZ
com.carfey.obsidian.slack.userName=Obsidian Scheduler (prod)

# As of 4.6.0, Obsidian supports starting a node in paused state. This can also be set as a System property.
com.carfey.obsidian.schedulerPausedOnStartup=true

# As of 4.10.0, Obsidian supports disabling script engine jobs selectively.
com.carfey.ops.job.script.BeanShellJob.enabled=true
com.carfey.ops.job.script.GroovyJob.enabled=true
com.carfey.ops.job.script.RubyJob.enabled=true
com.carfey.ops.job.script.PythonJob.enabled=true
com.carfey.ops.job.script.JavaScriptJob.enabled=true

# As of 5.0.0, Signal interrupt (supported as of 4.5.1) is disabled by default. Use configuration to enable.
com.carfey.obsidian.signalHandlerActiveForScheduler=true

# As of 5.2.0, you can send Obsidian events to a REST endpoint via an out-of-the-box Event Hook. The basicAuthorization property is optional, the sample showing its use for myusername:mypassword. The "Basic " prefix is added by Obsidian.
com.carfey.obsidian.restfulEventHook.url=https://myendpoint.com:1234/rest/obsidian_events
com.carfey.obsidian.restfulEventHook.basicAuthorization=bXl1c2VybmFtZTpteXBhc3N3b3Jk

# As of 5.2.1, maintenance jobs are automatically scheduled for new installations. Set the following property to disable this behaviour.
com.carfey.obsidian.skipMaintenanceJobInitialization=true

# As of 5.2.1, you can send Obsidian events to standard output and error streams using an out-of-the-box Event Hook. You can enable the default behaviour and auto-register it by adding the following configuration.
com.carfey.obsidian.standardOutputStreamsEventHook.enabled=true
</pre>

=== Table Prefixes ===
As shown in full configuration reference, a table name prefix may be specified to create Obsidian tables with names beginning with a specified string.

<pre>
# Table prefix may be used to add a prefix to tables and related database objects. It must be 6 or fewer characters and can contain letters or underscores. Available as of version 2.0.
com.carfey.obsidian.db.tablePrefix=OBSDN_
</pre>

== Properties/Yaml File ==

The above configuration must reside in a properties file named <code>com.carfey.properties</code> or a yaml file named <code>com.carfey.yaml</code> found according to the rules of [http://docs.oracle.com/javase/6/docs/api/java/lang/ClassLoader.html#getResource(java.lang.String) ClassLoader.getResource]. If both yaml and properties files are found, yaml is loaded first and properties values will override. Some possibilities include <code>WEB-INF/classes/com.carfey.(properties/yaml)</code>, a <code>com.carfey.(properties/yaml)</code> file in a directory which is explicitly added to the classpath, or at the root of a jar file as is done in <code>obsidian-props.jar</code> for standalone deployments. Prior to Obsidian 3.6, this file had to exist on the classpath, even if only using the override options below to configure Obsidian.

Instead of using a classpath resource for properties, you can specify an external properties file using the Java system property <code>carfey.properties.file</code>. All expected properties must be specified in either the default <code>com.carfey.properties</code> file on the classpath or in the override file. Any properties found in both files will use the override file's values. Usage: <code>-Dcarfey.properties.file=/home/obsidian/obsidian.properties</code>.

Instead of using a classpath resource for yaml, you can specify an external yaml file using the Java system property <code>carfey.yaml.file</code>. All expected configuration values must be specified in either the default <code>com.carfey.yaml</code> file on the classpath or in the override file. Any configuration values found in both files will use the override file's values. Usage: <code>-Dcarfey.yaml.file=/home/obsidian/obsidian.yaml</code>.

As of Obsidian 2.1, you may also use a programmatic properties override. Simply call <code>com.carfey.jdk.sys.Configurator.setOverride(Properties props)</code> as early as possible in the application startup. To quote the javadoc of this method, ''For use as a programmatic properties override. This must be called before any classes are accessed either through invocation or class initialization that may require access to configuration done through properties. Best if done as early as possible in code, perhaps first in an entry point class that does little else and then hands-off to existing entry point.''

As of Obsidian 4.4, you may specify configuration values as System Properties or Environment Variables. Duplicated values are resolved as follows:
# System Property
# Environment Variable - '''''overridden by System Property'''''
# Properties - '''''overridden by Environment Variable and System Property'''''

== Notifications Configuration ==

Sending notifications requires SMTP configuration to be defined in the Obsidian properties file. The properties file reference at the beginning of this page includes SMTP configuration details.

In addition to the properties file, you can configure some Notifications settings to tweak how your emails are sent. These values are configurable under the ''Dispatch'' category of the [[Admin Scheduler Settings|scheduler settings]] screen. Defaults are provided, but you can update them appropriately for your needs.

=== Notification sender address and DMARC ===

The notificationFromEmail scheduler setting controls the From address used for notification emails. It is available under:

''Scheduler Settings → Dispatch → notificationFromEmail''

Set this to an address belonging to your organization and authorized by the SMTP service configured for your Obsidian installation.

Do not use ops-notification@obsidianscheduler.com when sending through your own SMTP infrastructure. Your SMTP server normally cannot authenticate mail for the obsidianscheduler.com domain. This can cause SPF, DKIM, and DMARC failures and may result in notifications being quarantined or rejected.

Example:

scheduler-notifications@example.com

After updating the value, trigger a test notification and confirm successful receipt.

[[File:NotifSettings_4.0.png]]

== Dependent Libraries ==

Obsidian Scheduler requires a number of third party libraries, both for the web administration application and the scheduler itself. Below is information on these libraries and how they are used. Unless otherwise noted, they are mandatory. As of Obsidian 2.5.0, our installer supports selective [[Installation_Guide#Configuring_3rd_Party_Library_Conflict_Management|conflict management]].

''Authentication (OAuth / OIDC)''
All libraries in this section are only required when OAuthAuthenticator is active. '''As of Obsidian 7.0.0'''

* oauth2-oidc-sdk-11.23.1.jar, nimbus-jose-jwt-10.0.2.jar. Nimbus OAuth 2.0 SDK with OpenID Connect extensions and JOSE+JWT support.
* content-type-2.3.jar, lang-tag-1.7.jar. Supporting libraries for the Nimbus SDK.
* json-smart-2.5.2.jar, accessors-smart-2.5.2.jar. JSON parsing for the Nimbus SDK.
* jcip-annotations-1.0-1.jar. Concurrency annotations for the Nimbus SDK.
* asm-9.7.1.jar. Bytecode manipulation library; transitive dependency of the Nimbus SDK.

''Authentication (SAML 2.0)''
All libraries in this section are only required when SAMLAuthenticator is active; the installer removes them when SAML is not the selected authentication type. '''As of Obsidian 7.0.0'''

* opensaml-core-4.3.2.jar, opensaml-saml-api-4.3.2.jar, opensaml-saml-impl-4.3.2.jar, opensaml-security-api-4.3.2.jar, opensaml-security-impl-4.3.2.jar, opensaml-xmlsec-api-4.3.2.jar, opensaml-xmlsec-impl-4.3.2.jar, opensaml-messaging-api-4.3.2.jar, opensaml-profile-api-4.3.2.jar, opensaml-soap-api-4.3.2.jar, opensaml-soap-impl-4.3.2.jar, opensaml-storage-api-4.3.2.jar. OpenSAML 4 modules implementing SAML 2.0 messages, metadata and signature handling.
* java-support-8.4.2.jar. Shibboleth utility library required by OpenSAML.
* xmlsec-2.3.4.jar. Apache Santuario XML Signature implementation.
* cryptacular-1.2.5.jar, bcprov-jdk18on-1.85.jar, bcpkix-jdk18on-1.85.jar, bcutil-jdk18on-1.85.jar. Cryptographic providers used for assertion signature verification and SP key handling.
* velocity-engine-core-2.3.jar. Template engine used by OpenSAML's message encoders.
* commons-lang3-3.20.0.jar, commons-codec-1.15.jar. Apache Commons utilities required by OpenSAML.
* httpclient-4.5.14.jar, httpcore-4.4.16.jar. HTTP client used to retrieve IdP federation metadata.
* guava-32.1.3-jre.jar, failureaccess-1.0.1.jar, listenablefuture-9999.0-empty-to-avoid-conflict-with-guava.jar. Guava collections and its companion placeholder artifacts, required by OpenSAML.
* metrics-core-4.2.25.jar. Dropwizard Metrics, required by OpenSAML.
* slf4j-api-2.0.12.jar, log4j-slf4j2-impl-2.26.0.jar. SLF4J API and its log4j2 binding, so OpenSAML's diagnostic logging is routed into Obsidian's log4j2 configuration.

''Embedded Tomcat (Obsidian Embedded Tomcat JAR packs only)''

* tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar — Apache Tomcat embedded components (Apache License 2.0). Present in '''embed-tomcat-lib/''' when an Embedded Tomcat pack is selected.

''Common''
* obsidian.jar. Core Obsidian lib.
* gson-2.10.1. Supports REST API and web administration.
* jmustache-1.15.jar. Provides email templating.
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar. Obsidian logging uses log4j2.
* snakeyaml-2.3.jar. Support for YAML configuration.

''Databases''
* h2-1.4.200.jar. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-2.7.2.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* mssql-jdbc-9.2.1.jre11.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc11-21.1.0.0.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-42.2.19.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

''Mail''
* activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.
* angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
* jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.

''Scripts''
* bsh-2.0b5.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* jruby-9.2.17.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jython-standalone-2.7.2.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.

'''Scripts - Prior to Obsidian 7.0.0:'''
Groovy scripting shipped as a single uber archive: apache-groovy-all-4.0.24.jar

'''Scripts - As of Obsidian 7.0.0:'''
Groovy scripting ships as 13 modular JARs: groovy-4.0.24.jar, groovy-astbuilder-4.0.24.jar, groovy-datetime-4.0.24.jar, groovy-dateutil-4.0.24.jar, groovy-json-4.0.24.jar, groovy-jsr223-4.0.24.jar, groovy-macro-4.0.24.jar, groovy-macro-library-4.0.24.jar, groovy-nio-4.0.24.jar, groovy-sql-4.0.24.jar, groovy-templates-4.0.24.jar, groovy-typecheckers-4.0.24.jar, groovy-xml-4.0.24.jar.
Plus four owned transitives (included when Groovy is enabled): asm-analysis-9.7.1.jar, asm-tree-9.7.1.jar, asm-util-9.7.1.jar, javaparser-core-3.26.2.jar
All 17 JARs above are excluded when Groovy scripting is disabled at install time.

''Web Admin''
* dom4j-2.1.3.jar. XML utilities.
* flexmark-0.62.2.jar, flexmark-util-0.62.2.jar. Markdown formatting for Description and Parameter job annotations.
* jxl-2.6.12.jar. Excel file format utilities. Only required in web administration.
* opencsv-5.4.jar. Support for CSV downloads in UI.

'''Web Admin - As of Obsidian 7.0.0:'''
Wiki rendering ships as 12 modular JARs:
flexmark-0.62.2.jar, flexmark-util-ast-0.62.2.jar, flexmark-util-builder-0.62.2.jar, flexmark-util-collection-0.62.2.jar, flexmark-util-data-0.62.2.jar, flexmark-util-dependency-0.62.2.jar, flexmark-util-format-0.62.2.jar, flexmark-util-html-0.62.2.jar, flexmark-util-misc-0.62.2.jar, flexmark-util-options-0.62.2.jar, flexmark-util-sequence-0.62.2.jar, flexmark-util-visitor-0.62.2.jar

'''As of Obsidian 7.0.0''', the following changes were made:
* '''log4j upgraded''': log4j-api and log4j-core updated from 2.17.1 to 2.26.0.
* '''Modular Groovy libraries''': Obsidian no longer ships '''apache-groovy-all-4.0.24.jar'''. Groovy scripting now uses 13 modular JARs (see ''Scripts'' above). When Groovy is disabled at install time, all 13 modules are excluded.
* '''Modular Flexmark libraries''': Obsidian no longer ships '''flexmark-util-0.62.2.jar'''. Wiki rendering now uses 12 modular Flexmark JARs (see ''Scripts'' above).
* '''OAuth / OIDC authentication libraries''' added (Nimbus OAuth 2.0 SDK and transitive dependencies). Required only when OAuthAuthenticator is configured. See [[Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties|Authentication (OAuth/OIDC)]] above.
* '''SAML 2.0 authentication libraries''' added (OpenSAML 4 and its transitive dependencies, plus the SLF4J-to-log4j2 binding). Required only when SAMLAuthenticator is configured. See [[Advanced_Configuration#SAML_Authentication_Properties|Authentication (SAML 2.0)]] above.
* Embedded Tomcat runtime added (tomcat-embed-core-10.1.39.jar, tomcat-embed-el-10.1.39.jar). Present only when an Embedded Tomcat pack is selected. Replaces the Jetty quick-start distribution which has been removed.

'''Prior to Obsidian 7.0.0''', the following libraries were in use.
* log4j-api-2.17.1.jar, log4j-core-2.17.1.jar. Obsidian logging uses log4j2.

'''Prior to Obsidian 6.0.0''', the following library was in use.
* groovy-all-3.0.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 5.4.0''', the following library was in use.
* gson-2.8.6.jar. Supports REST API and web administration.

'''Prior to Obsidian 5.2.0''', the following library was in use.
* jakarta.activation-1.2.1.jar. Used for email notifications.

'''Prior to Obsidian 5.0.3''', the following older libraries were in use.
* ''Obsidian 5.0.2'' log4j-api-2.16.0.jar, log4j-core-2.16.0.jar.
* ''Obsidian 5.0.1'' log4j-api-2.15.0.jar, log4j-core-2.15.0.jar.
* ''Obsidian 5.0.0'' log4j-api-2.14.1.jar, log4j-core-2.14.1.jar.

'''Prior to Obsidian 5.0.0''', the following older libraries were in use.
* activation-1.1.jar, javax.mail-1.5.5.jar. Used for email notifications.
* dom4j-1.6.1.jar. XML utilities.
* gson-2.7.jar. Supports REST API and web administration.
* bsh-2.0b4.jar. Support for our Bean Shell script execution. (http://www.beanshell.org). Only required for BeanShellJob usage.
* groovy-all-2.4.14.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.7.0.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jruby-complete-9.2.7.0.jar. Support for Ruby script execution (https://www.jruby.org/). Only required for RubyJob usage.
* jmustache-1.12.jar. Provides email templating.
* h2-1.4.192. H2 database and JDBC driver. Only required for running H2.
* log4j-1.2.9.jar. Obsidian logging uses log4j.
* mariadb-java-client-1.4.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.3.1.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc7-12.1.0.1.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.4.1208.jre7.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.
* opencsv-3.8.jar. Support for CSV downloads in UI.
* flexmark-0.19.6.jar, flexmark-util-0.19.6.jar (as of 4.3.0). Markdown formatting for Description and Parameter job annotations.

'''Prior to Obsidian 4.5.1''', the following older libraries were in use.
* groovy-all-2.4.7.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.

'''Prior to Obsidian 4.0.0''', the following older libraries were in use.
* javax.mail-1.5.2.jar. Used for email notifications.
* jstl.jar, standard.jar. Web utilities. Only required in web administration.
* gson-2.2.2.jar. Supports REST API and web administration.
* groovy-all-2.1.8.jar. Support for Groovy script execution (https://groovy-lang.org/). Only required for GroovyJob usage.
* jython-standalone-2.5.3.jar. Support for Python script execution (https://www.jython.org/). Only required for PythonJob usage.
* jmustache-1.8.jar. Provides email templating.
* h2-1.3.154. H2 database and JDBC driver. Only required for running H2.
* mariadb-java-client-1.1.5.jar. MySQL JDBC driver. Only required for running against MySQL or MariaDB.
* jtds-1.2.8.jar. SQL Server JDBC driver. Only required for running SQLServer.
* ojdbc6-11.2.0.3.jar. Oracle JDBC driver. Only required for running Oracle.
* postgresql-9.0-801.jdbc4.jar. PostgreSQL JDBC driver. Only required for running PostgreSQL.

'''Prior to Obsidian 2.9.1''', the following redundant library was in included in the Obsidian packaging.
* smtp.jar. Used for email notifications.

'''Prior to Obsidian 2.2.0''', the following older libraries were in use.
* groovy-all-1.7.6.jar
* jython.jar (version 2.5.2rc2)

'''Prior to Obsidian 2.1.1''', the following libraries were also included.
* carfey-date-1.2.jar or carfey-date-1.1.jar. Date math/manipulation.
* jdk-gen.jar, jdk.jar, suite-gen.jar, suite.jar. Core Obsidian libs.

'''Prior to Obsidian 2.1.0''', the following older libraries were in use.
* ojdbc14.jar Oracle JDBC driver. Only required for running Oracle.

'''Prior to Obsidian 1.5''', the following older libraries were in use.
* gson-1.5.jar. Supports REST API and web administration.

=== Required Libraries for Embedded API ===

To use the [[Embedded_API|Embedded API]], the following resources should be imported. If you have newer versions of the same JARs in your application, feel free to use the newer version. The JAR files below can generally be found in the ''standalone'' directory if your installation. The <code>com.carfey.properties</code>/<code>com.carfey.yaml</code> file can be extracted from the <code>obsidian-properties-configuration.jar</code>/<code>obsidian-yaml-configuration.jar</code> in the ''standalone'' directory, or from an Obsidian WAR file under <code>WEB-INF/classes</code>.

* com.carfey.properties/com.carfey.yaml (configuration file), or obsidian-properties-configuration.jar/obsidian-yaml-configuration.jar, which contains the configuration file
* obsidian.jar
* dom4j-2.1.3.jar
* flexmark-0.62.2.jar plus the modular Flexmark JARs listed under ''Web Admin'' above
* gson-2.10.1
* log4j-api-2.26.0.jar, log4j-core-2.26.0.jar
* Appropriate JDBC JAR (e.g. mariadb-java-client-2.7.2.jar for MySQL or MariaDB)

In addition, the following resources should be included if you wish to have notification support enabled when using the API:
* jmustache-1.15.jar
** jakarta.activation-api-2.1.2.jar, jakarta.mail-api-2.1.2.jar. Used for Jakarta EE email notifications.
** angus-activation-2.0.1.jar, angus-mail-2.0.2.jar. Optionally used with Jakarta EE email notifications.
** activation-1.1.jar, javax.mail-1.6.2.jar. Used for javamail (javax) email notifications.

Finally, if you need to configure scripting jobs from the API, you will need to include any applicable JARs from the following list:
* apache-groovy-all-4.0.24.jar
* bsh-2.0b5.jar
* jruby-9.2.17.0.jar
* jython-standalone-2.7.2.jar

== Disabling Job Execution & Scheduling in the Web Application ==
See the instructions within the [[Getting_Started#Disabling_Job_Scheduling_in_the_Web_Application|Getting Started Guide]].

== Disabling Automatic Database Updates ==
See the instructions within the [[Getting_Started#Disabling_Automatic_Database_Updates|Getting Started Guide]].