OS4X Enterprise job archive restore

Requirements

If you have an archive system which is capable to inform OS4X that an OS4X Enterprise job is archived, you can update the database of OS4X. After the information is available that the job is archived, the administrative web interface offers a restore functionality. The ID of the archiving must be numerical.

Your job restore mechanism must support JSONP requests. There are several ways to achieve this, please consult your archiving provider how to implement such a functionality.

If you want to use single-sign on for this web request, the domain of the OS4X administrative web interface must be the same as the JSONP service URL, example:

• OS4X Administrative interface: https://os4x.mydomain.tld/os4x
• JSONP restore service URL: https://archive-server.mydomain.tld/service/url

This functionality was introduces with OS4X release 2017-08-22.

Task to be done when archiving a job

You have to update the job record in OS4X's database:

• Table: [tableprefix_]jobs, default: os4x_jobs
• Column: archive_id

The default of the value for this column is NULL, so if you want to reset the archive value, please update it to NULL value.

Configuring job restore

In the OS4X's administrative web interface, navigate to "Configuration" -> "OS4X Enterprise" -> "Basic". In the section "Job restore mechanism" there exist some parameters to be defined:

• Absolute AJAX URL for job restore processes: This is the absolute URL of the service call.
• Name of parameter for restore AJAX call: the parameter name of the archive ID must be configured here
• (optional) Name of JSONP callback parameter: the callback function name parameter

Due to the nature of JSONP, your service must be able to interpret the "callback" parameter and reply with a valid JSON answer, encapsulated by the callback function name. Example:

• Service URL call: http://192.168.20.60/archiving/restoreJob?inArchiveJobId=4711&callback=Ext.my.callbackfn123
• Expected answer:

Ext.my.callbackfn123({ whatever: true })

Hint: If you need additional parameters for the request, just append them seperated in URL encoded entities as GET parameters to the service URL. The archive restore service call will identify this situation and will append the own parameters according to the rules for GET parameters dynamically! Example service URL with additional parameters:

http://192.168.20.60/archiving/restoreJob?myParameter=myValue&mySecondParameter=this%20is%20a%20test

Using job restore

In the job detail view, a button exists for job restoring. As long as the value "archive_id" of the database table "os4x_jobs" has a non-NULL value (where the numeric value of "0" is also interpreted as NULL) the button is enabled. When pressing this button, the JSONP request is executed with the actual configuration and the restore process can be executed asynchronously.

Debugging

When something goes wrong, it can have several reasons. The most common are:

• Unauthorized service access: verify that the service call can be executed from the web browser location you are using. When dealing with single-sign-on environments, the service call will typically answer with an HTTP 401 (unauthorized) answer, so the webbrowser can answer back again with an authorized request automatically.
• Wrong server answer: the JSONP request must be answered by encapsulating the JSON answer in the callback function. The callback function name is dynamic. Only JSON is supported as content payload, XML is not supported by this mechanism. More information about JSONP is available at Wikipedia.
• Untrusted script source: the web server of the JSONP service may disallow your request. Be aware that your administrative web interface is starting the request, not the OS4X server!
• JSONP requests are always HTTP(S) GET requests. No POST, PUT, OPTIONS etc. are allowed.
• The local webbrowser's Javascript and network console is the best way to start debugging why requests may fail.