Create TomCat plugin procedures

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.