5 Modifying Workflows Using Custom Hooks
Modify the existing ZDT Patching workflow in Oracle WebLogic Server by adding custom logic specific to your business at predefined points called extension points.
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 rollouts.
The ZDT custom hooks feature identifies certain points in a patching workflow where additional commands can be run 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.
Table 5-1 lists the available extension points for workflows along with their descriptions and use cases.
Table 5-1 Extension Points Available for Workflows
Name | Description | 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. |
|
ep_EachNode |
Use this extension point when the workflow needs to perform any additional operation across 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. |
|
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. |
|
ep_OnlineAfterServerStart |
Use this extension point to perform any custom operation after the update has completed on each node and the server has restarted. |
Perform server and application-level administrative tasks, such as:
|
ep_OnlineAfterUpdate |
Use this extension point to perform any additional operation after the servers have restarted, and the application is continuing servicing requests. |
|
ep_RolloutSuccess |
Use this extension point to define any custom logic, such as sending notifications, after the patching is successful. |
|
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 run 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 run either on the remote node or on the local node. Table 5-2 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 run or revert operations in scripts |
Offline |
currentNodeName |
The full name of the node currently being updated. This variable is not applicable to the |
Online |
currentServerNames |
A comma-separated list of names of servers on the targeted node. This variable is not applicable 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, |
Online |
Parent topic: Modifying Workflows Using Custom Hooks
The Patching Workflow Process for Custom Hooks
You can customize operations in the workflow that is run either on the Administration server node or on a remote node.
When the workflow process reaches a user hook, the user specified extension at that extension point is run. 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 running 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 run locally is also written to the Administration Server log file. This includes error output or non-error output.
Figure 5-1 illustrates the typical scenarios for workflows, and how they include different extension points.
Figure 5-1 Patching Workflow with Extension Points
This figure shows the extension points available in a typical workflow for updating Oracle home or Java home.

Description of "Figure 5-1 Patching Workflow with Extension Points"
Parent topic: Modifying Workflows Using Custom Hooks
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
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 run at that extension point.
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 run in the order in which they appear in the extensionConfiguration.json
file. Each JAR file should contain only one extensionConfiguration.json
file. Figure 5-2 shows the structure of an extension JAR file.
During the rollout, the scripts are extracted in the patching
directory under DOMAIN_HOME/bin
.
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¶m2=val2,http://localhost:7006/context2?param1=val1¶m2=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.
Parent topic: Modifying Workflows Using Custom Hooks