This documentation supports an earlier version of BMC Helix IT Service Management on-premises deployment.

To view the documentation for the latest version, select 23.3.01 from the Product version picker.

Deploying custom plug-ins

Review the information in this topic to understand the steps that an administrator performs to deploy custom plug-ins after a fresh installation of BMC Helix Service Management.


The following diagram shows the overview of the process of deploying custom plug-ins:

Before you begin

Task 1: Prepare the plug-in files and create a custom plug-in image

Prepare the plug-ins files by performing the following steps and then create a custom plug-in image by using the Plug-in server base image from BMC Docker Trusted Registry (DTR).

  1. On the Jenkins server or a LINUX machine that has Docker Engine - Community  20.10.17 or later installed, create a working directory named customplugin.
    Use this directory to organize the files required to create a custom plugin.
  2. Navigate to the customplugin directory, and create a sub directory named image.

  3. Navigate to the image directory, and create a new file named Dockerfile by using a text editor.

  4. In the Dockerfile file, add the following details:

    # Dockerfile to create an image for a custom plug-in server.
    FROM <registry_server>/bmc/lp00x:pluginsvr_base-213006-RC1A-213006-RC2
    ADD --chown=bmcuser:bmc --chmod=g+rw pluginsvr /opt/bmc/ARSystem/pluginsvr

    In the <registry_server> parameter, specify the name of the registry server from where you have synced the plug-in server base image from containers.bmc.com.
    This file is used to prepare the Docker image of custom plug-in.

    Important

    The --chmod option requires BuildKit. To learn how to build images with BuildKit enabled, see  Build images with BuildKit Open link in the Docker documentation.


  5. Navigate to the image directory and create a sub directory named pluginsvr.
  6. Navigate to the pluginsvr directory.
  7. In the pluginsvr directory, copy all the custom plug-in jar files and the supporting files.
  8. In the pluginsvr directory, create a new pluginsvr_config.xml file and add the following details to the file:

    <?xml version="1.0" encoding="UTF-8" standalone="no"?>
    <pluginsvr_config>
    <port>__CUSTPLUGINPORT__</port>
    <regPortMapper>false</regPortMapper>
    <encryptionPolicy>2</encryptionPolicy>
    <publicKeyAlg>4</publicKeyAlg>
    <publicKeyExpiry>86400</publicKeyExpiry>
    <dataEncryptionAlg>1</dataEncryptionAlg>
    <dataKeyExpiry>2700</dataKeyExpiry>
    <numCoreThreads>5</numCoreThreads>
    <numSelectorThreads>2</numSelectorThreads>
    <workQueueMonitorLogInterval>0</workQueueMonitorLogInterval>
    <workQueueTaskThreshold>5</workQueueTaskThreshold>
    <pluginSvrName> PluginServer_Service___ARSERVERCONNECTNAME_____CUSTPLUGINPORT__ </pluginSvrName>
    <reloadDelay>30000</reloadDelay>
    <enableNativeBridge>false</enableNativeBridge>
    <maxThreads>10</maxThreads>
    <excessCoreThreadsIdleKeepAliveTimeInSecond>0</excessCoreThreadsIdleKeepAliveTimeInSecond>
    <supportNativePluginHost>false</supportNativePluginHost>
    <loadNativePluginHost>false</loadNativePluginHost>
    <pluginSvrLogEnable>True</pluginSvrLogEnable>
    <pluginSvrLogFile>/opt/bmc/ARSystem/db/__CUSTOMPLUGINNAME___arjavaplugin___CUSTPLUGINPORT__.log</pluginSvrLogFile>
    <pluginSvrLogLevel>INFO</pluginSvrLogLevel>
    <pluginSvrLogMaxFileSize>5242880</pluginSvrLogMaxFileSize>
    <pluginSvrLogMaxHistory>10</pluginSvrLogMaxHistory>
    <pluginSvrAlwaysOnLogName> /opt/bmc/ARSystem/db/__CUSTOMPLUGINNAME_____CUSTPLUGINPORT___alwayson.log </pluginSvrAlwaysOnLogName>
    <pluginSvrAlwaysOnCopies>20</pluginSvrAlwaysOnCopies>
    <pluginSvrAlwaysOnBufferSize>0</pluginSvrAlwaysOnBufferSize>
    <plugins>
    </plugins>
    </pluginsvr_config>

    This file is used to add the custom plug-in configuration information.

  9. To add the custom plug-in information, in the pluginsvr_config.xml file, enter a plug-in configuration block for your plug-in by using the <plugins> and </plugins> tags as shown in the following template:

    </plugins>
    	<plugin>
         <name><Name of your custom plugin></name>
             <classname>Name of the plugin class</classname>
                 <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/JAR file 1</pathelement>
                 <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/JAR file 2</pathelement>
                 <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/JAR file n</pathelement>				
                 <userDefined>
                         <KeepResultsSeconds>Keep result value in seconds</KeepResultsSeconds>
                         <KeepCacheSeconds>Keep cache value in seconds</KeepCacheSeconds>
                         <Timeout>Timeout value in seconds</Timeout>
                         <AlwaysLogDetails></AlwaysLogDetails>
                         <ProxyServer></ProxyServer>
                         <ProxyPort></ProxyPort>
                         <ProxyUser></ProxyUser>
                         <ProxyPass></ProxyPass>
                         <KeyStoreAlgorithm></KeyStoreAlgorithm>
                         <KeyStoreFormat></KeyStoreFormat>
                         <KeyStoreFile></KeyStoreFile>
                         <KeyStorePass></KeyStorePass>
                         <KeyStoreProtocol></KeyStoreProtocol>
                         <TemplateFieldDelimiter></TemplateFieldDelimiter>
                         <ArrayDelimiter></ArrayDelimiter>
                 </userDefined>
    	</plugin>
    </plugins>

    In the <pathelement type="location"> parameter, /opt/bmc/ARSystem/pluginsvr/ is the path of the platform container directory.

    The following block shows an example plug-in configuration:

    </plugins>
    	<plugin>
         <name>APL.ARDBC.RESTFULARDBCPLUGIN</name>
             <classname>com.apl.RestfulARDBCPlugin</classname>
                 <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/APLRestfulARDBCPlugin.jar</pathelement>
                 <pathelement type="location">/opt/bmc/ARSystem/pluginsvr/json-20200518.jar</pathelement>
                 <userDefined>
                         <KeepResultsSeconds>300</KeepResultsSeconds>
                         <KeepCacheSeconds>86400</KeepCacheSeconds>
                         <Timeout>90</Timeout>
                         <AlwaysLogDetails></AlwaysLogDetails>
                         <ProxyServer></ProxyServer>
                         <ProxyPort></ProxyPort>
                         <ProxyUser></ProxyUser>
                         <ProxyPass></ProxyPass>
                         <KeyStoreAlgorithm></KeyStoreAlgorithm>
                         <KeyStoreFormat></KeyStoreFormat>
                         <KeyStoreFile></KeyStoreFile>
                         <KeyStorePass></KeyStorePass>
                         <KeyStoreProtocol></KeyStoreProtocol>
                         <TemplateFieldDelimiter></TemplateFieldDelimiter>
                         <ArrayDelimiter></ArrayDelimiter>
                 </userDefined>
    	</plugin>
    </plugins>


    Important

    Make sure that you do not change any other sections in the file.

Task 2: To build the plug-in image

  1. Navigate to the image directory and build the plug-in image by using the following command:

    DOCKER_BUILDKIT=1 docker build -t <plugin_image_name> .

    For example:

    DOCKER_BUILDKIT=1 docker build -t my_custom_pluginserver .

    After the image is built, use the following command to verify that the new image is available:

    docker image ls
  2. Add a new tag to the image and push it to the registry server that is used to share images to the Kubernetes cluster. 

Task 3: To create a Helm chart for the plug-in server image

  1. Navigate to your working directory customplugin and download and extract the pluginservice.zip file.

  2. In the values.yaml file, add the following parameter values:

    Parameter nameDescription
    registryName of the registry server where the custom plug-in server image is saved.
    pluginimageName of your custom plug-in.
    pluginimagetagTag of the image pushed to the registry server.
    AR_SERVER_DOMAINName of your domain.
    CUSTOM_PLUGINSVR_NAMEName of your custom plug-in server.

    (Optional)

    CUSTOM_PLUGINSVR_PORT

    Custom plug-in port value.

    The default value is 9822.

    JAVA_MAX_HEAP_SIZEMaximum memory size for JVM.
    JAVA_MIN_HEAP_SIZEMinimum memory size for JVM.

    name

    in the imagePullSecrets section

    The IMAGESECRET_NAME parameter value from the HELIX_ONPREM_DEPLOYMENT pipeline that is used to deploy BMC Helix Service Management.
    Alternatively, you can use the following command to find the value:

    kubectl get secret -n <BMC Helix Innovation Suite namespace> --field-selector type=kubernetes.io/dockerconfigjson


    AR_SERVER_APP_SERVICE_PASSWORD

    The AR_SERVER_APP_SERVICE_PASSWORD parameter value from the HELIX_ONPREM_DEPLOYMENT pipeline used to deploy BMC Helix Service Management.

    Alternatively, you can use the following command to find the value:

    kubectl get secret platform-fts -n <helix_itsm_namespace> -o=jsonpath='{.data.AR_SERVER_APP_SERVICE_PASSWORD}' | base64 -d

    Important

    In the env section, add the environment variables required for your custom plug-in.

  3. If you are using Openshift with restricted SCC enabled, navigate to the deployment.yaml file located at pluginservice/templates/, and update the file as follows:
    1. In the deployment.yaml file, in the securityContext section, delete the runAsUser: 1000 and fsGroup: 1000 parameters.
    2. Add the runAsGroup: 1000 parameter as shown in the following image:

Task 4: To deploy the custom plug-in

  1. In your BMC Helix Innovation Suite namespace, deploy the plug-in server container by using the following command:

    helm --namespace=<BMC Helix Innovation Suite namespace> upgrade --install <plugin_server_name> . -f values.yaml

    For example:

    helm --namespace=itsm123 upgrade --install customplugin . -f values.yaml
  2. Verify that the custom plug-in server is running by using the following command:

    kubectl get pods -n <BMC Helix Innovation Suite namespace>
  3. To view the Helm deployments, run the following command:

    helm ls -n <BMC Helix Innovation Suite namespace>
  4. Log in to Mid Tier and confirm that the deployed plug-ins are registered in the Plugin Server Configuration form.
    For more information, see  Form Permissions plug-in configuration Open link in AR System documentation.


Where to go from here

Next taskProceed with Moving your customization to a new target system
Back to process

If you are finished moving your customization to a new target system, return to the Staged upgrade process.

Was this page helpful? Yes No Submitting... Thank you

Comments