SnapCenter Software 5 Manuals ( CA08871-403 )
PERL-based development
You must follow certain conventions while developing the plug-in using PERL.
-
Contents must be readable
-
Must implement mandatory operations setENV, quiesce, and unquiesce
-
Must use a specific syntax to pass results back to the agent
-
The contents should be saved as <PLUGIN_NAME>.pm file
Available operations are
-
setENV
-
version
-
quiesce
-
unquiesce
-
clone_pre, clone_post
-
restore_pre, restore
-
cleanup
General plug-in handling
Using results object
Every custom plug-in operation must define the results object. This object sends messages, exit code, stdout, and stderr back to the host agent.
Results object:
my $result = {
exit_code => 0,
stdout => "",
stderr => "",
};
Returning the results object:
return $result;
Preserving data consistency
It is possible to preserve data between operations (except cleanup) as part of same workflow execution. This is done using key-value pairs. The key-value pairs of data are set as part of result object and are retained and available in the subsequent operations of same workflow.
The following code sample sets the data to be preserved:
my $result = {
exit_code => 0,
stdout => "",
stderr => "",
};
$result->{env}->{‘key1’} = ‘value1’;
$result->{env}->{‘key2’} = ‘value2’;
….
return $result
The above code sets two key-value pairs, which are available as input in the subsequent operation. The two key-value pairs are accessible using the following code:
sub setENV {
my ($self, $config) = @_;
my $first_value = $config->{‘key1’};
my $second_value = $config->{‘key2’};
…
}
Logging error messages
Each operation can send messages back to the host agent, which displays and stores the content. A message contains the message level, a timestamp, and a message text. Multiline messages are supported.
Load the SnapCreator::Event Class: my $msgObj = new SnapCreator::Event(); my @message_a = ();
Use the msgObj to capture a message by using the collect method.
$msgObj->collect(\@message_a, INFO, "My INFO Message"); $msgObj->collect(\@message_a, WARN, "My WARN Message"); $msgObj->collect(\@message_a, ERROR, "My ERROR Message"); $msgObj->collect(\@message_a, DEBUG, "My DEBUG Message"); $msgObj->collect(\@message_a, TRACE, "My TRACE Message");
Apply messages to the results object:
$result->{message} = \@message_a;
Using plug-in stubs
Custom plug-ins must expose plug-in stubs. These are methods that the SnapCenter Server calls, based on a workflow.
| Plug-in Stub | Optional/Required | Purpose | ||
|---|---|---|---|---|
setENV |
required |
This stub sets the environment and the configuration object. Any environment parsing or handling should be done here. Each time a stub is called, the setENV stub is called just before. It is only required for PERL-style plug-ins. |
||
Version |
Optional |
This stub is used to get application version. |
||
Discover |
Optional |
This stub is used to discover application objects like instance or database hosted on the agent or host. The plug-in is expected to return discovered application objects in specific format as part of the response. This stub is only used in case the application is integrated with SnapDrive for Unix.
|
||
discovery_complete |
Optional |
This stub is used to discover application objects like instance or database hosted on the agent or host. The plug-in is expected to return discovered application objects in specific format as part of the response. This stub is only used in case the application is integrated with SnapDrive for Unix.
|
||
Quiesce |
required |
This stub is responsible for performing a quiesce, which means placing application into a state where you can create a Snapshot copy. This is called before Snapshot copy operation. The metadata of application to be retained should be set as part of response, which shall be returned during subsequent clone or restore operations on corresponding storage Snapshot copy in the form of configuration parameters. |
||
Unquiesce |
required |
This stub is responsible for performing a unquiesce, which means placing application into a normal state. This is called after you create a Snapshot copy. |
||
clone_pre |
optional |
This stub is responsible for performing preclone tasks. This assumes you are using the built-in SnapCenter Server cloning interface and is triggered when performing clone operation. |
||
clone_post |
optional |
This stub is responsible for performing post clone tasks. This assumes you are using the built-in SnapCenter Server cloning interface and is triggered only when performing clone operation. |
||
restore_pre |
optional |
This stub is responsible for performing prerestore tasks. This assumes you are using the built-in SnapCenter Server restore interface and is triggered while performing restore operation. |
||
Restore |
optional |
This stub is responsible for performing application restore tasks. This assumes you are using the built-in SnapCenter Server restore interface and is only triggered when performing restore operation. |
||
Cleanup |
optional |
This stub is responsible for performing cleanup after backup, restore, or clone operations. Cleanup can be during normal workflow execution or in the event of a workflow failure. You can infer the workflow name under which cleanup is called by referring to configuration parameter ACTION, which can be backup, cloneVolAndLun, or fileOrVolRestore. The configuration parameter ERROR_MESSAGE indicates if there was any error while executing the workflow. If ERROR_MESSAGE is defined and NOT NULL, then cleanup is called during workflow failure execution. |
||
app_version |
Optional |
This stub is used by SnapCenter to get application version detail managed by the plug-in. |
Plug-in package information
Every plug-in must have following information:
package MOCK; our @ISA = qw(SnapCreator::Mod); =head1 NAME MOCK - class which represents a MOCK module. =cut =head1 DESCRIPTION MOCK implements methods which only log requests. =cut use strict; use warnings; use diagnostics; use SnapCreator::Util::Generic qw ( trim isEmpty ); use SnapCreator::Util::OS qw ( isWindows isUnix getUid createTmpFile ); use SnapCreator::Event qw ( INFO ERROR WARN DEBUG COMMENT ASUP CMD DUMP ); my $msgObj = new SnapCreator::Event(); my %config_h = ();
Operations
You can code various operations like setENV, Version, Quiesce, and Unquiesce, which are supported by the custom plug-ins.
setENV operation
The setENV operation is required for plug-ins created using PERL. You can set the ENV and can easily access plug-in parameters.
sub setENV {
my ($self, $obj) = @_;
%config_h = %{$obj};
my $result = {
exit_code => 0,
stdout => "",
stderr => "",
};
return $result;
}
Version operation
The version operation returns the application version information.
sub version {
my $version_result = {
major => 1,
minor => 2,
patch => 1,
build => 0
};
my @message_a = ();
$msgObj->collect(\@message_a, INFO, "VOLUMES
$config_h{'VOLUMES'}");
$msgObj->collect(\@message_a, INFO,
"$config_h{'APP_NAME'}::quiesce");
$version_result->{message} = \@message_a;
return $version_result;
}
Quiesce operations
Quiesce operation performs application quiesce operation on resources listed in the RESOURCES parameter.
sub quiesce {
my $result = {
exit_code => 0,
stdout => "",
stderr => "",
};
my @message_a = ();
$msgObj->collect(\@message_a, INFO, "VOLUMES
$config_h{'VOLUMES'}");
$msgObj->collect(\@message_a, INFO,
"$config_h{'APP_NAME'}::quiesce");
$result->{message} = \@message_a;
return $result;
}
Unquiesce operation
Unquiesce operation is required to unquiesce the application. The list of resources is available in the RESOURCES parameter.
sub unquiesce {
my $result = {
exit_code => 0,
stdout => "",
stderr => "",
};
my @message_a = ();
$msgObj->collect(\@message_a, INFO, "VOLUMES
$config_h{'VOLUMES'}");
$msgObj->collect(\@message_a, INFO,
"$config_h{'APP_NAME'}::unquiesce");
$result->{message} = \@message_a;
return $result;
}
