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, as starting with Obsidian 2.0, ''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'''

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]]

File:MFA reset success.png

2021-08-04T19:50:50Z

Carfey:

Admin User Management

2021-08-04T19:50:42Z

Carfey: /* MFA Resets */

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, as starting with Obsidian 2.0, ''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'''

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]]

File:MFA reset page.png

2021-08-04T19:49:28Z

Carfey:

File:MFA user listing reset button.png

2021-08-04T19:47:12Z

Carfey:

File:MFA setup prompt.png

2021-08-04T19:44:19Z

Carfey: Carfey uploaded a new version of File:MFA setup prompt.png

Admin User Management

2021-08-04T19:43:15Z

Carfey: /* Completing MFA Setup */

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, as starting with Obsidian 2.0, ''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'''

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 ===

Admin User Management

2021-08-04T19:42:28Z

Carfey: /* Completing MFA Setup */

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, as starting with Obsidian 2.0, ''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'''

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|400px]]

=== 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 ===

Admin User Management

2021-08-04T19:42:21Z

Carfey: /* Completing MFA Setup */

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, as starting with Obsidian 2.0, ''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'''

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|500px]]

=== 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 ===

Admin User Management

2021-08-04T19:41:59Z

Carfey: /* Completing MFA Setup */

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, as starting with Obsidian 2.0, ''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'''

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.

=== 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 ===

Job Features

2019-01-16T23:50:07Z

Carfey: /* Execution Statuses */

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#Execution_.26_Pickup|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.jpg]]

= 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.

As of Obsidian 2.2.1, a configuration item allows you to specify whether you wish host restrictions to apply on AdHoc jobs or not. On new installations of 2.2.1, it defaults to TRUE while it defaults FALSE (to maintain behaviour from versions before 2.2.1) on upgrades from prior releases. It can by found under '''[[Admin Scheduler Settings|Scheduler Settings]] / Job / adHocJobsRespectFixedHostsRestrictions'''.

=Host Preference =

In addition to strict host selections, Obsidian 3.0 introduces 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#Job_Edit_Screen|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.

As of Obsidian 2.0, 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.

As of Obsidian 2.5.0, 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.

As of ''Obsidian 3.8.0'', 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) =
As of Obsidian 1.5.

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]].

As of Obsidian 3.4.0, [[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]].

File:Obsidian execution statuses.png

2019-01-16T23:49:28Z

Carfey:

Job Features

2019-01-15T00:58:45Z

Carfey: /* Recovery */

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#Execution_.26_Pickup|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.

= 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.

As of Obsidian 2.2.1, a configuration item allows you to specify whether you wish host restrictions to apply on AdHoc jobs or not. On new installations of 2.2.1, it defaults to TRUE while it defaults FALSE (to maintain behaviour from versions before 2.2.1) on upgrades from prior releases. It can by found under '''[[Admin Scheduler Settings|Scheduler Settings]] / Job / adHocJobsRespectFixedHostsRestrictions'''.

=Host Preference =

In addition to strict host selections, Obsidian 3.0 introduces 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#Job_Edit_Screen|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.

As of Obsidian 2.0, 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.

As of Obsidian 2.5.0, 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.

As of ''Obsidian 3.8.0'', 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) =
As of Obsidian 1.5.

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]].

As of Obsidian 3.4.0, [[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]].

REST Endpoints

2018-09-27T19:45:51Z

Carfey: /* GET a list of an existing job's schedules */

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.

As of Obsidian 2.3, all endpoints have corresponding bean classes that can be used with JSON object mappers like [https://code.google.com/p/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 (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"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 (as of 2.0)
},
"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 (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 37,
"status": "CHAIN_ACTIVE",
"endDate": "2013-01-08T14:34:00-0800",
"effectiveDate": "2013-01-07T14:34:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"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": "* * * * *",
"jobScheduleId": 35,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2031-04-30T08:00:00-0800",
"endDate": "2031-04-30T08:00:00-0800",
"schedule": "0 8 30 4 3#5",
"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 (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"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 (as of 3.4)
"chainAll" : true // corresponds to chainAll setting on job creation (as of 2.3)
},
"parameters": [
{
"name": "level",
"type": "STRING",
"allowMultiple": true,
"required": true,
"values": [ "WARN", "ERROR" ], // as of 2.5, 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 (as of 3.4)
"chainAll": false, // as of 2.0
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"customCalendarId": null, // as of 2.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "{{globalLevels}}" // as of 2.5, 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 50 chars before 1.5.2, after which it is 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. As of Obsidian 3.3.0, 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 || As of Obsidian 2.0. 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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| autoRetryInterval|| N || As of Obsidian 2.5. Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || As of Obsidian 2.5. Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || As of Obsidian 2.0. 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]].

As of Obsidian 2.3, 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 (as of 3.4)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| autoRetryInterval|| N || As of Obsidian 2.5. Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || As of Obsidian 2.5. Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || As of Obsidian 2.0. 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). As of Obsidian 3.7.0.
|-
| end || N || End date for the runtimes to preview (inclusive). Must be after the start time. As of Obsidian 3.7.0.
|}

'''Sample Response'''
<pre>
{
"schedules": [
{
"effectiveDate": "2012-01-06T15:53:00-0800",
"endDate": "2012-08-06T15:53:00-0700",
"schedule": "@hourly",
"status": "ENABLED",
"jobScheduleId": 37,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"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 (as of 2.0)
}
</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. As of Obsidian 3.3.0, 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 || As of Obsidian 2.0, 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>

''Available as of version 2.5.''

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>

''Available as of version 2.5.''

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. As of Obsidian 3.5, 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 (before 2.3, it defaulted to the current minute).
|-
| 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. ''As of Obsidian 3.5.0.''
|-
| 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. ''As of Obsidian 3.5.0.''
|-
| 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 (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"runtimeOrdinal": 0, //as of 3.8.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 (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"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 (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted (as of version 1.5.1)
"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, //as of 3.8.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 (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"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. Available as of 2.1.1. 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 (as of 1.5.1)
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 36,
"nickname": "testWithOutput",
"activeSchedule": {
"jobScheduleId": 37,
"schedule": "@hourly",
"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 (as of 2.0)
},
"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 (as of 2.1.1). 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 ==
'''<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, // as of 3.8.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>

''Available as of version 1.5.1.''

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>

= 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 (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"jobId": 36,
"nickname": "jobOne",
"schedule": "* * * * *",
"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": "* * * * *",
"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 =

''As of Obsidian 2.4.''

==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": "* * * * *", // optional
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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": "* * * * *", // optional
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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==
''Available as of version 2.6.''

'''<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 =

''As of Obsidian 2.4.

==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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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. As of 2.9.0, 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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 licence details on an existing scheduling host==
'''<code>PUT http(s)://localhost/rest/hosts/{id}/licence_health</code>'''        ''Prior to 4.5'': '''<code>PUT 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.

= Custom Calendar Endpoints =

''As of Obsidian 2.0. Format revised in 2.3.''

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>

''As of Obsidian 2.3.''

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==

''Available as of version 3.0.''

'''<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 =

''As of Obsidian 3.0.''

==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 =

''As of version 3.0.''

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 =

''As of Obsidian 3.0''

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 =

''As of Obsidian 3.0''

==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 =

''As of version 3.0.''

==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 =

''As of version 3.0.''

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.

= System Restore Endpoints =

''As of version 3.0.''

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. Since 3.8.0.
|-
| 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. Since 3.8.0.
|}

'''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": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.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": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.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 - xisting 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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,%20java.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).

REST Endpoints

2018-05-23T17:35:24Z

Carfey: /* GET details of an existing job */

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.

As of Obsidian 2.3, all endpoints have corresponding bean classes that can be used with JSON object mappers like [https://code.google.com/p/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 (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"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 (as of 2.0)
},
"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 (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"chainAll" : true, // corresponds to chainAll setting on job creation (as of 2.3)
"activeSchedule": {
"jobScheduleId": 37,
"status": "CHAIN_ACTIVE",
"endDate": "2013-01-08T14:34:00-0800",
"effectiveDate": "2013-01-07T14:34:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"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": "* * * * *",
"jobScheduleId": 35,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"effectiveDate": "2031-04-30T08:00:00-0800",
"endDate": "2031-04-30T08:00:00-0800",
"schedule": "0 8 30 4 3#5",
"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 (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"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 (as of 3.4)
"chainAll" : true // corresponds to chainAll setting on job creation (as of 2.3)
},
"parameters": [
{
"name": "level",
"type": "STRING",
"allowMultiple": true,
"required": true,
"values": [ "WARN", "ERROR" ], // as of 2.5, 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 (as of 3.4)
"chainAll": false, // as of 2.0
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"customCalendarId": null, // as of 2.0
"parameters": [
{
"name": "level",
"type": "STRING",
"value": "ERROR"
},
{
"name": "level",
"type": "STRING",
"value": "{{globalLevels}}" // as of 2.5, 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 50 chars before 1.5.2, after which it is 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. As of Obsidian 3.3.0, 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 || As of Obsidian 2.0. 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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| autoRetryInterval|| N || As of Obsidian 2.5. Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || As of Obsidian 2.5. Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || As of Obsidian 2.0. 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]].

As of Obsidian 2.3, 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 (as of 3.4)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.0)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"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 || As of Obsidian 2.0. Number of auto retries on non-interrupted execution failure. 0 if none are desired.
|-
| autoRetryInterval|| N || As of Obsidian 2.5. Minimum number of minutes between auto retries - calculated from failure time. Defaults to 0 and indicates try at next available opportunity.
|-
| autoRetryIntervalExponent|| N || As of Obsidian 2.5. Boolean indicating whether to exponentially increase interval time between retries.
|-
| chainAll || N || As of Obsidian 2.0. 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 a basically 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). As of Obsidian 3.7.0.
|-
| end || N || End date for the runtimes to preview (inclusive). Must be after the start time. As of Obsidian 3.7.0.
|}

'''Sample Response'''
<pre>
{
"schedules": [
{
"effectiveDate": "2012-01-06T15:53:00-0800",
"endDate": "2012-08-06T15:53:00-0700",
"schedule": "@hourly",
"status": "ENABLED",
"jobScheduleId": 37,
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
{
"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 (as of 2.0)
}
</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. As of Obsidian 3.3.0, 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 || As of Obsidian 2.0, 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>

''Available as of version 2.5.''

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>

''Available as of version 2.5.''

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. As of Obsidian 3.5, 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 (before 2.3, it defaulted to the current minute).
|-
| 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. ''As of Obsidian 3.5.0.''
|-
| 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. ''As of Obsidian 3.5.0.''
|-
| 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 (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"runtimeOrdinal": 0, //as of 3.8.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 (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"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 (as of 1.5.1)
"autoRetryCount": 0, // indicates number of auto-retry attempts to be made on failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 44,
"schedule": "@hourly",
"status": "ENABLED",
"endDate": "2013-01-06T17:44:00-0800",
"effectiveDate": "2013-01-06T16:03:00-0800",
"customCalendarId": 123 // if configured, the custom calendar (as of 2.0)
},
"jobClass": "someclass"
},
// optional interruption element if job execution was interrupted (as of version 1.5.1)
"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, //as of 3.8.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 (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"minExecutionDuration" : "1s", // only present when defined on job (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"revision" : 0, // Present as of 2.3
"activeSchedule": {
"jobScheduleId": 45,
"schedule": "@hourly",
"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. Available as of 2.1.1. 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 (as of 1.5.1)
"autoRetryCount": 2, // present if this job was auto-retried from a failure (as of 2.3)
"autoRetryInterval": 0, // indicates auto-retry minimum interval in minutes (as of 2.5)
"autoRetryIntervalExponent": false, // indicates whether to exponentially increase the interval between auto retries (as of 2.5)
"job": {
"recoveryType": "NONE",
"pickupBufferMinutes": 2,
"jobId": 36,
"nickname": "testWithOutput",
"activeSchedule": {
"jobScheduleId": 37,
"schedule": "@hourly",
"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 (as of 2.0)
},
"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 (as of 2.1.1). 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>

==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, // as of 3.8.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>

''Available as of version 1.5.1.''

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>

= 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 (as of 2.3)
"end": "2013-11-01T23:59:00-0800", // the inclusive search to date (as of 2.3)
"runtimes": [
{
"jobId": 36,
"nickname": "jobOne",
"schedule": "* * * * *",
"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": "* * * * *",
"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 =

''As of Obsidian 2.4.''

==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": "* * * * *", // optional
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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": "* * * * *", // optional
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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==
''Available as of version 2.6.''

'''<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 =

''As of Obsidian 2.4.

==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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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. As of 2.9.0, 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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 (as of 2.3)
"maxExecutionDuration" : "10m" // only present when defined on job (as of 2.3)
"autoInterrupt" : false, //indicates if a job is auto interrupted when maxExecutionDuration is exceeded (as of 3.4)
"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 licence details on an existing scheduling host==
'''<code>PUT http(s)://localhost/rest/hosts/{id}/licence_health</code>'''        ''Prior to 4.5'': '''<code>PUT 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.

= Custom Calendar Endpoints =

''As of Obsidian 2.0. Format revised in 2.3.''

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>

''As of Obsidian 2.3.''

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==

''Available as of version 3.0.''

'''<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 =

''As of Obsidian 3.0.''

==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 =

''As of version 3.0.''

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 =

''As of Obsidian 3.0''

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 =

''As of Obsidian 3.0''

==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 =

''As of version 3.0.''

==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 =

''As of version 3.0.''

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.

= System Restore Endpoints =

''As of version 3.0.''

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. Since 3.8.0.
|-
| 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. Since 3.8.0.
|}

'''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": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.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": [ // as of 3.8.0, prior to 3.8.0, parameters child element was at this level
"ordinal": 0, //as of 3.8.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 - xisting 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>GET 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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/api/embedded/SystemRestoreManager.html#updateConfiguration(com.carfey.ops.api.bean.system.restore.SystemRestoreConfiguration,%20java.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).

Implementing Jobs

2018-05-22T21:17:49Z

Carfey: /* Threading in Jobs */

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 [[http://opensource.org/licenses/MIT MIT License]] as of Obsidian 2.7.0. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

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

= SchedulableJob Interface =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.html SchedulableJob Javadoc]

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

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. 

<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 [http://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 [http://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.

== Async Jobs ==

[http://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 [http://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={"http://google.com","http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/config/JobConfig.html Javadoc].

The following is the <code>@Parameter</code> source code (see [http://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(); // as of 3.7.0
public Type type() default Type.STRING;
public boolean allowMultiple() default false;
public String defaultValue() default "";
public Class<? extends ListProvider> listProvider() default StaticListProvider.class; // as of 3.3.0
String[] listArgs() default {}; // as of 3.3.0
public String description() default ""; // as of 4.0.2
}
</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.

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

== List Parameterization ==

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

<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 [http://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 [http://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 [http://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 ===

As of Obsidian 3.3.0, if you wish to define a parameter which enumerates a file listing based on a server-side directory, you can use the built-in [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider]. It also marked with the [http://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 [http://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.

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

== Global Parameters ==

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

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 ===

''Available as of Obsidian 3.4.0''

In some cases, you may wish to embed global parameters inside other parameters, rather than substitute them entirely. For example, when using a [[Built-in_Jobs#Script_Job|ScriptFileJob]], you may wish to inject a global parameter value into an argument passed into a script as follows:

<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 =

[http://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");

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

// As of 3.6, 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 [http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationStrategy.html SerializationStategy] and register it via the [http://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 [http://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 =

[http://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 =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableJob.html InterruptableJob Javadoc]

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

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

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

= Classpath Scanning =

Obsidian supports classpath scanning to find your jobs for display in the [[Admin_Jobs#Adding_.26_Editing_Jobs|job edit screen]].

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]]

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

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

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

= 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.

Implementing Jobs

2018-05-22T21:16:24Z

Carfey: /* SchedulableJob Interface */

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 [[http://opensource.org/licenses/MIT MIT License]] as of Obsidian 2.7.0. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

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

= SchedulableJob Interface =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.html SchedulableJob Javadoc]

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

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. 

<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 [http://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 [http://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.

== Async Jobs ==

[http://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, they 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 [http://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={"http://google.com","http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/config/JobConfig.html Javadoc].

The following is the <code>@Parameter</code> source code (see [http://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(); // as of 3.7.0
public Type type() default Type.STRING;
public boolean allowMultiple() default false;
public String defaultValue() default "";
public Class<? extends ListProvider> listProvider() default StaticListProvider.class; // as of 3.3.0
String[] listArgs() default {}; // as of 3.3.0
public String description() default ""; // as of 4.0.2
}
</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.

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

== List Parameterization ==

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

<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 [http://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 [http://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 [http://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 ===

As of Obsidian 3.3.0, if you wish to define a parameter which enumerates a file listing based on a server-side directory, you can use the built-in [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider]. It also marked with the [http://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 [http://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.

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

== Global Parameters ==

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

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 ===

''Available as of Obsidian 3.4.0''

In some cases, you may wish to embed global parameters inside other parameters, rather than substitute them entirely. For example, when using a [[Built-in_Jobs#Script_Job|ScriptFileJob]], you may wish to inject a global parameter value into an argument passed into a script as follows:

<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 =

[http://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");

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

// As of 3.6, 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 [http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationStrategy.html SerializationStategy] and register it via the [http://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 [http://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 =

[http://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 =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableJob.html InterruptableJob Javadoc]

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

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

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

= Classpath Scanning =

Obsidian supports classpath scanning to find your jobs for display in the [[Admin_Jobs#Adding_.26_Editing_Jobs|job edit screen]].

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]]

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

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

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

= 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

2018-03-19T16:50:55Z

Carfey:

This Getting Started is for Obsidian 4.0 and newer versions. See the [[Getting_Started_(3.x.x_and_earlier)|Previous Getting Started]] for prior 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 runs on Java 1.7 or above.
* Obsidian's administration web application is a servlet application tested on Tomcat 7 & 8 and Jetty 9.x, but is likely to work in any compliant servlet container version 2.4 or higher, such as WebSphere. It works on all modern browsers and is tested on recent versions of Chrome and Firefox.
* Obsidian requires one of the following fully-supported database platforms:
** MySQL 5.5 through 5.7 (excluding Galera)
** MariaDB 5.5
** Oracle 10g & 11.x
** PostgreSQL 9
** MS SQL Server 2008-2014
** 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 [http://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 (1.7 or up) 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-jetty-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 (1.7 or up) 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://msdn.microsoft.com/en-us/library/tcbchxcb(v=vs.110).aspx 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.

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. Key files and directories are shown below.

<pre>
├───db_scripts
└───Obsidian-4.5.0
│ com.carfey.properties.copy
│ obsidian.war
│ standaloneObsidian.bat
│ standaloneObsidian.sh
│ standaloneObsidianAdmin.war
│ webObsidian.bat
│ webObsidian.sh
│
├───jetty
├───license
├───logs
└───standalone
(various JAR files...)
obsidian-props.jar
obsidian.jar
</pre>
The installer creates a top-level directory named <code>Obsidian-''n''.''n''.''n''</code> containing generated artifacts. The key files and directories are:

* '''com.carfey.properties.copy''' - Copy of properties file generated by the installer.
* '''obsidian.war''' - Combined scheduler and admin web application WAR. This can be deployed directly to a servlet container. This artifact can be customized by adding your job code and dependencies as JARS to the <code>/WEB-INF/lib</code> directory within the archive.
* '''standaloneObsidian.bat''' and '''standaloneObsidian.sh''' - Windows and Linux scripts to start the standalone scheduler process with no web application. The standalone scheduler can be customized by adding your job code and dependencies as JARS to the <code>standalone</code> directory.
* '''webObsidian.bat''' and '''webObsidian.sh''' - .bat - Windows and Linux scripts to start either the standalone web application or combined scheduler and admin web application within the bundled Jetty server.
* '''standaloneObsidianAdmin.war''' - Standalone admin web application WAR (no scheduler). This can be deployed directly to a servlet container.
* '''standalone''' - Directory containing JARs that Obsidian requires to run the standalone scheduler process. The standalone scheduler can be customized by adding your job code and dependencies as JARS to this directory.
** '''obsidian-props.jar''' - JAR file containing the Obsidian properties file <code>com.carfey.properties</code>. If you wish to make configuration changes for the standalone scheduler, the properties file within this JAR will need to be updated.

= 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-props.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.properties.copy</code> from your installation with the <code>.copy</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_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.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 want to use the included Jetty server as your servlet container, you can use the 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 want to use the included Jetty server as your servlet container, you can use the 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 [[#Embed_Obsidian_.26_Customize_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.

Deployment Models

2018-03-19T16:49:04Z

Carfey: /* Clustered Scheduler with Separate Admin Web Application */

Obsidian supports multiple deployment setups as described in the [[Getting Started#Deployment|Getting Started guide]]. This can be as simple as a single node providing both scheduling and the web application, or as complicated as many scheduling nodes of different types participating in load-sharing and providing [[Recovery_%26_Failover|failover]] via a [[Clustering|cluster]].

= Purpose of Each Node 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 two services may be deployed in different types of deployments. They may be provided by a single application artifact, or they may be split apart, depending on your needs.

== Scheduler Node==

A scheduler node represents a scheduler process running within a Java virtual machine, which determines when jobs should run, and executes them. Scheduler nodes can participate in clustering for shared job execution, but do not need to communicate with each other directly. They need to communicate with the Obsidian database and the configured SMTP server (if applicable).

This node may be the standalone artifact that is included in your Obsidian installation, or it may be embedded within your application. If you use the standalone artifact, any job code and its dependent libraries need to be added to the artifact. Conversely, if you embed the scheduler inside your application, you will need to import Obsidian's required libraries and configuration file into your project.

Many of our customers embed a scheduler node inside their own application, so that it can execute your application code without requiring a separate customized Obsidian application. Generally, when you embed Obsidian in this way, you would deploy a separate uncustomized [[#Administration_Interface|Administration Interface]].

'''Related Terms:'''
* ''Scheduler'', ''scheduler process'' or ''scheduler host'' - all refer to the Obsidian process running within a JVM that provides Obsidian's job scheduling services.

== Administration Interface ==
The administration interface represents the Obsidian web application, which provides a management user interface, and the [[REST API]]. Like a scheduler node, it needs to communicate with the Obsidian database, and the configured SMTP server (if applicable), but there is no benefit to deploying more than one of the administration interface since it provides no clustering benefits.

Typically, when you embed the scheduler component, we recommend you run a vanilla administration interface as provided in your installation package, since it does need require access to your job execution code

'''Related Terms:'''
* ''Admin/administration webapp'', ''management UI'', ''management web application'', ''etc'' - all refer to the Obsidian interface web application, deployed to a servlet container.

= Combined Scheduler and Admin Interface =

The simplest deployment looks like the following. It demonstrates a single node running both the scheduler process and admin interface as a single application, which would be deployed to a servlet container. The logical SMTP server is optional.

[[File:SimpleDeploymentDiagram.png]]

= Clustered Scheduler with Separate Admin Web Application=

A more complex setup with clustered scheduling comprised of multiple node types is shown below. It demonstrates a cluster of 3 scheduler nodes, one of which also serves the admin webapp. Additionally, two more admin webapp hosts provide access to the web application user interface and REST API to a different area of the network.

[[File:DeploymentDiagram.png]]

Deployment Models

2018-03-19T16:20:04Z

Carfey: /* Clustered Scheduler with Deparate Admin Web Application */

Implementing Jobs

2018-03-16T20:45:59Z

Carfey: /* Classpath for Building and Deploying */

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 [[http://opensource.org/licenses/MIT MIT License]] as of Obsidian 2.7.0. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

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

= SchedulableJob Interface =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.html SchedulableJob Javadoc]

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

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. 

<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 [http://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 [http://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.

== Async Jobs ==

[http://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#Finalize_a_Pending_.28Async.29_Runtime|Embedded API]] is used to set the final results of the job.

= 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 [http://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={"http://google.com","http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/config/JobConfig.html Javadoc].

The following is the <code>@Parameter</code> source code (see [http://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(); // as of 3.7.0
public Type type() default Type.STRING;
public boolean allowMultiple() default false;
public String defaultValue() default "";
public Class<? extends ListProvider> listProvider() default StaticListProvider.class; // as of 3.3.0
String[] listArgs() default {}; // as of 3.3.0
public String description() default ""; // as of 4.0.2
}
</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.

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

== List Parameterization ==

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

<pre>
@Configuration(knownParameters={
@Parameter(name="logLevel", required=true, type=Type.STRING, listArgs={"ERROR", "INFO", "DEBUG"})
})
</pre>

=== Custom Dynamic Lists ===

For more complex scenarios, you may wish to enumerate values dynamically. This can be done by creating your own implementation of the [http://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 [http://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 File Lists ===

As of Obsidian 3.3.0, if you wish to define a parameter which enumerates a file listing based on a server-side directory, you can use the built-in [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider].

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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html Javadoc] for full usage details.

=== Dynamic List Providers ===

''As of Obsidian 4.5.0'', a <code>ListProvider</code> can be marked as providing dynamic, or changing values, using the [http://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.

== 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.

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

== Global Parameters ==

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

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 ===

''Available as of Obsidian 3.4.0''

In some cases, you may wish to embed global parameters inside other parameters, rather than substitute them entirely. For example, when using a [[Built-in_Jobs#Script_Job|ScriptFileJob]], you may wish to inject a global parameter value into an argument passed into a script as follows:

<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 =

[http://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");

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

// As of 3.6, 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 [http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationStrategy.html SerializationStategy] and register it via the [http://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 [http://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 =

[http://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 =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableJob.html InterruptableJob Javadoc]

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

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

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

= Classpath Scanning =

Obsidian supports classpath scanning to find your jobs for display in the [[Admin_Jobs#Adding_.26_Editing_Jobs|job edit screen]].

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]]

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

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

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

= 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.

Implementing Jobs

2018-03-16T20:42:39Z

Carfey: /* Classpath for Building and Deploying */

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 [[http://opensource.org/licenses/MIT MIT License]] as of Obsidian 2.7.0. In the root of the installation folder, you can find the source in <code>obsidian-builtin-job-src.jar</code>.

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

= SchedulableJob Interface =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/SchedulableJob.html SchedulableJob Javadoc]

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

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. 

<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 [http://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 [http://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.

== Async Jobs ==

[http://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#Finalize_a_Pending_.28Async.29_Runtime|Embedded API]] is used to set the final results of the job.

= 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 [http://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={"http://google.com","http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/config/JobConfig.html Javadoc].

The following is the <code>@Parameter</code> source code (see [http://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(); // as of 3.7.0
public Type type() default Type.STRING;
public boolean allowMultiple() default false;
public String defaultValue() default "";
public Class<? extends ListProvider> listProvider() default StaticListProvider.class; // as of 3.3.0
String[] listArgs() default {}; // as of 3.3.0
public String description() default ""; // as of 4.0.2
}
</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.

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

== List Parameterization ==

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

<pre>
@Configuration(knownParameters={
@Parameter(name="logLevel", required=true, type=Type.STRING, listArgs={"ERROR", "INFO", "DEBUG"})
})
</pre>

=== Custom Dynamic Lists ===

For more complex scenarios, you may wish to enumerate values dynamically. This can be done by creating your own implementation of the [http://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 [http://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 File Lists ===

As of Obsidian 3.3.0, if you wish to define a parameter which enumerates a file listing based on a server-side directory, you can use the built-in [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html FileListProvider].

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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/param/FileListProvider.html Javadoc] for full usage details.

=== Dynamic List Providers ===

''As of Obsidian 4.5.0'', a <code>ListProvider</code> can be marked as providing dynamic, or changing values, using the [http://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.

== 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.

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

== Global Parameters ==

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

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 ===

''Available as of Obsidian 3.4.0''

In some cases, you may wish to embed global parameters inside other parameters, rather than substitute them entirely. For example, when using a [[Built-in_Jobs#Script_Job|ScriptFileJob]], you may wish to inject a global parameter value into an argument passed into a script as follows:

<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 =

[http://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");

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

// As of 3.6, 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 [http://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 [http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/result/SerializationStrategy.html SerializationStategy] and register it via the [http://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 [http://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 =

[http://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 =

[http://obsidianscheduler.com/obsidianapi/com/carfey/ops/job/InterruptableJob.html InterruptableJob Javadoc]

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

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

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 [http://docs.oracle.com/javase/tutorial/essential/concurrency/interrupt.html tutorial] explains the details of thread interrupts.

= Classpath for Building and Deploying =

To implement jobs in Java, you will need to reference Obsidian base classes in your Java project.

To deploy and run jobs in Obsidian, your built code and any 3rd party libraries it requires must be included in the Obsidian classpath. If you're running the scheduler '''within a servlet container''' (e.g. Tomcat), JARs should be placed under <code>/WEB-INF/lib</code>. This could be a plain installation of Obsidian, or a web app which contains both your application and Obsidian. If you are running the '''standalone scheduler''', you'll need to place your JARS under the <code>/standalone</code> directory. Otherwise, if you are running an '''embedded Obsidian''' instance, you'd need to ensure the jobs are available in the classpath in one form or another.

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. To be able to configure jobs in your standalone web application, your Obsidian instances which run jobs will need to have been started at least once after your latest classpath changes, and after configuring [[Implementing_Jobs#Classpath_Scanning|classpath scanning]]. This is because scheduler instances store job metadata in the Obsidian database so the admin web application can properly validate jobs.

The base libraries to build Java jobs are found in the zip file you downloaded under the <code>/standalone</code> directory:

* <code>obsidian.jar</code>

These libraries should not conflict with your existing build classpath since they are internal Obsidian libraries.

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.).

'''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.

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

= Classpath Scanning =

Obsidian supports classpath scanning to find your jobs for display in the [[Admin_Jobs#Adding_.26_Editing_Jobs|job edit screen]].

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]]

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

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

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

= 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.

Deployment Models

2018-03-16T17:36:22Z

Carfey: /* Purpose of Each Node Type */

Obsidian supports multiple deployment setups as described in the [[Getting Started#Deployment|Getting Started guide]]. This can be as simple as a single node providing both scheduling and the web application, or as complicated as many scheduling nodes of different types participating in load-sharing and providing [[Recovery_%26_Failover|failover]] via a [[Clustering|cluster]].

= Purpose of Each Node 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 two services may be deployed in different types of deployments. They may be provided by a single application artifact, or they may be split apart, depending on your needs.

== Scheduler Node==

A scheduler node represents a scheduler process running within a Java virtual machine, which determines when jobs should run, and executes them. Scheduler nodes can participate in clustering for shared job execution, but do not need to communicate with each other directly. They need to communicate with the Obsidian database and the configured SMTP server (if applicable).

This node may be the standalone artifact that is included in your Obsidian installation, or it may be embedded within your application. If you use the standalone artifact, any job code and its dependent libraries need to be added to the artifact. Conversely, if you embed the scheduler inside your application, you will need to import Obsidian's required libraries and configuration file into your project.

Many of our customers embed a scheduler node inside their own application, so that it can execute your application code without requiring a separate customized Obsidian application. Generally, when you embed Obsidian in this way, you would deploy a separate uncustomized [[#Administration_Interface|Administration Interface]].

'''Related Terms:'''
* ''Scheduler'', ''scheduler process'' or ''scheduler host'' - all refer to the Obsidian process running within a JVM that provides Obsidian's job scheduling services.

== Administration Interface ==
The administration interface represents the Obsidian web application, which provides a management user interface, and the [[REST API]]. Like a scheduler node, it needs to communicate with the Obsidian database, and the configured SMTP server (if applicable), but there is no benefit to deploying more than one of the administration interface since it provides no clustering benefits.

Typically, when you embed the scheduler component, we recommend you run a vanilla administration interface as provided in your installation package, since it does need require access to your job execution code

'''Related Terms:'''
* ''Admin/administration webapp'', ''management UI'', ''management web application'', ''etc'' - all refer to the Obsidian interface web application, deployed to a servlet container.

= Combined Scheduler and Admin Interface =

The simplest deployment looks like the following. It demonstrates a single node running both the scheduler process and admin interface as a single application, which would be deployed to a servlet container. The logical SMTP server is optional.

[[File:SimpleDeploymentDiagram.png]]

= Clustered Scheduler with Deparate Admin Web Application=

A more complex setup with clustered scheduling comprised of multiple node types is shown below. It demonstrates a cluster of 3 scheduler nodes, one of which also serves the admin webapp. Additionally, two more admin webapp hosts provide access to the web application user interface and REST API.

[[File:DeploymentDiagram.png]]