Modifying Workflows Using Custom Hooks

About Extension Points

Extension points are placeholders in the ZDT Patching workflow where you can insert custom logic. ZDT Patching provides extension points and predefined environment variables for multitenant (deprecated) and non-multitenant rollouts.

The ZDT custom hooks feature identifies certain points in a patching workflow where additional commands can be executed to customize its behavior. These points are referred to as extension points. You can customize the behavior of a workflow by inserting collections of resources, called extensions, at each predefined extension point.

customhooks.html#GUID-0D2A78A9-5611-4192-A888-04104A45E897__GUID-5812AB42-224F-410A-B75D-50E490F83D53 lists the available extension points for multitenant and non-multitenant environments, along with their descriptions and use cases.

Table 5-1 Extension Points Available for Multitenant and Non-Multitenant Workflows

Name	Description	Available when executing extensions in a non-multitenant workflow	Available when executing extensions in the multitenant workflow	Use Cases
ep_OnlineBeforeUpdate	Use this extension point at the initial stage of the workflow before the patching operation starts on each node. This is typically the point where prerequisite checks can be performed.	Yes	Yes	Pre-upgrade quiesce to disable or pause external domains that are fed into the cluster. Run any SQL script that may be needed to prepare for an application update.
ep_EachNode	Use this extension point when the workflow needs to perform any additional operation across each node.	Yes	Yes	Add checks to ensure that there is enough disk space on all the nodes for the rollout of Oracle home. Ensure that any new shared file system artifacts are accessible on each node.
ep_OfflineBeforeUpdate	Use this extension point at the stage of the workflow when all servers are shut down, just before the Oracle home or Java home update starts.	Yes	Yes	Back up files or directories.
ep_OfflineAfterUpdate	Use this extension point to perform any custom operation after Oracle home or Java home have been patched and before the servers start.	Yes	No	Validate the versions of software components included in the rollout. Modify any Java properties in the Java home.
ep_OnlineAfterServerStart	Use this extension point to perform any custom operation after the update has completed on each node and the server has restarted.	Yes	No	Perform server and application-level administrative tasks, such as: Check JDBC, JTA or JMS subsystem. Deploy or redeploy any additional application at this point. Directing administrative requests to applications to ensure that the applications behave as expected.
ep_OnlineAfterUpdate	Use this extension point to perform any additional operation after the servers have restarted, and the application is continuing servicing requests.	Yes	Yes	Perform any basic checks to ensure that affected applications are functional and accessible.
ep_RolloutSuccess	Use this extension point to define any custom logic, such as sending notifications, after the patching is successful.	Yes	Yes	Send out an e-mail to the administrator to notify the status of the upgrade.

This feature also provides certain predefined environment variables that can be passed at the extension points. Some predefined environment variables are available for use with online extension points, while others can be used with offline extension points. Online extension points can be executed when the server is running, whereas offline extension points are available for use when the server is shut down. Both offline and online extension points can be executed either on the remote node or on the local node. customhooks.html#GUID-0D2A78A9-5611-4192-A888-04104A45E897__GUID-E9812DB2-AF43-4A1D-89D6-B789908C2343 provides a list of all the environment variables that are available for use with online and offline extension points.

Table 5-2 Predefined Environment Variables for Extension Points

Variable Name	Description	Available for Use with Offline or Online Extension points
javaHome	The location of the existing Java home	Offline
newJavaHome	The location of the new Java home to use	Offline
mwHome	The location of the Middleware home	Offline
domainDir	The location of the domain directory	Offline
domainTmp	The location of the directory under the domain home where temporary files may be stored	Offline
patched	The location of patched Oracle home	Offline
backupDir	The location where the existing Oracle home will be moved	Offline
isRevert	Controls execute or revert operations in scripts	Offline
currentNodeName	The full name of the node currently being updated. This variable is not applicable to the `ep_OnlineBeforUpdate` or `ep_RolloutSuccess` extension points.	Online
currentServerNames	A comma-separated list of names of servers on the targeted node. This variable is not applicable to `ep_OnlineBeforeUpdate` or `ep_RolloutSuccess` extension points.	Online
partitionName	A partition name to which the rollout is targeted to	Online
applicationInfo	The application name, application location, and application backup, separated by commas for each application. Separate multiple applications by colon: `<appName>,<appLoc>,<appBackUp>:<appName2>,<appLoc2>,<appBackUp2>` For example, `"scrabble,/pathTo/scrabblev2,/pathTo/scrabbleV1Backup:cart,/pathTo/cartV3,/pathTo/cartV2Backup`	Online

The Patching Workflow Process for Custom Hooks

You can customize operations in the workflow that is executed either on the Administration server node or on a remote node. The custom hooks feature is available in both the non-multitenant environment, and the multitenant environment of WebLogic Server. In a multitenant environment, you can introduce extensions while you roll out application updates to partitions and during a rolling restart of partitions. However, note that a partition administrator might not have access to the Administration Server file system. Therefore, as a partition administrator, you can use the partition file system directory to store extension jar files. You can use the partition file system directory to upload and manage partition-specific resources. customhooks.html#GUID-8F81FA21-B987-44D6-AE09-07631174D2EB__GUID-339AFF0B-495D-4A52-9040-3CAF84B4F91B and customhooks.html#GUID-8F81FA21-B987-44D6-AE09-07631174D2EB__GUID-0027F5DE-D80F-4206-A03F-77A86FECC32A illustrate the typical scenarios for non-multitenant and multitenant workflows, and how they include different extension points.

When the workflow process reaches a user hook, the user specified extension at that extension point is executed. Any script that exits with a code of zero is considered to have completed successfully, whereas a script that returns a non-zero exit code is considered failed. If no errors occur, the processing resumes. If an error occurs during the execution of an extension, then the workflow is rolled back to its previous state. Note that the scripts do not have in-built retry or resume methods. A script is attempted once, and if it fails, the workflow does not retry it. Therefore, if your script performs an operation that needs to be retried, then you must write the retry logic in the script.

During the workflow, the output generated by offline scripts to STDOUT or STDERR is propagated to the Administration Server log file. Similarly, output generated by a script that is executed locally is also written to the Administration Server log file. This includes error output or non-error output.

Figure 5-1 Patching Workflow with Extension Points in Non-Multitenant Rollouts

This figure shows the extension points available in a typical non-multitenant workflow for updating the Oracle home or Java home.

Description of "Figure 5-1 Patching Workflow with Extension Points in Non-Multitenant Rollouts"

Figure 5-2 Patching Workflow with Extension Points in Multitenant Rollouts (Deprecated)

This figure shows the extension points available in a multitenant workflow for updating applications or rolling restart of partitions.

Description of "Figure 5-2 Patching Workflow with Extension Points in Multitenant Rollouts (Deprecated)"

Specifying Extensions to Modify the Workflow

The custom hooks feature provides several ways to introduce extensions in the workflow. You can specify the extensions in either of the two JSON files, extensionConfiguration.json or extensionProperties.json, or pass them directly as options in the rollout commands. Regardless of how you pass the extension parameters, these parameters ultimately map to script parameters that are translated into environment variables.

This flexibility lets you override or customize parameters at different levels. When you use more than one way of specifying extension parameters, then the following is the order in which script parameters are overridden:

Extension parameters specified in the extensionConfiguration.json file.
Extension parameters specified in the extension properties JSON file to override the parameters set in the extensionConfiguration.json file.
Extension parameters specified as options in the WLST rollout commands to override the parameters specified in the two JSON files. You can use the same extension JAR in different environments by customizing only the options in the rollout commands for each workflow.

The following sections provide more information about using these methods to specify extensions.

Creating a JSON Configuration File

The extensionConfiguration.json file is a JSON format file that contains an array of extension definitions. Each extension definition must specify the following:

The name of the predefined extension point where the extension is inserted in the workflow.
The fully qualified name of the class file to execute at that extension point.

Optionally, any additional parameters used by the extension. The additional extension parameters must be declared in the JSON format. The specified class file can use one of the standard extensions supplied by WebLogic Server. The following sample extensionConfiguration.json file shows how to define extensions.

{"extensions":[
{
"extensionPoint":"ep_OnlineBeforeUpdate",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"checkJar.sh","jarPath":"/tmp/extension.jar"}
},
{
"extensionPoint":"ep_EachNode",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"checkDiskSpace.sh"}
},
{
"extensionPoint":"ep_OnlineAfterUpdate",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"checkApps.sh","appUrls":"http://localhost:8004/Coke/Simple_stage/handle,http://localhost:8006/Coke/Simple_stage/handle"}
},
{
"extensionPoint":"ep_RolloutSuccess",
"extensionClass":"weblogic.management.patching.extensions.ScriptExecutorExtension",
"extensionParameters":{"scriptName":"emailSuccess.sh"}
}
]}

After you create the extensionConfiguration.json file, you must place it along with other related native scripts in a JAR file, such as, sampleExtension.jar. The JAR file that you create must have a directory structure that adheres to Oracle standards. If more than one extension is specified at a single extension point, then the extensions are executed in the order in which they appear in the extensionConfiguration.json file. Each JAR file should contain only one extensionConfiguration.json file. customhooks.html#GUID-04D475B0-DAF4-4140-A417-26F54B55048B__GUID-71C5F3FE-EC0F-44EB-BD26-E968ED106BDE shows the structure of an extension JAR file.

During the rollout, the scripts are extracted in the patching directory under DOMAIN_HOME/bin.

Figure 5-3 Extension Jar File Structure

Description of "Figure 5-3 Extension Jar File Structure"

Creating a JSON Properties File

Alternatively, you can specify the extension information in another JSON file, such as, extensionProperties.json file. You can use this file when you need to pass multiple extensions in a workflow and when these extensions are placed in multiple JAR files. Note that the JSON properties file is different from the extensionConfiguration.json file; the extensionConfiguration.json file is specific to the scripts within its own JAR file, whereas the JSON properties file gives you a convenient way to include multiple extension JAR files in the workflow. Each JSON properties file includes the path to one or more JAR files that contain the extension configuration information and optionally includes any additional parameters.

The following snippet shows the format of a sample extensionProperties.json file.

{"extensionProperties":[
{
"extensionJar":"/pathTo/extension.jar",
"extensionParameters":{"scriptName":"updateProperties.sh", "appURL":"http://localhost:7005/context?param1=val1&param2=val2,http://localhost:7006/context2?param1=val1&param2=val2"}
}
]}

Including Options in the WLST Rollout Commands

You can pass extension parameters in either of the two JSON files or pass them directly to the WLST rollout commands using the extension or extensionProperties options. For more information about how to use these options to specify extension parameters, see the arguments for WLST rollout commands in Using WLST to Initiate and Monitor Workflows.

Note:

When you create JSON files to include your extensions and place them in extensions jars, be sure to meet the following conditions:

Place extension jars on all remote nodes before the rollout.
Specify the path to the extension jar that contains the extension parameters to roll out. The same path must exist on all nodes.
On a Windows system, avoid using the backslash character when you specify the paths in the JSON file.
Do not include commas in the values of the script parameters in the JSON files.