4 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.

Note:

WebLogic Server Multitenant domain partitions, resource groups, resource group templates, virtual targets, and Resource Consumption Management are deprecated in WebLogic Server 12.2.1.4.0 and will be removed in the next release.

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.

Table 4-1 lists the available extension points for multitenant and non-multitenant environments, along with their descriptions and use cases.

Table 4-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. Table 4-2 provides a list of all the environment variables that are available for use with online and offline extension points.

Table 4-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. Figure 4-1 and Figure 4-2 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 4-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 4-1 follows
Description of "Figure 4-1 Patching Workflow with Extension Points in Non-Multitenant Rollouts"

Figure 4-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 4-2 follows
Description of "Figure 4-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. Figure 4-3 shows the structure of an extension JAR file.

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

Figure 4-3 Extension Jar File Structure

Description of Figure 4-3 follows
Description of "Figure 4-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.