In this section:

Overview

DTP uses the JMS events broker to provide real-time information about events that occur in DTP. The server publishes event messages to a topic and clients can subscribe to the topics to receive these messages.

The broker manages client connectivity and message distribution with the NIO protocol (nio://). The default port is 61617 (see Configuring the JMS Events Broker Port for instructions on changing the default port). Example URI: nio://hostname:61617.

All events published to the Events Broker are logged to the jms.log file. See Viewing Log Files for instructions on accessing logs.

Accessing Event Broker Topics

Choose Report Center Settings from the settings menu (gear icon) and click Event Broker in the sidebar to access the event broker interface. The interface enables you to reconfigure the JMS port and review event broker topics.   

Support for MQTT

By default, DTP is configured to use the MQTT transport connector. The transport connector is specified in the EventsConfig.xml configuration file located in the [DTP_HOME]/conf directory:

<?xml version="1.0" encoding="UTF-8"?>
<events-configuration>
	<transport-connector port="61617" />
	<transport-connector port="1883" protocol="mqtt"/>
</events-configuration>

Event Topics

The following topics are currently available for subscription.

Event TopicDescription

AnalysisMetadata

This topic notifies subscribers about changes to analysis metadata in the Violations and Test Explorers.

There are two types of messages with the corresponding JMSType:

  • JMSType = 'violations'
  • JMSType = 'test'

The body of the JSON messages employ the following schema:

AnalysisMetadata Event Schema
{
   "fields": [{
      "newValue": "Retest",
      "fieldName": "action"
      }],
      "type": "test",
      "date": "2015-06-08T17:12:39.323+0000",
      "user": "admin",
      "ids": ["8a981276-e694-337e-b543-2187ab610c95"],
      eventId": 18
}

BuildReview

This topic notifies subscribers about changes to a build review in the Change Explorer. There are two types of messages with the corresponding JMSType:

  • JMSType = 'Review': Event is thrown when a request to create, update, or delete a review is successfully fulfilled.
  • JMSType = 'Finding': Event is thrown when a request to create, update, or delete a review finding is successfully fulfilled.

Each message also contains a string property 'action' that represents the type of requested action:

  • action = 'Create'
  • action = 'Update'
  • action = 'Delete'

Messages are TextMessage types that contain JSON as the message body. Example:

BuildReview Event Schema
{
  "type": "Review",
  "action": "Create",
  "entity": {
    "id": "36",
    "baselineBuild": {
      "id": "BaselineBuild"
    },
    "targetBuild": {
      "id": "TargetBuild"
    },
    "name": "ReviewName",
    "author": "admin",
    "metadata": {}
  },
  "activity": {
    "author": "admin",
    "date": "2016-12-09T18:50:11Z",
    "changes": {
      "name": "ReviewName"
    }
  }
}


The JSON in the message body is the same JSON that will be returned for a successful request to the corresponding /v1.3/buildReviews or /v1.3/buildReviews/{id}/findings REST endpoint.

See REST API for more information about the REST endpoint, including how to provide REST authentication.


DataCollector

Notifies subscribers about events created from Data Collector. There are three types of messages with the corresponding JMSType:

  • JMSType = ReceivedEvent: Event is thrown when Data Collector receives the report and starts to process it.
  • JMSType = ProcessedEvent: Event is thrown when Data Collector successfully finishes processing the report.
  • JMSType = ErroredEvent: Event is thrown when Data Collector encounters an error while processing the report.

The body of the JSON messages employ the following schema:

DataCollector Event Schema
{
   "reportFileName":"javaStaticAnalysisRun007.xml",
   "eventTime":"2014-07-10 16:31:04",
   "status":"ReceivedEvent"
}

For ProcessedEvent, the body of JSON includes additional information.

{
   "reportFileName": "em.xml",
   "eventTime": "2014-09-30 15:20:06",
   "status": "ProcessedEvent",
   "fixedViolationsCount": 0,
   "newViolationsCount": 391,
   "suppressedViolationsCount": 48,
   "violationsCount": 439,
   "runConfigurationId": "33",
   "runId": "580",
   "testConfig": {
      "name": "Recommended Rules",
      "machine": "embuilder1.parasoft.com",
      "user": "jenkins",
      "pseudoUrl": "builtin://Recommended Rules"
   },
   "resultsSession": {
      "id": "1412929102566",
      "project": "Environment Manager",
      "time": "2014-09-30T14:44:46-07:00",
      "hasVoils":"true",
      "tag": "Recommended Rules",
      "toolId": "jtest",
      "toolVer": "10.0.6.201406011700",
      "toolName": "Parasoft Jtest",
      "machine": "embuilder1.parasoft.com",
      "lang": "en_US",
      "climode": "true"
      }
}

PrioritizationView

This topic is deprecated in DTP 5.1.4 and later. If you are currently using this topic, we strongly recommend switching to the AnalysisMetdata topic, which also includes changes in the Test Explorer. In the new topic, you can use JMStype = "violations" to filter for messages specifically from the Violations Explorer (called Prioritization View in DTP 5.1.3 and older). See AnalysisMetadata for details.

This topic notifies subscribers about violation priority changes made in the Violations Explorer. There is only one type of message, so JMSType is not required. The message corresponds to an event that modified one or more violations. The JSON contains an event identifier and a list of IDs for all of the modified violations.

PrioritizationView Event Schema
{
   "eventId":"102",
   "violationIds": ["8f522ef1-18bf-38a9-a9ce-dfaa3c91f4f6"],
}

The eventId can be used with the following API endpoint:

/grs/api/v1/staticAnalysisViolations/<violationId>/prioritization/events

An array of the violation’s modification history is returned, and the eventId can be used to correlate what has changed.


Project

This topic notifies subscribers about changes made to projects. DTP will publish an event each time a project is created, updated, or deleted. Messages are TextMessage types that contain JSON as the message body. Example:

PrioritizationView Event Schema
{
   "eventType":"CREATED",
   "project": ["id":"27","name":"Parabank"]
}

The JMSType values are:

  • CREATED
  • UPDATED
  • DELETED

Each message also contains a string property projectName, which is the name of the project. You can use this string property and the JMSType to create a message selector. In the following example, a message selector detects when any project is created:

JMSType = 'CREATED'

In the following example, a message selector detects when only the "Parabank" project is updated:

JMSType = 'UPDATED' and projectName = 'Parabank'

Extending the Project Event Topic with the REST API

You can use the /v1/projects/{id} REST endpoint to retrieve additional project information, such as the state of the project or its end date, after detecting that it has been created or updated.

For example, assume that the project ID for the updated "Parabank" project in the previous example is 27. You could apply a GET to this URL, substituting the proper host and port:

https://yourserver:8443/grs/api/v1/projects/27

See REST API for more information about the REST endpoint, including how to provide REST authentication.

Authentication for Publishing Topics

Authentication is not required to subscribe to a topic, but authentication is required to publish to a topic. You must restart DTP Server anytime you make changes to the EventsConfig.xml or eventsbeans. xml configuration file for changes to take effect.

Enabling the Authentication Topic

  1. Open the EventsConfig.xml configuration file located in the [DTP_HOME]/conf directory
  2. Locate the <topic-authentication> element and set the enabled attribute to true (default). Set the attribute to false to disable authentication. Changing username and password is not recommended. 
  3. Restart DTP Server (see Starting DTP Services).

Authentication Exceptions

You can control which topics do not require authentication after authentication has been enabled.

  1. Open the events-beans.xml configuration file located in the [DTP_HOME]/tomcat/webapps/grs/WEB-INF/ springs/ directory.
  2. Add topic names to the list of nonAuthenticatedTopics property in the destinationAuthenticationManager bean:

    <bean id="destinationAuthenticationManager">
    	<property name="nonAuthenticatedTopics">
    		<list>
    			<value>MyTopicName</value>
    		</list>
    	</property>
    </bean>
  3. Restart DTP Server (see Starting DTP Services).


  • No labels