Initializing and Restoring

As of Obsidian 3.0.0

At times, you may wish to perform initialization, backup or restoration of an Obsidian configuration. For example, you may wish to take a known good configuration from a development environment and apply it to a test environment.

In Obsidian 3.0.0, we introduce support that leverages the System Restore functionality of our API. The Obsidian (Embedded API or and REST API) both expose individual functions for retrieving and updating the entire breadth of an Obsidian configuration. Rather than require you to individually retrieve all the configuration items and then apply them elsewhere, we now introduce a system wide snapshot of an entire Obsidian installation combined with JSON formatted file-based initialization allowing for easy backups and restores.

Note: Users do not include the current passwords since they cannot be determined, and also as a security measure. All users will be returned with the password "changeme".

Uses

Backup or Export

Simply use the System Restore GET REST endpoint or the SystemRestoreManager.getConfiguration() Embedded API to retrieve a SystemRestoreConfiguration. Store the JSON representation in your backup media.

Transfer or Restore a Configuration

Follow the Backup instructions. Using the JSON, you can either place it on the file-system as describe in Startup Initialization, or use it in conjunction with the System Restore PUT REST endpoint or the SystemRestoreManager.updateConfiguration() Embedded API.

You may choose to update parts of the exported configuration depending on your needs, or to set new user passwords.

Startup Initialization

By default, Obsidian will look for a file on the classpath named /obsidianInitialization.json containing configuration data in the format described in JSON Configuration Format.

You may override the classpath resource name using the system property obsidianInitClasspath. For example, you could add the java system property -DobsidianInitClasspath=/com/mycompany/obsidianInit.json. You can also use a file-based resource by using the system property obsidianInitFile. For example, you could add the java system property -DobsidianInitFile=/var/obsidian-3.0.0/obsidianScheduleInitialization.json.

Note: Initialization only runs on scheduler instances. This means that a standalone Obsidian web application with no scheduler running will not do any initialization based on the presence of the appropriate JSON file.

JSON Configuration Format

The file format is a JSON serialized version of the SystemRestoreConfiguration class. Here we will define each configuration item and any special conditions associated with each one. A sample JSON is provided.

Jobs

The jobs key has a list of JobSaveRequest objects. Each of these represents a configured job in Obsidian. This JobSaveRequest is very much like a JobCreationRequest but having two extra attributes to handle the case where the Job already exists. The updateAttributes flag is used to determine whether the job attributes (jobClass, recoveryType, pickupBufferMinutes, etc.) will be updated when the job exists. The updateSchedule flag is used to determine whether to apply the current schedule and any additional jobSchedules when the job already exists. If any of the schedules' effective dates or end dates are in the past, they will be skipped.

Chains

The chains key is a ChainsRequest that houses a collection of chain configurations and a replaceAll attribute. The replaceAll attribute is used when chains already exist in the system. If chains exist and the flag is not set to true, the existing chains are left as is. If set to true, all existing chains are deleted and the new set of chains are created.

Conflicts

The conflicts key is similar to the ConflictUpdateRequest but it uses job nicknames instead of jobIds.

Users

The users key has a list of UserSaveRequest objects. These are similar to the standard UserCreationRequest, but they contain an update attribute that is used when the user already exists. If the same user name exists and the flag is not set to true, the user is left as is. Otherwise, the user is created or updated as the case dictates.

Global Parameters

The globalParameters key is a list of GlobalParameter objects that are to be set into the system. Any current global parameters are either deleted or overridden.

Custom Calendars

The customCalendars key is a list of CustomCalendarUpdateRequest objects. Creates or updates as the case dictates by matching on the name.

System Parameters

The systemParameters key is a list of SystemParameter objects. Updates all parameters given.

Subscribers

The subscribers key is a list of SubscriberSaveRequest objects. Creates or updates as the case dictates by matching on the email address.

Templates

The templates key is a list of TemplateSaveRequest objects. Creates or updates as the case dictates by matching on the name.

Sample

{
   "jobs" : [
      {
        "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
        "nickname": "Daily Debug Log Cleanup",
        "recoveryType": "NONE",
        "state": "ENABLED",
        "schedule": "@daily",
        "parameters": [
            {
              "name": "level",
              "type": "STRING",
              "value": "DEBUG"
            },
            {
              "name": "maxAgeDays",
              "type": "INTEGER",
              "value": "7"
            }
        ],
        jobSchedules: [
           {
            "state": "DISABLED",
            "effectiveDate": "2020-01-01T00:00:00",
            "endDate": "2020-01-01T23:59:00"
         }
        ]
      },
      {
        "jobClass": "com.carfey.ops.job.maint.LogCleanupJob",
        "nickname": "Weekly Info Log Cleanup",
        "recoveryType": "NONE",
        "state": "ENABLED",
        "schedule": "@weekly",
        "parameters": [
            {
              "name": "level",
              "type": "STRING",
              "value": "INFO"
            },
            {
              "name": "maxAgeDays",
              "type": "INTEGER",
              "value": "30"
            }
        ]
      }
   ],
   "users" : [
      {
         "userName": "admin",
         "active": true,
         "roles": ["ADMIN","API"],
         "password": "changeme",
         "update": false
      }
   ],
   "chains" : {
      "replaceAll": true,
      "items" : [
         {
            "sourceJobNickname": "Daily Debug Log Cleanup",
            "targetJobNickname": "Weekly Info Log Cleanup",
            "triggerStates": ["FAILED"]
         },
         {
            "sourceJobNickname": "Daily Debug Log Cleanup",
            "targetJobNickname": "Weekly Info Log Cleanup",
            "schedule": "0 * * * *",
            "triggerStates": ["ABANDONED"]
         },
         {
            "sourceJobNickname": "Daily Debug Log Cleanup",
            "targetJobNickname": "Weekly Info Log Cleanup",
            "schedule": "5 * * * *",
            "triggerStates": ["DIED"]
         }
        ]
   },
   "conflicts": [
      ["Daily Debug Log Cleanup", "Weekly Info Log Cleanup"]
   ],
   "globalParameters": [
      { 
         "name": "forceSSL",
         "type": "BOOLEAN",
         "values": ["false"]
      },
      { 
         "name": "hostNames",
         "type": "STRING",
         "values": ["example.com", "test.com"]
      }
   ],
   "customCalendars": [
      {
         "name": "Special 2050 dates",
         "dates": ["2050-01-01","2050-03-03"]
      }
   ],
   "systemParameters": [
      {
         "name": "jvmJobForkingEnabled",
         "value": "true"
      },
      {
         "name": "maxRecords",
         "value": "2500"
      }
   ],
   "templates": [
      {
         "name": "Daily Debug Job template",
         "active": true,
         "category": "JOB",
         "defaultForJobs": false,
         "jobNicknames": ["Daily Debug Log Cleanup"],
         "subjectTemplate": "subject1",
         "bodyTemplate": "body template"
      }
   ],
   "subscribers": [
      {
         "emailAddress": "[email protected]",
         "active": true,
         "subscriptions": [
            {
               "jobNickname": "Daily Debug Log Cleanup",
               "category": "JOB",
               "level": "INFO",
               "active": true
            }
         ],
         "jobSubscriptions": [
            {
               "jobNicknames": ["Daily Debug Log Cleanup"],
               "allJobs": false,
               "triggerStates": ["FAILED","CONDITIONAL"],
               "resultConditions": [
                  {
                     "variableName": "someVar",
                     "operator": "IN",
                     "values": ["abc","123"]
                  }
               ],
               "active": true
            }
         ]
      }
   ]
}