Create TomCat plugin procedures

12 minute readExtensibilityDeveloper productivity

Plugin procedures can be used in procedure steps, process steps, and pipeline tasks, allowing you to orchestrate third-party tools at the appropriate time in your component, application process, or pipeline.

Depending on your plugin configuration and how you run procedures, the Input parameters  Configuration name field may behave differently in the CloudBees CD/RO UI. For more information, refer to Differences in plugin UI behavior.

AddDatasource

Adds a datasource resource declaration into the Tomcat context.

Input parameters

Table 1. AddDatasource input parameters
Parameter Description

Context configuration path

Required. The absolute path of the context.xml file, including the filename and extension. For example, $CATALINA_BASE/conf/context.xml or /opt/tomcat/conf/context.xml.

Datasource name

Required. The name of the datasource. For example, jdbc/MyTest.

URL

Required. The connection URL to pass to the JDBC driver. For example, jdbc:mysql://hostname:3306/databaseName.

Maximum active connections

Required. The maximum number of connections that can be allocated from this pool at the same time. The default is 8.

Maximum idle connections

Required. The maximum number of connections that can sit idle in this pool at the same time. The default is 8.

Maximum wait for connections

Required. When no connections are available, this is the maximum number of milliseconds the pool waits for a connection to be returned before returning an error. The default is -1 (infinite).

Minimum wait for connections

The minimum number of connections that sit idle in this pool at the same time.

Additional attributes

Enter additional attributes for the resource, using the format: attributeName=\"value\";attributeName2=\"value2", where a semicolon (;) is used to separate the attributes. Note the quotation marks ("") around the values must be present.

Driver class name

Required. The fully qualified Java class name of the JDBC driver to use. For example, com.mysql.jdbc.Driver.

Datasource credential

Specify the credential that contains the username and password for the datasource.

CheckPageStatus

Checks the status of a page on a given URL.

Input parameters

Table 2. CheckPageStatus input parameters
Parameter Description

Credentials

The credentials to be entered.

Maximum elapsed time

Defines the maximum time, in seconds, the job tries to check into the server (a maximum of 180 seconds). If this field is left empty, no wait time is used (zero seconds).

Success criteria

Required. Indicates the status of the page that must be matched, with either a Page found or a Page not found status. If the Success criteria matches the returned status at the end of the analysis, it is considered a success. Otherwise, it is an error in the job.

Page URL

Required. The URL of the page to be checked. For example, http://localhost/examples/jsp/index.html.

CheckServerStatus

Checks the status of the specified server URL.

Input parameters

Table 3. CheckServerStatus input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Maximum elapsed time

Defines the maximum time, in seconds, the job attempts to check into the server. If left empty, no wait time is used and the URL is only checked once.

Success criteria

Required. Indicates the status of the page that must be matched, with either a Page found or a Page not found status. If the Success criteria matches the returned status at the end of the analysis, it is considered a success. Otherwise, it is an error in the job.

CreateOrUpdateJMSConnectionFactory

Adds a new JMS Connection Factory or updates an existing Connection Factory based on the update action with support for different JMS providers.

Input parameters

Table 4. CreateOrUpdateJMSConnectionFactory input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Virtual hostname

Required. The hostname of the Tomcat server or the virtual host to deploy the application.

Request URL context path

Required. The URL context path where Tomcat serves the application.

JNDI name

Required. The name used to look up the resource in JNDI.

Provider

Required. Select a provider for the JMS resources.

ActiveMQ broker URL

The URI is assumed to be a composite URI with multiple URIs used to bind the connectors of the broker. This parameter is required if the selected provider is Apache ActiveMQ.

ActiveMQ broker name

Broker name. This parameter is required if the selected provider is Apache ActiveMQ.

WebsphereMQ connection factory type

Type of resource that is controlled by WebsphereMQ connection factory. This parameter is required if the selected provider is IBM WebSphereMQ.

WebsphereMQ server hostname

Network hostname where the Websphere MQ provider is located. This parameter is required if the selected provider is IBM WebSphereMQ.

WebsphereMQ server port

TCP Port (1 - 65535) on the server where the Websphere MQ provider is located. This parameter is required if the selected provider is IBM WebSphereMQ.

WebsphereMQ channel

Name for a channel on WebsphereMQ. This parameter is required if the selected provider is IBM WebSphereMQ.

WebsphereMQ queue manager

Name of a queue manager on WebsphereMQ. This parameter is required if the selected provider is IBM WebSphereMQ.

Custom connection factory class

Fully qualified name of the Java class to use. For example, org.apache.activemq.ActiveMQConnectionFactory. This parameter is required if the selected provider is Custom.

Custom connection factory class

Fully qualified name of the Factory Java class to use. For example, org.apache.activemq.JNDIRefferenceFactory. The parameter is required if the selected provider is Custom.

Custom connection factory attributes

Enter additional attributes for the resource, using the format: attributeName="value";attributeName2="value2", where a semicolon (;) is used to separate the attributes. Note the quotation marks ("") around the values must be present.

Description

Description for this connection factory.

Update action

Required. Specify the update action to take when a resource element with the same JNDI name exists:

  • Do nothing

  • Remove and recreate

CreateOrUpdateJMSQueue

Adds a new JMS queue or updates an existing JMS queue based on the update action, with support for different JMS providers.

Input parameters

Table 5. CreateOrUpdateJMSQueue input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Virtual hostname

Required. The hostname of the Tomcat server or the virtual host to deploy the application.

Request URL context path

Required. The URL context path where Tomcat serves the application.

JNDI name

Required. The name used to look up the resource in JNDI.

Provider

Required. Select the provider for the JMS resources.

Custom JMS queue class

Fully qualified name of the Java class to use. For example, org.apache.activemq.ActiveMQQueue.

Custom JMS queue factory class

Fully qualified name of the Factory Java class to use. For example, org.apache.activemq.ActiveMQConnectionFactory.

Custom JMS queue attributes

Enter additional attributes for the resource, using the format: attributeName="value";attributeName2="value2", where a semicolon (;) is used to separate the attributes. Note the quotation marks ("") around the values must be present.

Description

Description for this JMS Queue.

Update action

Required. Specify the update action to take when a resource element with the same JNDI name exists:

  • Do nothing

  • Remove and recreate

CreateOrUpdateJMSTopic

Adds a new JMS Topic or updates an existing JMS Topic based on the update action, with support for different JMS providers.

Input parameters

Table 6. CreateOrUpdateJMSTopic input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Virtual hostname

Required. The hostname of the Tomcat server or the virtual host to deploy the application.

Request URL context path

Required. The URL context path where Tomcat serves the application.

JNDI name

Required. Name used to look up the resource in JNDI.

Provider

Required. Select the provider for the JMS Resources:

  • Apache ActiveMQ

  • IBM WebSphereMQ

  • Custom

Custom JMS topic class

Fully qualified name of the Java class to use. For example, org.apache.activemq.ActiveMQTopic.

Custom JMS topic factory class

Fully qualified name of the Factory Java class to use. For example, org.apache.activemq.JNDIReferenceFactory.

Custom JMS topic attributes

Enter additional attributes for the resource, using the format: attributeName="value";attributeName2="value2", where a semicolon (;) is used to separate the attributes. Note the quotation marks ("") around the values must be present.

Description

Description for this JMS topic.

Update action

Required. Specify the update action to take when a resource element with the same JNDI name exists:

  • Do nothing

  • Remove and recreate

CreateOrUpdateMailSession

Adds a new JMS Mail Session or updates an existing JMS Mail Session based on the update action.

Input parameters

Table 7. CreateOrUpdateMailSession input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Virtual hostname

Required. The hostname of the Tomcat server or the virtual host to deploy the application.

Request URL context path

Required. The URL context path where Tomcat serves the application.

JNDI name

Required. The JNDI name for this mail session. It should be unique for context.

SMTP host

Required. The server that provides SMTP service for your network.

Description

Description for this mail session resource element.

Update action

Required. Specify the update action to take when a resource element with the same JNDI name exists:

  • Do nothing

  • Remove and recreate

DeleteResource

Removes any of these resources - Connection Factory, JMS Queue, JMS Topic, or Mail Session.

Input parameters

Table 8. DeleteResource input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Virtual hostname

Required. The hostname of the Tomcat server or the virtual host to deploy the application.

Request URL context path

Required. The URL context path where Tomcat serves the application.

JNDI name

Required. The JNDI name of the resource delete.

DeployApp

Deploys an application into the Tomcat server.

Input parameters

Table 9. DeployApp input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Context configuration path

The context configuration file path.

Context path

Required. The context path to use. The context path is the name after the slash, by which your application is accessible.

Update application

Select if the existing application in the supplied context path must be overridden.

WAR file/exploded directory path

The path to the WAR file or exploded directory to upload to the server. If this parameter is left empty, the plugin looks into the appBase directory of Tomcat for the WAR file that matches the context path provided to make the deployment. Acceptable formats:

  • File: Use the prefix file: and the absolute path of the WAR file or directory. For example, file:/absolute/path/to/a/directory or 'file:/tmp/app_wars/webapp.war'.

  • Jar: Use the prefix jar: and the URL to a local WAR file. You can use any syntax that is valid for the JarURLConnection class for reference to an entire JAR file.

  • No prefix: If no prefix is entered, the Tomcat manager looks in the host application base directory for either a WAR file or a directory, relative to the specified path.

  • No prefix and remote deploy: If no prefix is entered and Remote Deployment is selected, the Tomcat manager looks into the WAR path entered for the WAR file.

DeployApplication

Deploys an application into the Tomcat server using context files.

Input parameters

Table 10. DeployApplication input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Application WAR file location

Required. The absolute path of the web application WAR file to deploy. For example, /var/downloads/hello.war.

Request URL context path

Required. The URL context path where Tomcat serves the application. For example, if Tomcat serves the application at http://host:port/ws, this value would be /ws. If Tomcat serves the application at http://host:port/abc/ws, this value would be /abc/ws.

Virtual hostname

The hostname of the Tomcat server or the virtual host to deploy. If this field is left empty, the application is deployed to the Tomcat default host (localhost). A warning is returned if the provided name is not defined in the conf/server.xml file.

Host application directory location

The pathname of a directory where web applications for this host are located (Tomcat refers to this directory as the appBase folder). If this field is left empty, it is read from the corresponding host (specified by the hostname) appBase attribute in the conf/server.xml file. A warning is returned if the directory does not exist. The procedure also fails if it cannot retrieve the value either from input or the conf/server.xml file.

Web application context element

The full XML content for the <Context> element of the context descriptor. If no value is provided, the default value is formed dynamically according to values specified for the Application WAR file location and Request URL context path. For example:

<?xml version="1.0" encoding="UTF-8"?> <Context docBase="hello.war" path="/hello" unpackWAR="true"> </Context>
  • The docBase is the path where the deployed application WAR file resides, relative to the host’s appBase: /path/to/hello.war.

  • The path is the same as the Request URL context path: /hello.

For more information about possible attributes, refer to the Tomcat documentation.

Update action

Specify if Tomcat should override and deploy over an existing deployment.

  • No action: If the WAR file already exists, do not overwrite it.

  • Remove and recreate: If the WAR file exists, overwrite it, and redeploy.

Server restart options

Specifies if the server should be restarted.

  • Restart unconditionally: The server is restarted even if the previous steps were successful. Also, if the there is a deployment failure after the restart, no action is taken.

  • Do not restart: The server is not restarted. This is a use case where server restarts happen as part of a deferred schedule or the host autoDeploy attribute is set to true.

  • Stop Restarted Server upon failure: The server is restarted. However, the server is stopped if the deployment fails.

DeployConfigurationFile

Deploys a specified configuration file to an appropriate destination in the Tomcat server.

Input parameters

Table 11. DeployConfigurationFile input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Destination filepath

Required. The absolute path where the configuration XML file is copied to.

Local filepath

The absolute path where the configuration XML file is copied from.

Configuration file content

XML content for the configuration file to deploy. If Local filepath is specified, it is ignored.

Overwrite

Required. Specify the overwrite action taken if the file already exists in the destination:

  • Update

  • Always

  • No

DeployLibraryFile

Deploys a specified library file to an appropriate destination in the Tomcat server.

Input parameters

Table 12. DeployLibraryFile input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Destination filepath

Required. The absolute path where the deployed library file generates after a procedure run.

Local filepath

Required. The absolute path to a local file to deploy.

Overwrite

Required. Specify the overwrite action to take if the file already exists in the destination.

ReloadApp

Reloads an application of the Tomcat server.

Input parameters

Table 13. ReloadApp input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Context path

Required. The context path to use. The context path is the name after the slash, by which your application is accessible.

RemoveDatasource

Removes a datasource resource declaration from the Tomcat context.

Input parameters

Table 14. RemoveDatasource input parameters
Parameter Description

Context configuration path

Required. The absolute path of the context.xml file, including the filename and extension. For example, $CATALINA_BASE/conf/context.xml or /opt/tomcat/conf/context.xml.

Datasource name

Required. The name of the datasource. For example, jdbc/MyTest.

RunTomcatManager

Runs the Tomcat Manager in a free mode.

Input parameters

Table 15. RunTomcatManager input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Command:

Required. The command passed to the Tomcat Manager. For example, start, stop, or run.

Parameters:

Required. Provide additional parameters received by the Tomcat Manager. Enter as URL parameters. For example, path=/jpetstore&war=file:/tmp/app_wars/jpetstore.war

ShutdownServer

Shuts down the Tomcat server.

Input parameters

Table 16. ShutdownServer input parameters
Parameter Description

Catalina path

The absolute path to Catalina home to locate the catalina.sh file that is required to start or stop the application servers. For example, /opt/tomcat/.

Shutdown script path

Required. The absolute path to the shutdown server script, including the filename and extension. For example, /opt/tomcat/bin/shutdown.sh.

StartApp

Starts an application on the Tomcat server.

Input parameters

Table 17. StartApp input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Context path

Required. The context path to use. The context path is the name after the slash, by which your application is accessible.

Health check timeout

The health check timeout. Defines the maximum time, in seconds, the job tries to check the application.

StartServer

Starts the Tomcat server.

Input parameters

Table 18. StartServer input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Catalina path

The absolute path to Catalina’s home to locate the catalina.sh file required to start or stop the application servers. For example, /opt/tomcat/.

Startup script path

Required. The absolute path to the startup server script, including the filename and extension. For example, /opt/tomcat/bin/startup.sh.

Health check timeout

The health check timeout. Defines the maximum time, in seconds, the job tries to check the server.

StopApp

Stops an application into the Tomcat server.

Input parameters

Table 19. StopApp input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Context path

Required. The context path to use. The context path is the name after the slash, by which your application is accessible.

UndeployApp

Undeploys an application from the Tomcat server.

Input parameters

Table 20. UndeployApp input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Context path

Required. The context path to use. The context path is the name after the slash, by which your application is accessible.

UndeployApplication

Undeploys an application from the Tomcat server, removing deployment files and the context file.

Input parameters

Table 21. UndeployApplication input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Request URL context path

Required. The URL context path where Tomcat serves the application. For example, if Tomcat should serve the application at http://host:port/ws, this value should be /ws. If Tomcat should serve the application at http://host:port/abc/ws, this value should be /abc/ws.

Host application directory location

The pathname of a directory where web applications for this host are located (Tomcat refers to this directory as the appBase folder). If this field is left empty, it is read from the corresponding host (specified by the hostname) appBase attribute in the conf/server.xml file. A warning is returned if the directory does not exist. The procedure also fails if it cannot retrieve the value either from input or the conf/server.xml file.

Virtual hostname

The hostname of the Tomcat server or the virtual host to deploy. If this field is left empty, the application is deployed to the Tomcat default host (localhost). A warning is returned if the provided name is not defined in the conf/server.xml file.

Specific deployment files

A comma-separated list of absolute paths to remove during undeployment operation. If specified, the procedure removes the context XML file with the specified Request URL context path and any given file paths. If left empty, the procedure reads the docBase attribute from the context XML file with the specified Request URL context path, and if a WAR file, checks for the extracted folder and removes both.

Server restart options

Specifies if the server should be restarted.

  • Restart unconditionally: The server is restarted even if the previous steps were successful. Also, if the there is a deployment failure after the restart, no action is taken.

  • Do not restart: The server is not restarted. This is a use case where server restarts happen as part of a deferred schedule or the host autoDeploy attribute is set to true.

  • Stop Restarted Server upon failure: The server is restarted. However, the server is stopped if the deployment fails.

UndeployFile

Removes a specified library or configuration file from the Tomcat server.

Input parameters

Table 22. UndeployFile input parameters
Parameter Description

Configuration name

Required. The previously defined configuration for the plugin.

Destination filepath

Required. The absolute path to the library file to delete.