User Tools

Site Tools


repeaterj_agent

Java Repeater Agent

v3.31.0

The Java Repeater Agent is an agent for Windows and Linux that supports the following integrations with ServiceNow:

Integration Description
Jira ServiceNow to Jira integration such as ServiceNow incidents to Jira defects
NOTE: As of the Europium release, Jira attachments can also be shared to ServiceNow with the Repeater Agent
Service Manager ServiceNow to Service Manager integration

The Repeater Agent has the same requirements as the Replicator Agent as noted here.

As of the Europium release, the Repeater Agent supports up to Java version 10.


Installation

Unpacking

The agent is packaged as a zip file. You will place it and unzip it in where you would like to install it. Once unzipped, you will have the following directories:

The following commands and set up steps will utilize components located in bin and conf directory.

Installing

Linux

To run the installation on linux run the setup.sh command from the bin directory of the Agent. This will run the installation prompt.

Windows

To run the installation on windows run the setup.bat file located in the bin directory of the Agent. This will run the installation prompt.

Installation Prompt

The installation prompt will then as you for:

  1. MBS Credentials (URL, Username, Password)
  2. Service Credentials (URL, Username, Password)
  3. Service Type (Jira, Remedy)
  4. Queue Names
  5. Proxy Configurations (optional)
  6. Service Name (optional)

These components will be further described in the Configurations section.

Installing as a Service

You can run the Agent on its own, however, for extended use we recommend installing the Agent as a Daemon (Linux) or a Service (Windows). It will be given the Service Name “Perspectium_Repeater_Agent” unless modified in the installer. It will be given the Display Name “Perspectium_Repeater_Agent”.

If you intend to install multiple Agents on the same VM, perhaps for Dev/Test it is necessary to do a couple extra steps detailed below. We recommend having an isolated VM for any production activity.

Linux

To run the installation on linux run the installDaemon.sh command from the bin directory of the Agent. This will install it as a Daemon.

Windows

To run the installation on linux run the installService.bat command from the bin directory of the Agent. This will install it as a Service. You can then find the service in the windows standard services panel.

Multiple Agents

As stated before the Agent will be given the default name/display name “Perspectium_Repeater_Agent” for the service. If you would like two running on the same machine both of these values must be unique. To check these values open up the wrapper.conf file in the conf directory and search for the following:

#********************************************************************
# Wrapper Windows Service and Posix Daemon Properties
#********************************************************************
# Name of the service
wrapper.ntservice.name=Perspectium_Repeater_Agent

# Display name of the service
wrapper.ntservice.displayname=Perspectium_Repeater_Agent

# Description of the service
wrapper.ntservice.description=Perspectium_Repeater_Agent

You will modify these values for name and displayname to fit your Agents. For example, for you company “acme” you can name them

Name Display Name
acme_dev Perspectium_Repeater_Agent_Dev
acme_test Perspectium_Repeater_Agent_Test

Note: The install service scripts key off the values here. So if you want to re-name a service (or uninstall a service), uninstall it first before modifying the wrapper.conf.

Installing with Receipts

By default, the Repeater Agent will send receipts upon receiving messages. To enable Perspectium Receipts functionality, please contact support to install the correct update set on your Service Now instance.

Configurations

The agent's configuration file, agent.properties is located in the conf directory. The service wrapper's configuration file wrapper.conf is also located in the conf directory.

The following configurations are available for the agent:

MBS Configuration

Configuration information for connecting to Perspectium MBS as provided by Perspectium:

Attribute Description
mbs_url URL of the Perspectium MBS server Required
mbs_user Username for the Perspectium MBS server Required
mbs_password Password for the Perspectium MBS server Required
request_queue Queue where the agent should read messages from.
Example: psp.out.siam.<integration>.agent.<instance_name>
Required
response_queue Queue where the agent should put messages into after processing an integration request.
Example: psp.in.siam.<integration>.agent
Required

The request queue and response queue are where the Agent will be forwarding the requests from and to, respectively. They traditionally follow the pattern detailed above. For a Jira integration to the ServiceNow instance “acme” you would use the queues:

  • psp.out.siam.jira.agent.acme
  • psp.out.servicenow.acme

Service Integration Configuration

Configuration information for the Service (such as Jira) that the agent will be integrating with. This is the Service that messages read from MBS will be posted to:

Attribute Definition
service_type The type of integration. Only the following integrations should have a value specified, as all other integrations will work with the default message repeater setup:

Jira, (service_type=Jira)
Remedy, (service_type=Remedy)
Cherwell, (service_type=Cherwell)
Required for Jira, Remedy, and Cherwell integrations

Optional for other integrations
service_url URL of the Service API to connect to. (an example for jira would be https://hostname.atlassian.net/) Required
service_user Username for the Service API to connect to. Required
service_password Password for the Service API to connect to. Required
cache_location v3.26.0 Declares directory for logging. If the directory is not declared, it will be set to a default location. Optional

For the agent to function properly the service user must have permission to create, update, and delete tickets in the project being shared to as well as having access to any custom fields that exist within that project. For example, in a Jira integration this would be group access to a project.

The Service API URL (service_url configuration) will also need to be provided to Perspectium for provisioning on MBS.

Proxy Configuration

The Repeater Agent supports optionally using an HTTP/HTTPS proxy for the agent to connect outside the network to MBS.

Description
proxy_url URL of the Service API to connect to. Optional
proxy_user Username for the Service API to connect to. Optional
proxy_password Password for the Service API to connect to. Optional

If you are not using a proxy you can just hit “Enter” to skip through these.

Max Retries

In v3.25.0 users can set the “service_max_retries” property in the agent.properties file. Set this property to a number to limit the attempts of retries on sending a message. After reaching this limit, the agent will skip the message and move on to the next message.

NOTE: This is an optional property with a default setting of 5 retries. A “#” character in front of it will mean this is ignored and we will try indefinitely. We recommend setting it to 3-5 and removing the #.

Cache Location

In v3.26.0 users can set the directory in which the logging file, agent.dat, will be saved. Set this property in the agent.properties file, which will be in the conf folder. When setting the properties, please append the next folders with the “/” instead of “\” as shown:

cache_location=C:/Users/Windows10/Desktop

If no file path is set, it will default to the data folder.

Sample Configuration File

#Perspectium Repeater Agent Configuration File
#   To encrypt property values such as passwords, prefix the value with encrypt:

#MBS Configuration
mbs_url=https://replaceme.perspectium.net
mbs_user=your/user
mbs_password=yourpassword

request_queue=psp.out.siam.jira.agent.dev1234
response_queue=psp.in.siam.jira.agent

#Proxy Configuration
#proxy_url=http://proxyhost:8080
#proxy_user=proxyuser
#proxy_password=proxypassword

#Service Configuration
service_url=http://servicehost.yourcompany.net:12345/ws
service_user=perspectium
service_password=perspectium
cache_location=../data
service_max_retries=5

Running the Agent

The Repeater Agent runs by executing scripts in the <agent_installed_directory>/bin directory. It can be run in the console or installed as a Windows service or Linux Daemon.

Linux

Starting / Stopping the Agent in the Console

  • cd to the /bin subdirectory of your installed directory
  • To start run runConsole.sh
  • To stop run stop.sh

Starting / Stopping Daemon

  • As Adminstrator, cd to the /bin subdirectory of your install directory
  • To start run startDaemon.sh
  • To stop run stopDaemon.sh

Uninstalling Daemon

  • As Adminstrator, cd to the /bin subdirectory of your install directory
  • run uninstallDaemon.sh

Windows

Starting / Stopping the Agent in the Console

  • Open up the bin directory of the Agent
  • To start execute runConsole.bat
  • To stop execute stop.bat (or exit out of the command prompt window)

Starting / Stopping the Service

  • As Adminstrator, open up the to the /bin subdirectory of your install directory
  • To start execute the startService.bat
  • To stop execute the stopService.bat
  • You could equivalently use the windows services panel

Uninstalling Service

  • As Adminstrator, cd to the /bin subdirectory of your install directory
  • uninstallService.bat

Troubleshooting

Log files are located in the /logs subdirectory of your install directory. The latest log file will always be named perspectium.log. These log files will be rotated and compressed daily.

Setting the Logging Level

You can manually set the logging level by editing a single line of the config. Log into the host that the agent is installed on and navigate to the home directory of the Agent and edit the log4j2.xml file within the conf folder.

You will change the property <Root level=“DEBUG”> to: INFO, DEBUG, or FINEST.

Finest provides the most detail and info provides the least. Save the file and restart the agent to implement the change. This will stay in affect through Agent restarts until it is modified back.

Carbon
The agent will log the request (the XML/JSON) it makes to the integration such as JIRA as well as the response it gets back from the integration to help with troubleshooting issues. This logging only occurs when the logging level is set to FINEST.

Handling Self-Signed Certificates

If you have self signed certificates for your local Jira instance you will likely see the following in your logs:

javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target

Please see the following link for how to handle self signed certs.

Handling Common Attachment Formats

If the common attachments that are posted for your integration appear to be in the incorrect format, you may need to reconfigure your service_type so that it properly matches the endpoint you are integrating with. To determine the service_type value for your Repeater Agent, check the PSP Logs module.

For more information, see Service Integration Configuration.

repeaterj_agent.txt · Last modified: 2019/01/09 16:24 by timothy.pike