The Java Repeater Agent is an agent for Windows and Linux that supports the following integrations with ServiceNow:
|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.
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.
To run the installation on linux run the setup.sh command from the bin directory of the Agent. This will run the installation prompt.
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.
The installation prompt will then as you for:
These components will be further described in the Configurations section.
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.
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.
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.
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
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.
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.
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:
Configuration information for connecting to Perspectium MBS as provided by Perspectium:
|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. |
|response_queue|| Queue where the agent should put messages into after processing an integration request. |
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:
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:
|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: |
| 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.
The Repeater Agent supports optionally using an HTTP/HTTPS proxy for the agent to connect outside the network to MBS.
|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.
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 #.
Users can set the sleep time using the “sleep_milliseconds” property in the agent.properties files. If the properties is not configured, it defaults the interval to 15 seconds. So if you want the agent to run on a faster interval (For example 5 seconds, you can configure the properties to sleep_milliseconds=5000)
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:
If no file path is set, it will default to the data folder.
#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 sleep_milliseconds=5000
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.
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.
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.
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.
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.
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.