To integrate your backup plugin with OnApp, you need to provide the following files:
- A plugin.rb file where you define a name of your backup plugin.
- A separate file for each hook that is required to be used in integration with OnApp. You also pass models with metadata objects to hooks in these files.
- A helper file with code that you can include into any hook-specific file.
In this document, you can find the examples of the required files with the descriptions and inline comments.
Before You Begin
Before you proceed to working with files, please note that:
- Every call of a hook is idempotent.
- Every hook returns a Backups::Plugin::Response instance that is built using the 'success' and 'error' helpers. If none of the helpers were used, the successful response is returned implicitly.
- The plugins and helpers have access to the backup resource attributes that are primary_host, secondary_host, username and password.
- The plugins and helpers possess logging capabilities, i.e. errors with 'logger.error("Error message goes here")'.
- The plugins and helpers have access to configuration via 'config'.
- The plugins and helpers have access to configuration parameters via 'config.advanced_options' that is a hash, where key is a name of an option and value is a value of an option set for this resource in OnApp.
- The plugins and helpers have access to OnApp version via ‘onapp_version’.
- The plugins and helpers which are performed in a transaction can write to transaction log via user_facing_logger.log(“Something”).
You can use polling in the hook-specific and helper files to run a periodic check on results of specific operations. The following code snippet is an example of a polled operation that you can use in a hook-specific or helper file.
You can simplify polling operations with the help of STATUSES. See the task_helper.rb file for an example.
Create Plugin File
The plugin.rb is a main file where you define a name of your backup plugin. Below you can find an example of plugin.rb with inline comments that help to understand the requirements to the file.
Create Hook-Specific Files
There is a set of hooks that you can implement for your backup plugin depending on its configuration. Each hook requires a separate file with a name that corresponds to a particular event triggered by a hook. Every hook should contain a method 'call' with the corresponding arguments.
Below you can find the examples of hook-specific files with inline comments that help to understand the structure of the files and their essential components:
OnApp Backup Plugin System supports only UNIX file separators for both UNIX-like operating systems and Windows. It is up to a plugin to convert one type of a file separator into another.
Create Helper Files
The helper files or helpers contain code that you can include into any hook-specific file. The usage of helpers allows you to apply the Don’t Repeat Yourself (DRY) principle to your backup plugin. The helper files reside in the helpers directory of a backup plugin.
Below you can find the examples of helpers with inline comments that help to understand the structure of the files and their essential components: