TeamForge EventQ Reporting API

Overview

Convention

command parameter(s)
command parameter(s)
command parameter(s) ...
return type parameter(s)

Authentication and Authorization

When sending query requests to the reporting api, a custom header named 'X-EventQ-Session' must be added to each http post request, the value of which is the 'session id' returned from a successful login call to the TeamForge endpoint. The TeamForge endpoint is found here: http(s)://TeamForgeHost/ce-soap60/services/CollabNet

Commands and Parameters

Return types

Conclude your query with a single "return" method to transform the data and return the results. All results are returned wrapped in a top-level json hash containing the key items, which contains the results of the query. The return may also contain the optional keys source_display_data, containing a hash of display metadata for the associated sources keyed by source id, and work_item_urls, containing urls to external work items keyed by id (if applicable).

Return example

{
  "items": [
    {
      "_type": "WorkItemSummary",
      "assigned_to": "dev-bot",
      "associated_activity_summary_ids": [

      ],
      "associated_ctf_ids": [

      ],
      "closed": true,
      "comments": [

      ],
      "created_at": "2015-04-22T20:54:26.063Z",
      "created_by": "itembot!",
      "creation_time": "2014-03-29T00:26:20.091Z",
      "deleted": false,
      "description": "Autogenerated workitem description",
      "id": "55380a82109a01555d00000c",
      "opaque_id": "6kkd",
      "priority": "mecha-critical",
      "remote_id": "AUTO-6",
      "remote_status_id": "3",
      "settled": true,
      "source_id": "5537ed65109a012cec000004",
      "summary": "Release the integration",
      "tags": [
        "up",
        "strange"
      ],
      "time_created": "2015-04-22T20:54:26.000Z",
      "updated_at": "2015-04-23T16:49:19.657Z"
    }
  ],
  "source_display_data": {
    "5537ed65109a012cec000004": {
      "_type": "WorkItemSource",
      "_links": {
        "type_icon": {
          "href": "http://ctf.example.com/orc/assets/icons/work-item.png",
          "type": "image/png"
        },
        "source_icon": {
          "href": "http://external.example.com/images/icons/issuetypes/bug.png",
          "type": "image/png"
        }
      },
      "name": "External Bug Tracker",
      "background_color": "#f2511b"
    }
  },
  "work_item_urls": {
    "55380a82109a01555d00000c": "http://tracker.example.com/a_tracker_source/AUTO-6"
  }
}

Return Keys

Return Key	Description
items (array or hash)	Query-dependent results.
source_display_data (hash)	Display metadata for sources references in results.
work_item_urls (hash)	URLs for referenced work items. This key is present in the return structure only if 'items' contains WorkItemSummary objects.

Query Return Data Types

Data item	Description
fields (array or hash)	Returns json formatted results set limited to the fields supplied as parameters.
	Example: fields ["time_created", "remote_id"]
	Accepted values: any set of object fields; see MQ API docs for object descriptions or XDS schema for custom objects. For instance, builds may take: remote_id, status, test_results, duration, created_by, or time_created.
field_contains (nested array)	Returns json formatted results set limited to exact value supplied as parameters.
	Example: field_contains [ "remote_id", ["artf1001", "art1002"] ]
	Accepted values: any object field with matching value set; see MQ API docs for object descriptions or XDS schema for custom objects. For instance, builds may take: remote_id, status, test_results, duration, created_by, or time_created.
group_by_field (string)	Returns json formatted results set grouped by the field supplied as parameter.
	Example: group_by_field "status"
	Accepted values: created_at, remote_id, status
count (none)	Returns a json structure with a count of all matching activities.
	Example: count
timeseries (date/time)	Useful for charting applications, the output will be a hash, where the keys are the starting points of the time series, and the value is the array of objects that fall into that series. It takes a Ruby-style date reference parameter to specify the results granularity. Requires before and after in the same query.
	Example: timeseries 5.minutes
	Accepted values: Ruby-style date references (minutes, hours, days, weeks, months, years).

Examples

The following code examples are Copyright 2020 CollabNet, Inc., licensed under the Apache License, Version 2.0 (the "License"); you may not use this code except in compliance with the License. You may obtain a copy of the License at [http://www.apache.org/licenses/LICENSE-2.0]

Use Cases and Query Examples

Use case: "Find the number of all failed builds across all projects"

#Query:
		restrict_to builds
		field_contains ["status_type", ["FAILURE"] ]
		count

Use case: "Given a set of artfs as inputs, give me all the associated activities"

#Query:
		associated_to: ["artf1234", "artf1235", "artf1236"]

Use case: "Across two specific projects, give me the builds that pass vs fail"

#Query:
		in_project ["proj1001", "proj1002"]
		restrict_to builds
		group_by_field "status_type"

Use case: "Given a set of artfs as inputs (say, in a planning folder) give me build stats (total #, pass, fail, etc)"

#Query:
		associated_to ["artf1001", "artf1002", "artf1003"]
		associations
		restrict_to builds
		group_by_field "status_type"

Use case: "For a given user, give me a list of commits over X timeline, associated build stats"

#Query:
		restrict_to commits
		after 2.weeks.ago
		before 1.week.ago
		field_contains [ "created_by", ["jdoe"] ]
		associations
		restrict_to builds
		group_by_field "status_type"

Use case: "Give me code review stats on a whole project (total #, total reviewed commits, total un-reviewed)"

#Query 1 to find un-reviewed commits
		in_project ["proj1706"]
		restrict_to commits
		has_none "reviews"
		count

		#Query 2 to find reviewed commits:
		in_project ["proj1706"]
		restrict_to commits
		has_any "reviews"
		count

Use case: "Given a set of artfs, give me associated build results starting 1 week ago ending 5 minutes ago, grouped into 4 hour intervals."

#Query:
		associated_to ["artf1001", "artf1002", "artf1003"]
		associations
		restrict_to builds
		after 1.week.ago
		before 5.minutes.ago
		timeseries 4.hours

Use case: "Give me all binary artifact activities grouped by status"

#To query XDS sources like binary artifacts, restrict_to "custom" source type, then
		#filter to narrow the results using tagged_as
		#Query:
		restrict_to custom
		tagged_as ["binary artifact"]
		group_by_field "status_type"

Code samples

Create a Java client using Apache Axis & Apache HttpComponents

Get an X-EventQ-Session value from TeamForge.

/**
		* @param ctfEndpoint
		* @param ctfUserName
		* @param ctfUserPassword
		* @return sessionId (X-EventQ-Session)
		*/
		private static String getSessionIdFromCTF(String ctfEndpoint, String ctfUserName, String ctfUserPassword) {
		try {
			Service service = new Service();
			Call call = (Call) service.createCall();
			call.setTargetEndpointAddress(new java.net.URL(ctfEndpoint));
			call.setOperationName(new QName("http://schema.open.collab.net/sfee50/soap60/service", "login"));
			String sessionId = (String) call.invoke(new Object[]{ctfUserName, ctfUserPassword});
			return sessionId;
		} catch (Exception e) {
			System.err.println(e.toString());
			return e.toString();
			}
		}

Post a request to the Reporting endpoint containing the custom header and a query.

/**
		* @param url
		* @param token
		* @param query
		* @return queryResults
		* @throws Exception
		*/
		String sendPostHttpClient(String url, String token, String query) throws Exception {
		String queryResults;
		CloseableHttpClient client = HttpClients.custom().build();

		HttpUriRequest request = RequestBuilder.post().setUri(url)
		.setHeader(HttpHeaders.CONTENT_TYPE, "application/x-www-form-urlencoded")
		.setHeader("X-EventQ-Session", token)
		.setEntity(new StringEntity(query))
		.build();

		CloseableHttpResponse response = client.execute(request);
		queryResults = EntityUtils.toString(response.getEntity(), "UTF-8");
		return queryResults;
		}

Build your client using the above methods.

public class ReportingClient {

		/* EventQ End Point represents the EventQ instance which you will be querying against*/
		static String eventqEndPoint = "http(s)://EventQHost/orc/api/1/reporting/";

		/* teamForgeEndPoint represents the soap endpoint for the TeamForge instance which your EventQ
		* server is bound to*/
		static String teamForgeEndPoint = "http(s)://TeamforgeHost/ce-soap60/services/CollabNet";

		/* orcReportingQuery is your query in String format. Each LINE represents a different command
		* so in this example every distinct command must be separated by a newline character '\n'*/
		static String orcReportingQuery = "restrict_to reviews\ngroup_by_field \"status_type\"";

		/* TeamForge username and password for the account which the queries will be run under. This account
		* must have REPORTING_API permissions on at least one project in EventQ or must be a SITE ADMIN
		* in Teamforge. If the user is NOT a TeamForge SITE ADMIN, only those projects for which the user has
		* REPORTING_API permissions will be considered in the query.*/
		static String teamForgeUserName = "userName";
		static String teamForgeUserPassword = "userPassword";


		public static void main(String... args) {
			EventQReportingClient sampleClient = new EventQReportingClient();
			String xEventQSession = sampleClient.getSessionIdFromCTF(teamForgeEndPoint,
			teamForgeUserName, teamForgeUserPassword);
			try {
				String serverResponse = sampleClient.sendPostHttpClient(eventqEndPoint,
				xEventQSession, orcReportingQuery);
				System.out.println(serverResponse);
			} catch (Exception e) {
				System.out.println(e.toString());
			}

			}
		}