Integrating Remedy applications with BMC Digital Workplace Catalog using plugins

Functionality enabled through Remedy application integration

The following table shows a few examples of the features that require this integration.

Integration process overview

The following diagram illustrates the process for integrating Remedy applications with BMC Digital Workplace Catalog so that end users can request services.

An administrator runs the integration script on each AR System server that hosts a unique Remedy application. The integration script installs the required objects and populates the database entries that support the integration. Next, the administrator must create records through the configuration forms to define the relationship between the Remedy application and the BMC Digital Workplace Catalog server. For Remedy applications deployed in a server group, run the integration on the primary server only. Then, duplicate the ARSystemInstallDir/pluginsvr/remoteaction folder, and the pluginsvr_config.xml and ar.cfg files to each of the secondary servers. 

The catalog administrator configures a connection that uses the Remedy connector to connect to the Remedy application server. If applications run on different servers, the catalog administrator must create and configure a connection for each server, and must also set the default connection for ITSM functionality.  After completing the integration, the catalog administrator creates services that use the connection, and end users request the services.

To prepare for integration

1. Download the BETA Remedy-plugin-integration-patch-for-DWP-Catalog Version 20.02.00 file from BMC Electronic Product Distribution (EPD). 
   For more information, see Downloading-the-BMC-Digital-Workplace-Catalog-installation-files.

2. Obtain the credentials to administer the AR System server.
3. For each application to be integrated, enable the AR System Object List on the server.
   For instructions, see "To enable and use the AR System Object List" in Setting-up-a-Remedy-Mid-Tier-for-system-administration-of-the-BMC-Digital-Workplace-Catalog-server.
4. (Optional) To inspect the objects that the integration script creates, configure BMC Remedy Developer Studio with access to the AR System server.
   For instructions, see Starting and logging on to Remedy Developer Studio.

To run the Remedy application integration script

1. Copy the Remedy-intg-plugin-DWPC-20.02.00-BETA.zip file to the AR System server, and extract the files into a temporary folder.
2. Open a command-line or terminal window.

3. Ensure that the JAVA_HOME environment variable is set.

   Windows

   > echo %JAVA_HOME%

   Linux

   # echo $JAVA_HOME

   If the JAVA_HOME environment variable is not set, set it.

   Windows

   > set JAVA_HOME="C:\Program Files\Java\latest"

   Linux

   # export JAVA_HOME=/usr/java/latest

4. Run the script for the server operating system.

   Windows

   > install.bat
   
   Enter AR System install directory :C:\Program Files\BMC Software\ARSystem
   Enter AR System admin user :Demo
   Enter AR System Password :password
   Enter ITSM hostname :bmc-itsm-sample
   Enter port number [zero if no port] : 0

   Linux

   # sh ./install.sh
   
   Enter AR System install directory :/opt/bmc/ARSystem
   Enter AR System admin user :Demo
   Enter AR System Password :password
   Enter ITSM hostname :bmc-itsm-sample
   Enter port number [zero if no port] :0

   Important

   The Linux script packaged in the zip archive is not executable. To run the script, perform one of the following tasks:

   • Invoke the sh command-line interpreter to run ./install.sh.
   • Issue the command chmod +x install.sh to make the script executable.

   The script copies the required files and installs the forms, filters, and escalations.

To verify that the installation is complete

After you run the integration script the first time, you might want to inspect the files, forms, filters, and escalations that were loaded onto the server. You do not have to verify the creation of these objects with every integration.

1. Open the Remedy AR System ARSystemInstallDir folder and check for the creation of a remoteaction folder. The same files are created on both Windows and Linux systems.

   Contents of C:\Program Files\BMC\ARSystem\pluginsvr\remoteaction folder

   • remoteactionplugin-<version>.jar
   • driver_command_execution.txt
   • lib folder with 40+ jar files
2. Open BMC Remedy Developer Studio and log on as the AR System administrator.

3. Verify whether the following forms have been created. Also verify that filters and escalations have been created for the forms listed below.

   Forms
   

   SB:ServiceRequest-Detail

   SB:ServiceRequest-Detail-Signature

   SB:ServiceRequestStub

   SB:RemoteApprovalConfiguration

If all the files, forms, filters, and escalations were created as described, then the installation was successful.

To configure the callback to the BMC Digital Workplace Catalog server from the AR System server

Use the Remedy Mid Tier for the AR System server to create records to specify the BMC Digital Workplace Catalog server that will receive the callbacks.

1. Open the AR System Objects List on the mid tier by using a URL similar to the following example. Replace <bmc-itsm-sample.com>  with the address of the AR System server.

   Example

   http://<bmc-itsm-sample.com>:8080/arsys/forms

2. When you are prompted, log in as an administrative user who has access permission to use the SB:RemoteApprovalConfiguration form to create records.

   Important

   Some systems require the AR System administrator to access these forms. Other systems allow an application administrator to access these forms. Contact your IT administrator if you are not sure.

3. Search for the SB:RemoteApprovalConfiguration form, and create the following record with values that match your system configuration:

   Example

   http://<bmc-itsm-sample.com>:8080/arsys/forms/<bmc-itsm-sample.com>/SB:RemoteApprovalConfiguration

   Example

   Values that apply to the target BMC Digital Workplace Catalog server

   Parameter	Example	Description
   Remote Hostname	bmc-dwpcatalog-sample.com	Server name of the BMC Digital Workplace Catalog server. You do not need to specify http or https. If the BMC Digital Workplace Catalog server is configured with a load balancer for SSL access or high availability deployment, specify the hostname of the load balancer.
   Remote Port	8008	Port number used to access the BMC Digital Workplace Catalog application, not the platform (9988). Note: If you want to run BMC Digital Workplace Catalog on HTTPS, use port 443 or 8443. Also, update the port on the SB:RemoteApprovalConfiguration form, and make sure that the BMC Digital Workplace certificates are imported to the Remedy AR System server.
   HTTPS	Enable if the BMC Digital Workplace Catalog server is configured for SSL access.
   Remote User Name	hannah_admin@calbroservices.com	Tenant administrator user account.
   SBE Login End point	/api/myit-sb/users/login	Endpoint for authentication.
   SBE Signal End point	/api/myit-sb/processes/signal	Endpoint for process completion responses.

To register the new plugin

To edit the configuration files

1. Copy the updated plugin configuration below and paste it into the appropriate plugin server instance configuration in the pluginsvr_config.xml in the pluginsvr folder.

   Tip

   The list shows the code for Windows. The same code is applicable to UNIX with \ instead of / in the directory names.

   Important

   • Replace [version] below with the actual version found in the name of the remoteactionplugin-[version].jar file in the [pluginsvr_home]\remoteaction directory.
   • Replace [pluginsrv_home] below with the fully qualified directory represented by representing the ARSystemInstallDir/pluginsvr directory.
     For example, C:\Program Files\BMC Software\ARSystem\pluginsvr.

   
   

   <plugin>
   <name>BMC.DWP.REMOTEACTION</name>
   <classname>com.bmc.myservice.filterplugin.RemoteActionPlugin</classname>
   <filename>[pluginsvr_home]\remoteaction\remoteactionplugin-[version].jar</filename>
   <pathelement type="path">[pluginsvr_home]\remoteaction</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\activemq-all-5.10.0.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\aopalliance-repackaged-2.5.0-b32.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\aspectjrt-1.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\com.bmc.arsys.companion.client-17.5.0-SNAPSHOT.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\com.bmc.arsys.companion.remote-17.5.0-SNAPSHOT.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\com.bmc.arsys.messaging.client-17.5.0-SNAPSHOT.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\com.bmc.arsys.rx.application-17.5.0-SNAPSHOT.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\com.bmc.arsys.rx.services-17.5.0-SNAPSHOT.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\commons-jxpath-1.3.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\commons-lang-2.6.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\geronimo-j2ee-management_1.1_spec-1.0.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\geronimo-jms_1.1_spec-1.1.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\hawtbuf-1.10.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\hk2-api-2.5.0-b32.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\hk2-locator-2.5.0-b32.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\hk2-utils-2.5.0-b32.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\j2ee-1.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jackson-annotations-2.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jackson-core-2.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jackson-databind-2.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jackson-jaxrs-base-2.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jackson-jaxrs-json-provider-2.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jackson-module-jaxb-annotations-2.8.4.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\javassist-3.20.0-GA.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\javax.annotation-api-1.2.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\javax.inject-2.5.0-b32.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\javax.ws.rs-api-2.0.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jersey-client-2.25.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jersey-common-2.25.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jersey-entity-filtering-2.25.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jersey-guava-2.25.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jersey-media-json-jackson-2.25.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\jersey-media-multipart-2.25.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\log4j-1.2.17.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\mimepull-1.9.6.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\osgi-resource-locator-1.0.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\retroguard-2.3.1.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\slf4j-api-1.7.7.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\slf4j-log4j12-1.7.2.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\commons-logging-1.2.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\spring-beans-4.1.9.RELEASE.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\spring-core-4.1.9.RELEASE.jar</pathelement>
   <pathelement type="location">[pluginsvr_home]\remoteaction\lib\spring-tx-4.1.9.RELEASE.jar</pathelement>
   <userDefined>
   <maxQueueSize>50000</maxQueueSize>
   <minThreads>5</minThreads>
   <maxThreadsRetry>10</maxThreadsRetry>
   <maxThreads>10</maxThreads>
   <maxQueueSizeRetry>50000</maxQueueSizeRetry>
   </userDefined>
   </plugin>

2. Add the following Plugin related entries with your AR System details to the ar.cfg file. For UNIX servers, add them to the ar.conf file:

   Server-Plugin-Alias: BMC.DWP.REMOTEACTION BMC.DWP.REMOTEACTION <ar-system-server.com>:<ar-system-plugin-port>

Sample pluginsvr_conf.xml file

To configure connections for ITSM functionality

A catalog administrator must configure at least one connection that uses the Remedy connector. To use Atrium Configuration Management Database (CMDB) functionality, a catalog administrator must also configure a connection that uses the CMDB connector.  When you create the first connection for the Remedy connector, the system sets this connection as the default connection for entitlements and approvals. If you are integrating with Atrium Configuration Management Database (CMDB), when you create the first connection for the CMDB connector, the system sets this as the default CMDB connection. For information on creating connections, see Configuring-service-connectors.

To set the default connections for ITSM functionality

If you have more than one connection that uses the Remedy connector or more than one connection that uses the CMDB connector, a catalog administrator can set the default connection in BMC Digital Workplace Catalog. 

To change the default connections from the default values set by the system:

1. Click the configuration gear () to open the Application Settings panel.
2. In the Connectors section, click the arrow (>) to open the Default Connections panel, and select the applicable connections:
   
   • Entitlement/Approval—Displays connections that use the Remedy connector. Select the connection to the BMC Service Request Management server. The connection to this server is used for entitlements and approvals, and should connect to the same Remedy ITSM server that is configured in BMC Digital Workplace.
   • CMDB—Displays connections that use the CMDB connector. Select the connection to Atrium CMDB. 
3. Click Save.
   

To validate the plugin details

1. In a browser, open the Remedy AR System Administration Console, and click System > General > Plugin Server Configuration.
2. Select the Plugin Server Instance that applies to your configuration.
3. Select the BMC.DWP.REMOTEACTION plugin.

4. Select the Plugin Configuration tab, and verify the Plugin Class Name, Plugin File Name, Path Elements and User Defined Elements to ensure that the values are accurate.

   Important

   Under Logging Configuration, click View corresponding to the Log File details to view the log file. Set the Enable Plugin Log to True, and change the Log Level if required.

Troubleshooting the integration

Perform these tasks if you experience any problems while running workflows after you configure the integration to an AR System server.

Options to troubleshoot the AR System server integration

• To monitor a request to observe the fields that a filter action updated, log on to the mid tier to access the AR System server and search for records created through the SB:ServiceRequestStub form.

• To troubleshoot issues with the approval engine, log in to the AR System server and examine the approval log (which must be enabled):

  • (Windows) C:\Program Files\BMC Software\ARSystem\arserver\db\arapprov.log
  • (Linux) /opt/bmc/ARSystem/arserver/db/arapprov.log

  To enable the approval log, log in to the mid tier and update the setting under Quick Links > Approval Administration Console > Server Settings.
  For more information, see Excerpt named BMC Remedy Approval Server configuration file settings was not found in document xwiki:Service-Management.Employee-Digital-Workplace.BMC-Digital-Workplace-Advanced.dwpadv2008._inclusion_library.External-links-inclusions-library.WebHome..

To troubleshoot the communication from the BMC Digital Workplace Catalog server

1. Open the 

   BMC Digital Workplace Catalog

    server file system. Replace <installLocation> with the location of your BMC Digital Workplace Catalog application, for example:
   /opt/bmc/digitalworkplace

2. Review the following log: <installLocation>/db/bundle.log

   • (Recommended) Run-time log example

     # tail -f /opt/bmc/digitalworkplace/db/bundle.log

   • Text editor log example

     # vi /opt/bmc/digitalworkplace/db/bundle.log

Filter Plugin Misconfigured Errors

The SB:ServiceRequestStub form entry that has failed to process, will display errors in the "Error Message" field. When the filter plugin has not been configured, or is not correctly configured, the following error will show up in the Error Message field:
ERROR (8755):The specified plug-in does not exist.;BMC.DWP.REMOTEACTION

If you see this error try the following:

1. Check the remoteaction folder exists in the %AR_INSTALL_BASE%\pluginsvr directory. Verify that the remoteactionplugin-<version #>.jar file and its dependent jar files (in lib subdirectory) exist in the directory.
2. Check the pluginsvr_conf.xml configuration is correct, especially the version of the remoteactionplugin-<version>.jar file
3. Check the ar.cfg (ar.conf) file and make sure that the alias exists and is configured correctly.

Where to go from here

To configure connections to additional Remedy application servers, see Configuring-service-connectors.

To import services from Remedy Service Request Management, see Importing-service-catalog-items-from-external-systems.

To create services, see Adding-and-updating-services.