TeamForge EventQ provides a message queue (MQ) based interface for adding custom adapters and the Extensible Data Source (XDS) system for adding new product domains and tools.

Overview

TeamForge EventQ APIs can be classified into three groups: Extensibility APIs, Reporting APIs and HTTP APIs.

  • Extensibility APIs: To add new integrations to EventQ such as Commits API, Builds API, Review Requests API and so on.
  • Reporting API: To retrieve data from the EventQ database.
  • HTTP APIs: To administrate EventQ programmatically.

EventQ can be extended via the Message Queue (MQ) API. The MQ API is provided for purposes of creating custom adapters for stock product classes/domains; build, commit, code review, and work item sources can post activity information to the corresponding message queues using the formats described in the API Documentation (see references below).

New product classes may be established using the Extensible Data Source API, or XDS API. For instance, TeamForge EventQ does not have stock product class for “deployment”, so the XDS API may be used to establish a new product domain for “deployment” which can then be used like other sources.

MQ API — Writing Your Own Adapters

Each TeamForge EventQ instance has an associated “message queue” service, which is used to collect and queue data from integrated tools. Extensibility is achieved by writing “adapters” that communicate specially formatted messages to the TeamForge EventQ message queue service.

The message communication protocol is called “AMQP” and the RabbitMQ web site links to open source AMQP protocol libraries that can be used to create adapters for numerous languages and platforms. The API documentation referenced below houses detailed message format specifications, example messages, and code samples for interacting with AMQP libraries.

TeamForge EventQ is extensible via MQ for these types of tools: SCM and version control, continuous integration/build, code review, and work item systems.

XDS API — Authoring New Product/Tool Domains

EventQ can be configured to accept data from a wide range of sources through the XDS API. In addition to the stock activity APIs defined for commits, builds, reviews, and work items, the XDS feature enables you to create your own activity APIs by defining and registering an “XDS Schema” that describes the expected activity message format for a particular tool or product domain in question. Once an XDS Schema is registered with EventQ, adapters can send EventQ activity messages in compliance with the registered schema and the resulting XDS activities may show up in activity streams and as associations. In this way, XDS Schemas give users a way to publish new activity APIs for arbitrary, user-defined data sources.

XDS Schemas can be added to EventQ either through the MQ or HTTP API. See Extensible Data Sources (XDS) Walk-through and refer to the API documentation.

Once a Schema is established, “XDS Sources” can be added through the “Custom” step type. See Extensible Data Source (XDS) Overview.

Authentication

For the MQ interface, authentication is provisioned by the RabbitMQ server. When a new source is created, a unique username/password combination is created and exposed on the EventQ source edit screen. These credentials must be supplied by the posting client. These user credentials are independent of the TeamForge user store and belong only to RabbitMQ.

Extensibility APIs

Commits API

Submission Parameters

Submission Queue
  • queue_name: eventq.commits
  • auto_delete: false
  • durable: true
Top Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Required A key generated by TeamForge EventQ that links incoming commit messages with the appropriate source server.
Example: "source_association_key": "31e8dd90-164f-0130-c4d0-406c8f04c05d"
commit_data Required The commit.
Objects

commit_data - The following fileds should be in this commit post.

Field Required/Optional Description
repo_id Optional A unique identifier for this repository. For example, the repo UUID.
revision_id Required A unique identifier for the commit action (eg., revision number or commit id).
branch_name Optional Identifier for the applicable repository branch.
type Required A string representing the activity type
Accepted values
post-commit - A commit has been completed.
message Optional The message associated with this activity.
changes Optional An array of changed items. Required information about affected paths (an array of hashes).
Accepted values
  • path (Required) - A string with the relative path to the file that created, modified, etc.
  • action (Required) - A string representing the action.
    • added - Added
    • deleted - Deleted
    • modified - Modified
    • props_modified - File properties (not contents) modified
    • type_changed - Type changed (e.g., from 'file' to 'symlink', 'symlink' to 'directory', etc.)
    • copied - Path is copied from another source
    • renamed - Path is renamed from another source
  • from (Optional) - If the activity is a copy or rename, the path from which it was copied or renamed (if it can be determined or inferred with some accuracy; this is not guaranteed to be absolutely correct)
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
created_by Required The user name of the person who took the action.

Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON

{
      "api_version": "1",
      "source_association_key" : "150e8951-19e1-4066-8b74-601026dd6cde",
      "commit_data" : {
        "repo_id": "390e8951-19e1-4066-8b74-601026dd6cde",
        "revision_id": "2315",
        "branch_name": "master",
        "type": "post_commit",
        "message": "here's my commit [orc-277]",
        "changes": [
          { "path": "/source/file/1", "action": "modified" },
          { "path": "/source/file/2", "action": "added" },
          { "path": "/source/file/3", "action": "deleted" },
          { "path": "/source/file/4", "action": "modified" },
          { "path": "/source/file/4", "action": "props_modified" }
        ],
        "event_time": "2012-10-02T17:15:32.320Z",
        "created_by": "username"
      }
    }

Ruby Submission Example

You will need to change the following example before you can run it. Set the Rabbit MQ hostname and the association key, and paste a JSON block following the commit format specified on this page.

require 'amqp'

      QUEUE = 'eventq.commits'
      COMMIT = '{
        "api_version": "1",
        "source_association_key" : "150e8951-19e1-4066-8b74-601026dd6cde",
        "commit_data" : {
          "repo_id": "390e8951-19e1-4066-8b74-601026dd6cde",
          "revision_id": "2315",
          "branch_name": "master",
          "type": "post_commit",
          "message": "here\'s my commit [orc-277]",
          "changes": [
            { "path": "/source/file/1", "action": "modified" },
            { "path": "/source/file/2", "action": "added" },
            { "path": "/source/file/3", "action": "deleted" },
            { "path": "/source/file/4", "action": "modified" },
            { "path": "/source/file/4", "action": "props_modified" }
          ],
          "event_time": "2012-10-02T17:15:32.320Z",
          "created_by": "username"
        }
      }'

      # Event loop
      EventMachine.run do
        connection = AMQP.connect('amqp://guest:guest@example-mq')

        # Set up our RabbitMQ information
        channel = AMQP::Channel.new(connection)
        queue = channel.queue(QUEUE, :auto_delete => false, durable: true)
        exchange = channel.direct('')

        # Publish the activity and exit the loop
        exchange.publish COMMIT, :routing_key => queue.name do
          connection.disconnect {EventMachine.stop}
        end
      end

Builds API

Submission Parameters

Submission Queue
  • queue_name: eventq.builds
  • auto_delete: false
  • durable: true
Top Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Required A key generated by TeamForge EventQ that links incoming builds with the appropriate source server.
Example: "source_association_key": "6t5qM5AuLLWLkmqFJeKp"
build_data Required The raw build data, as provided by the build system.
Objects

build_data - The following fields should be in this build object.

Field Required/Optional Description
remote_id Required A string to uniquely identify the build. It will appear in the UI.
duration Required A string containing time (in seconds) it took for a build agent to build.
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
build_url Required A string with the URL to the build summary. Please note that the fully qualified URL with the URL scheme is required.
created_by Optional A string containing the username of the person who triggered the build.
status Required An object that declares the status of the build object.
Accepted values
  • type (Required) - A string representing the type of the status. Please note that any type other than the listed below will be used as UNKNOWN inside TeamForge EventQ.
    • SUCCESS
    • FAILURE
    • UNSTABLE
    • ABORTED
  • name (Required) - A user-friendly display name for the status.
test_results Optional An object containing the test results summary.
Accepted values
  • passed_count - A string containing the number of passed tests.
  • failed_count - A string containing the number of failed tests.
  • ignored_count - A string containing the number of ignored tests.
  • url - A string containing the URL to the test results. Please note that the fully qualified URL with the URL scheme is required.
revisions Optional An array of objects containing the SCM revisions related to this build.
Accepted values
  • revision (Required) - A string containing the commit revision id.
  • repository_url (Required) - A string containing the repository url.
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
created_by Required The user name of the person who took the action.

Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON

{
    "api_version": "1",
    "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
    "build_data": {
    "remote_id": "700",
        "event_time": "2012-10-02T17:15:32.320Z",
        "duration": "200",
        "build_url": "http://example.com/builds/600",
        "created_by": "admin",
        "status": {
            "type": "SUCCESS",
            "name": "SUCCESSFUL"
        },
        "test_results": {
            "passed_count": "10",
            "failed_count": "0",
            "ignored_count": "0",
            "url": "http://example.com/builds/600/tests"
        },
        "revisions":
            [{ "revision": "fb849a2440dda438f4c6ab25f8c3266ed82d8797",
             "repository_url": "ssh://gitserver/project"
            }]
        }
  }

Ruby Submission Example

You will need to change the following example before you can run it. Set the Rabbit MQ hostname and the association key, and paste a JSON block following the build format specified on this page.

 require 'amqp'

      QUEUE = 'eventq.builds'
      BUILD = '{
        "api_version": "1",
        "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
        "build_data": {
            "remote_id": "700",
            "event_time": "2012-10-02T17:15:32.320Z",
            "duration": "200",
            "build_url": "http://example.com/builds/600",
            "created_by": "admin",
            "status": {
                "type": "SUCCESS",
                "name": "SUCCESSFUL"
            },
            "test_results": {
                "passed_count": "10",
                "failed_count": "0",
                "ignored_count": "0",
                "url": "http://example.com/builds/600/tests"
             },
            "revisions":
             [{ "revision": "fb849a2440dda438f4c6ab25f8c3266ed82d8797",
             "repository_url": "ssh://gitserver/project"
              }]
        }
      }'
      # Event loop
      EventMachine.run do
        connection = AMQP.connect('amqp://guest:guest@example-mq')

        # Set up our RabbitMQ information
        channel = AMQP::Channel.new(connection)
        queue = channel.queue(QUEUE, :auto_delete => false, durable: true)
        exchange = channel.direct('')

        # Publish the build and exit the loop
        exchange.publish BUILD, :routing_key => queue.name do
          connection.disconnect {EventMachine.stop}
        end
      end

Review Requests API

Submission Parameters

Submission Queue
  • queue_name: eventq.reviews
  • auto_delete: false
  • durable: true
Top Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Required A key generated by TeamForge EventQ that links incoming review requests with the appropriate source server.
Example: "source_association_key": "31e8dd90-164f-0130-c4d0-406c8f04c05d"
request_data Required The raw review request data, as provided by the review server.
Objects

request_data - The following fields should be in this review request object.

Field Required/Optional Description
remote_id Required A string to uniquely identify the review request.
link Optional A URL that points back to this individual review.
summary Optional A string to summarize the review request.
description Optional A longer string that can be used to further describe the review request. It will appear in the UI.
created_by Required "A string containing the username of the person who submitted the request (e.g., initiated this request event, NOT necessarily the creator of the review; in some instances, this may consistently be an administrative user)."
status Required An object that declares the status of the review request.
Accepted values
  • type (Required) - A string representing the type of the status.
    • open - The review request is currently open for review.
    • submitted - The review request changes have been submitted.
    • rejected - The code in the request was rejected.
    • discarded - The review request has been discarded.
    • other - A status type that may not fit into the above list.
  • name (Required) - A user-friendly display name for the status.
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
updated_by Optional A string containing the username of the person performing the update.
files Optional An array of objects with optional SCM revision information. If included, only the file name is required.
Accepted values
  • file (Required) - A string with the full path to the file that was being reviewed.
  • revision (Optional) - A string representing the revision number of the commit that includes this file.
  • repository_url (Optional) - A string with the URL to the SCM server. For associations to commits, this must match one defined as a source in the same pipeline.
reviewers Optional An array of user hashes. Optional reviewer information. If included, only the user name is required. For some systems, reviewers are only reported when they have marked the review 'completed' or 'reviewed'; other systems (e.g., Review Board) report reviewers when they add comments or make other changes to a review.
Accepted values
  • username (Required) - A string of the user's name.
  • link (Optional) - A string representing the URL to the users profile.
Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON

{
    "api_version": "1",
    "source_association_key" : "31e8dd90-164f-0130-c4d0-406c8f04c05d",
    "request_data" : {
      "remote_id": "42",
      "link": "http://reviewserver/review/42/",
      "summary": "The summary of the request",
      "description": "An extended description of what the request covers",
      "status": {
        "type": "open",
        "name": "Review"
      },
      "event_time": "2012-10-02T17:15:32.320Z",
      "created_by": "username",
      "updated_by": "username",
      "files": [
        {
          "revision": "ef9f8fe661992f48c3539c05fc5c69c61918fa17",
          "file": "commit1_file1.txt",
          "repository_url": "ssh://gitserver/project"
        },
        {
          "revision": "ef9f8fe661992f48c3539c05fc5c69c61918fa17",
          "file": "commit1_file2.txt",
          "repository_url": "ssh://gitserver/project"
        },
        {
          "revision": "fb849a2440dda438f4c6ab25f8c3266ed82d8797",
          "file": "commit2_file1.txt",
          "repository_url": "ssh://othergitserver/project"
        }
      ],
      "reviewers": [
        { "username": "adent", "link": "http://reviewserver/user/adent" },
        { "username": "fprefect", "link": "http://reviewserver/user/fprefect" }
      ]
    }
}

Ruby Submission Example

You will need to change the following example before you can run it. Set the Rabbit MQ hostname and the association key, and paste a JSON block following the review format specified on this page.

require 'amqp'

    QUEUE = 'eventq.reviews'
    REVIEW = '{
      "api_version": "1",
      "source_association_key" : "31e8dd90-164f-0130-c4d0-406c8f04c05d",
      "request_data" : {
        "remote_id": "42",
        "link": "http://reviewserver/review/42/",
        "summary": "The summary of the request",
        "description": "An extended description of what the request covers",
        "status": {
          "type": "open",
          "name": "Review"
        },
        "event_time": "2012-10-02T17:15:32.320Z",
        "created_by": "username",
        "files": [
          {
            "revision": "ef9f8fe661992f48c3539c05fc5c69c61918fa17",
            "file": "commit1_file1.txt",
            "repository_url": "ssh://gitserver/project"
          },
          {
            "revision": "ef9f8fe661992f48c3539c05fc5c69c61918fa17",
            "file": "commit1_file2.txt",
            "repository_url": "ssh://gitserver/project"
          },
          {
            "revision": "fb849a2440dda438f4c6ab25f8c3266ed82d8797",
            "file": "commit2_file1.txt",
            "repository_url": "ssh://othergitserver/project"
          }
        ],
        "reviewers": [
          { "username": "adent", "link": "http://reviewserver/user/adent" },
          { "username": "fprefect", "link": "http://reviewserver/user/fprefect" }
        ]
      }
    }'

    # Event loop
    EventMachine.run do
      connection = AMQP.connect('amqp://guest:guest@example-mq')

      # Set up our RabbitMQ information
      channel = AMQP::Channel.new(connection)
      queue = channel.queue(QUEUE, :auto_delete => false, durable: true)
      exchange = channel.direct('')

      # Publish the activity and exit the loop
      exchange.publish REVIEW, :routing_key => queue.name do
        connection.disconnect {EventMachine.stop}
      end
    end

Work Item API

Integrating TeamForge EventQ with the Work Item systems requires for the adapters to be able to send the configuration details of the underlying systems (trackers configuration etc. (see “TODO put a link on configuring work item sources”)) as well as the actual data (work items) generated by these systems. These are two distinct types of messages that use different formats.

There are two types of Work Item APIs:

Work Item Configuration API

Submission Parameters

Submission Queue
  • queue_name: eventq.work_items
  • auto_delete: false
  • durable: true
Top Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Required A key generated by TeamForge EventQ that links incoming work items with the appropriate source server.
Example: "source_association_key": "6t5qM5AuLLWLkmqFJeKp"
workitem_settings Required Tracker configuration details.
Objects

workitem_settings - The following fields should be in this workitem_settings object.

Field Required/Optional Description
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
url Required A string with the browse URL for the system. EventQ will append an individual work item's id to that url to link back to the work item.
tracker Required Tracker configuration information. A JSON object describing the structure of the tracker.
Accepted values
  • name (Required) - A name for the tracker.
  • id (Required) - A string containing a unique (on the reporting system) identifier for the tracker.
  • key (Optional) - A string containing the tracker key (usually used to prefix the work-item ids).
  • regex (Required) - A string containing a regular expression that EventQ will use to associate work-items with commits using the commit message.
  • icon (Optional) - A string containing a URL for this tracker's icon.
  • statuses (Required) - An array of status objects associated with the tracker.
    • id (Required) - A string containing a unique(on the underlying system) identifier for the status.
    • name (Required) - A string containing the name of the status.

Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON

{
      "api_version": "1",
      "source_association_key" : "150e8951-19e1-4066-8b74-601026dd6cde",
      "workitem_settings" : {
      "url": "http://www.example.com/jira",
      "event_time": "2012-10-02T17:15:32.320Z",
      "tracker": {
                   "name": "EventQ/Stories",
                   "id": "01234567abcdef01234567",
                   "key":"ORC",
                   "regex": "ORC-\d+",
                   "icon": "http://www.example.com/jira/browse/bug.jpig",
                   "statuses": [
                       {"name": "Open", "id": "abcdef"},
                       {"name": "In progress", "id": "123abc"},
                       {"name": "Closed", "id": "456123"}
                   ]
                 }
      }
}

Ruby Submission Example

You will need to change the following example before you can run it. Set the Rabbit MQ hostname and the association key, and paste a JSON block following the build format specified on this page.

require 'amqp'

      QUEUE = 'eventq.work_items'
      WORK_ITEM_CONFIGURATION = '
      {
        "api_version": "1",
        "source_association_key" : "150e8951-19e1-4066-8b74-601026dd6cde",
        "workitem_settings" : {
            "url": "http://www.example.com/jira",
            "event_time": "2012-10-02T17:15:32.320Z",
            "tracker":  {
                            "name": "EventQ/Stories",
                            "id": "01234567abcdef01234567",
                            "key":"ORC",
                            "regex": "ORC-\d+",
                            "icon": "http://www.example.com/jira/browse/bug.jpig",
                            "statuses": [
                                {"name": "Open", "id": "abcdef"},
                                {"name": "In progress", "id": "123abc"},
                                {"name": "Closed", "id": "456123"}
                            ]
                         }
      }
    }'
      # Event loop
      EventMachine.run do
        connection = AMQP.connect('amqp://guest:guest@example-mq')

        # Set up our RabbitMQ information
        channel = AMQP::Channel.new(connection)
        queue = channel.queue(QUEUE, :auto_delete => false, durable: true)
        exchange = channel.direct('')

        # Publish the work item configuration and exit the loop
        exchange.publish WORK_ITEM_CONFIGURATION, :routing_key => queue.name do
          connection.disconnect {EventMachine.stop}
        end
      end

Work Item Message API

Submission Parameters

Submission Queue
  • queue_name: eventq.work_items
  • auto_delete: false
  • durable: true
Top Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Required A key generated by TeamForge EventQ that links incoming work items with the appropriate source server.
Example: "source_association_key": "6t5qM5AuLLWLkmqFJeKp"
workitem_settings Required The work item data.
Objects

work_item - The following fields should be in this work item object.

Field Required/Optional Description
created_by Optional A string containing the username of the person who submitted the work item.
updated_by Optional A string containing the username of the person performing the update.
id Required A string to uniquely identify the work item.
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
summary Required A string to summarize the work item.
description Optional A longer string that can be used to further describe the work item.
status_id Required A string to uniquely identify the status. This value must match the identifier within the work item configuration message.
tracker_id Required A string to uniquely identify the tracker. This value must match the identifier within the work item configuration message.
closed Optional A boolean for the open or closed state of the work item. True if the work item is closed.
deleted Optional A boolean for the deleted state of the work item. True if the work item has been deleted.
priority Optional A string containing the priority of the work item.
assigned_to Optional A string containing the username of the person who is assigned to the work item.
creation_time Optional A string containing a timestamp in UTC timezone and RFC 3339 format. The time the item was first created in the source system.
tags Optional An array of strings containing the tags, or labels, for this work item.
Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON

{
      "api_version": "1",
      "source_association_key" : "150e8951-19e1-4066-8b74-601026dd6cde",
      "work_item": {
          "created_by": "admin",
          "updated_by": "username",
          "summary": "title",
          "id": "KDA-59",
          "description": "description",
          "status_id": "10001",
          "event_time": "2014-03-12T20:47:41.295Z",
          "closed": false,
          "deleted": false,
          "tracker_id": "10200-2",
          "priority": "Major",
          "assigned_to": "admin",
          "creation_time": "2014-03-29T00:26:20.091Z",
          "tags": [
            "Tag1",
            "Tag2",
            "Tag3"
          ]
      }
}

Ruby Submission Example

You will need to change the following example before you can run it. Set the Rabbit MQ hostname and the association key, and paste a JSON block following the build format specified on this page.

require 'amqp'

      QUEUE = 'eventq.work_items'
      WORK_ITEM = '
      {
        "api_version": "1",
        "source_association_key" : "150e8951-19e1-4066-8b74-601026dd6cde",
        "work_item": {
            "created_by": "admin",
            "updated_by": "admin",
            "summary": "title",
            "id": "KDA-59",
            "description": "description",
            "status_id": "10001",
            "event_time": "2014-03-12T20:47:41.295Z",
            "closed": false,
            "deleted": false,
            "tracker_id": "10200-2",
            "priority": "Major",
            "assigned_to": "admin",
            "creation_time": "2014-03-29T00:26:20.091Z",
            "tags": [
                "Tag1",
                "Tag2",
                "Tag3"
            ]
        }
      }'
      # Event loop
      EventMachine.run do
        connection = AMQP.connect('amqp://guest:guest@example-mq')

        # Set up our RabbitMQ information
        channel = AMQP::Channel.new(connection)
        queue = channel.queue(QUEUE, :auto_delete => false, durable: true)
        exchange = channel.direct('')

        # Publish the work item and exit the loop
        exchange.publish WORK_ITEM, :routing_key => queue.name do
          connection.disconnect {EventMachine.stop}
        end
      end

Extensible Data Sources (XDS) Walk-through

This walk-through is intended to provide a detailed step-by-step implementation example of the Extensible Data Sources (or XDS) feature. Please read the parent overview section of this document first.

Setting the stage: EventQ does not ship with a stock activity API for deployment tools, so our fictional example lifecycle includes a process to deploy software into various environments. EventQ users would like to see these deployment activities bubble up to activity streams and any deployment associations in the context of other activities. So let’s define an XDS Schema modeling the “deployment” domain and then send activities to the newly registered XDS Activity API for deploy.

Define the Schema Attributes - The first step is craft an XDS Schema to adequately describe our deployment domain space and the events we expect to send to EventQ. The submission of the data type schema is itself governed by an API, which is documented at XDS Schema API.

  1. API version The version number of the XDS Schema API (not your new schema’s version number).
  2. Source association key This value is obtained by creating a new “XDS Source” in EventQ’s web client. Supplying a source association key is optional during schema registration. If provided, the source will be associated with the schema when the schema is received. Otherwise, the XDS source will be associated to a registered schema when the first activity message is received. There is no “preferred” option; this flexibility exists purely to suit various types of integration models.
  3. Schema name Should be a human-friendly identifier of the data source.
  4. Schema ID Takes a UUID as the value and the value should be unique per schema. If UUID generation is not possible, characters are limited to alphanumerics and the dash symbol.
  5. Schema version Allows for the same schema to be updated without sending a separate schema ID. This is an integer field, best practice is to start at 1 and increment.
  6. Event time The time at which your newly crafted schema is submitted to EventQ. Requires UTC RFC3339 format.

    The schema ID is user-defined; we suggest a long “UUID” style string. The schema name is also user-defined. In our deploy example, we can add a schema ID and name as follows:

    // Example Deploy XDS Schema
    {
      "api_version": "1",
      "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
      "custom_schema": {
      "name": "Faux Schema",
      "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
      "schema_version": 2,
      "event_time": "2015-02-02T17:15:32.320Z",
      }
    }
    

Defining the fields expected by your schema - Since you are defining an API at this stage, the next step is to define the list of fields expected by your API. Fields are the attributes you wish to supply with each event message sent by an adapter. We’ll address optional vs. required fields in the next section, but for now we want a comprehensive list of all fields represented in your new activity message format. For instance, in our deploy example you may want to supply deploy environment, time, duration of deploy activities, etc.

The XDS Activity API categorizes fields into three classes: mandatory fields, stock fields, and custom fields. “Mandatory fields” are required in all registered schemas and thus must be present in all activity messages. “Stock fields” are a set of non-mandatory fields that have special relevance to the EventQ application, such as appearing in specific places in the user interface. “Custom fields” are truly arbitrary and may be used to capture desired data not encompassed by mandatory or stock fields.

  1. Mandatory fields - all of these fields are required in every XDS schema.

    1. schema_id Activity messages will need to send this to identify themselves as governed by a specific schema.
    2. schema_version Should match the same schema_version as sent by the schema. This makes sure that the message is displayed with the correct version of the schema.
    3. event_time The UTC RFC3339 time of the event. 4.remote_id Represents the source tool’s identifier for the activity. For instance, if we were modeling Subversion commits, the remote_id would be the revision number. Messages with the same remote_id are treated as part of the same activity and are aggregated as “sub-events”.
  2. Stock fields - Optional fields with special relevance in the EventQ application.

    1. associated_remote_id If your activity has an association this field is used to specify one or more IDs for purposes of association.
    2. created_by The user who instantiated the activity.
    3. summary The primary heading or title of the activity.
    4. description A detailed description of the activity.
    5. status_name The current status of the activity, corresponds to the “status_type” field.
    6. status_type The current status class, either “open”, “success”, or “fail” each of which maps to status icons displayed in the user interface.
    7. link_to Creates a link back to the activity on the source system. The link_to field can take an array with a link label along with the URL to customize the display text in the user interface. The default label is “See More”. Following our example, one could display “Deployment Details” in the user interface in place of the default “See More”.

      Let’s return to our deployment example and see how fields are defined in the Data Type Schema:

      // Example Deploy XDS Schema
      {
       "api_version": "1",
       "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
       "custom_schema": {
       "name": "Faux Schema",
       "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
       "schema_version": 2,
       "event_time": "2015-02-02T17:15:32.320Z",
       "fields": ["schema_id", "schema_version", "event_time", "remote_id", 
       "associated_remote_id", "summary", "status_name", "status_type", 
       "link_to", "rule", "deploy_url", "deploy_message"],
        }
      }
      

Note that we’ve included the four mandatory fields, a couple of “stock fields”, and some custom fields modeling our “deploy” specific domain data.

Requiring specific fields - You may impose required fields. Remember that some fields are always required, so this section is not optional for that reason. But you can extend the set of required fields beyond those required by the API.

  1. required Pass in an array of required fields. Any activity message without all of these fields will be discarded. Let’s return to our deploy example and see how fields are defined in the Data Type Schema:

    // Example Deploy XDS Schema
    {
        "api_version": "1",
        "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
        "custom_schema": {
        "name": "Faux Schema",
        "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
        "schema_version": 2,
        "event_time": "2015-02-02T17:15:32.320Z",
        "fields": ["schema_id", "schema_version", "event_time", "remote_id", 
        "associated_remote_id", "summary", "status_name", "status_type", 
        "link_to", "rule", "deploy_url", "deploy_message"], 
       "required": ["schema_id", "schema_version", "event_time", "remote_id", "rule"],
      }
    }
    

    The four fields required by the API are represented, along with one additional field we added above named “rule”. Any activity message that fails to supply all five of these fields will be discarded.

Select “important” fields that result in activity stream posts - Not every event that triggers an activity message is necessarily worthy of a post in the activity stream. List only those fields that you deem worth of an activity stream update in the “important” field.

  1. important Array of field names. Only changes to these fields will trigger a new entry in the activity stream. In this case, we only want changes to the “summary” or “status_name” field to trigger activity stream posts:

    // Example Deploy XDS Schema
    {
       "api_version": "1",
       "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
       "custom_schema": {
       "name": "Faux Schema",
       "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
       "schema_version": 2,
       "event_time": "2015-02-02T17:15:32.320Z",
       "fields": ["schema_id", "schema_version", "event_time", "remote_id", 
       "associated_remote_id", "summary", "status_name", "status_type", 
       "link_to", "rule", "deploy_url", "deploy_message"], 
       "required": ["schema_id", "schema_version", "event_time", "remote_id", "rule"],
      "important": ["summary", "status_name"],
      }
    }
    

    Parse certain fields for TeamForge object references - Say you have a field that often contains a reference to a tracker artifact and you want EventQ to automatically convert those into links. An association will also be created if EventQ is aware of the referenced object.

In addition, any URL reference will be converted to a HTML link in the EventQ user interface. Say, www.example.com is referenced in a “parse” field, then it will be converted to a HTML link, e.g. www.example.com

  1. parse Array of field names. Converts any TeamForge object references to links, converts URL references to links.

    // Example Deploy XDS Schema
    {
       "api_version": "1",
       "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
       "custom_schema": {
       "name": "Faux Schema",
       "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
       "schema_version": 2,
       "event_time": "2015-02-02T17:15:32.320Z",
       "fields": ["schema_id", "schema_version", "event_time", "remote_id", 
       "associated_remote_id", "summary", "status_name", "status_type", 
       "link_to", "rule", "deploy_url", "deploy_message"], 
       "required": ["schema_id", "schema_version", "event_time", "remote_id", "rule"],
       "important": ["summary", "status_name"],
       "parse": ["deploy_message"],
      }
    }
    

By adding “deploy_mesage” to the “parsed” field, any CTF object will be linked and possibly associated. Any web addresses referenced will also be converted to a full HTML link.

Register your schema with EventQ - Now that your new schema is formulated, register your schema with your EventQ instance using either:

 * **eventq.custom message queue**, or
 * **XDS Schema HTTP API** (see `/api/1/docs/http_api_xds_schema`)

There is no preferred method for schema registration; pick the method that works best for your integration scenario. Registered schemas may be used site-wide. In our deploy example, perhaps we’ve written an extension to our deploy product and have registered its schema. The same schema may be reused by multiple sources (e.g., multiple instances of the deploy product) across the site.

Note also that successive submissions of the same schema ID and version will be ignored and it is a safe practice to send the same schema multiple times if it is programmatically convenient to do so.

To modify a schema, increment the schema_version value and re-register the schema with EventQ using the methods described above.

  1. Success You can use the XDS Schema HTTP API (see /api/1/docs/http_api_xds_schema) to inspect registered schemas and their versions.

  2. Troubleshooting Check the server log “custom_queue.log” to see if the schema was rejected and why it was rejected.

Send Activity messages - Now that you’ve defined an API for your tool/domain you can start supplying activity messages to EventQ that coincide with your new schema. For a technical reference on crafting activity messages, see the XDS Schema API documentation.

  1. Submit XDS Activity messages to eventq.custom queue Note that the activity stream will only reflect new entries when an “important” field is modified or set in an activity message.

    // Example Deploy XDS Activity Message
    {
      "api_version": "1",
      "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
      "custom_data": {
     //required fields
      "name": "Faux Schema",
      "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
      "schema_version": 2,
      "event_time": "2015-02-02T17:15:32.320Z",
      "remote_id": "deploy-1234",
      "rule": "1 comes before 2",
     // stock fields
      "summary": "Deploy at 4:52pm on a Friday",
      "deploy_message": "Deploying to fix [artf12345] and [artf12346] as critical bugs.",
      "associated_remote_id": "b4c8e50c908ade5c6f053e1ef6422f88",
      "link_to": ["Deploy Details", "http://www.example.com/deploy/deploy-1234"],
      "status_type": "open",
     // other custom fields
      "environment": "Dev Stage 1"
      }
    }
    

Optional Features - The XDS API offers some optional features to help pretty things up and make life a bit easier.

  1. Interpolate TeamForge URLs

    It may be desirable to create URL references to TeamForge pages or functions (like SSO authentication). There are two interpolation functions in XDS:

    Reference TeamForge base URLs: %CTF_BASE_URL%

    Reference TeamForge “Go” URLs: %CTF_GO_URL%

    In our example, we may wish to reference a TeamForge Go URL like so:

    // Example Deploy XDS Activity Message
    ...
    "summary": "Deploy at 4:52pm on a Friday. See %CTF_GO_URL%/page1001",
    
  2. Control field visibility Say you wanted to load specific data into EventQ’s database for reporting purposes, but you don’t want to expose all of those fields in the user interface. The solution is to add those fields to the hidden array in the XDS Schema message. The hidden array takes only custom fields (optional, non-stock). Custom fields are visible by default.

    Continuing our example, the newly introduced “environment” and “authorized_by” custom fields will be stored in the EventQ database, but not exposed in the user interface:

    // Example Deploy XDS Schema
    {
       "api_version": "1",
       "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
       "custom_schema": {
       "name": "Faux Schema",
       "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
       "schema_version": 2,
       "event_time": "2015-02-02T17:15:32.320Z",
       "fields": ["schema_id", "schema_version", "event_time", "remote_id", "associated_remote_id", 
       "summary", "status_name", "status_type", "rule", "deploy_url", "deploy_message",
       "environment", "authorized_by"],
       "required": ["schema_id", "schema_version", "event_time", "remote_id", "rule"],
       "important": ["summary", "status_name"],
       "parse": ["deploy_message"],
       "link_to": ["deploy_url"],
       "hidden": ["environment","authorized_by"]
      }
    }
    

XDS Schema API

Submission Parameters

Submission Queue
  • queue_name: eventq.custom
  • auto_delete: false
  • durable: true
Top-Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Optional A key generated by TeamForge EventQ that links incoming work items with the appropriate source server. (Optional)
Example: "source_association_key": "kLM56uWtKAqpeLLm5qJF"
custom_schema Required a schema for the XDS events.
Objects

custom_schema - The fields specified below define the schema that activities will conform to.

Field Required/Optional Description
name Required A visible name that will allow pipeline-creators to recognize this schema when populating a pipeline.
schema_id Required A unique id defining this schema. Every activity sent by a single adapter should reference the same schema id. If this changes, the data source is considered a new data source, and data will not populate into pipelines that listened for the old one. If the schema changes, you can use the version to show that it's intended to be parsed differently, but continue to deliver messages to existing pipelines.
Example: "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0"
schema_version Required A string to uniquely identify the work item.
Example: "schema_version": 1
event_time Required A string containing a timestamp in UTC timezone and RFC 3339 format.
Example: "event_time": "2012-10-02T17:15:32.320Z"
fields Required A string to summarize the work item.
Example: "fields": ["schema_id", "schema_version", "event_time", "remote_id", "assigned_to", "hours_played", "severity", "canary"]
required Required A longer string that can be used to further describe the work item.
Example: "required": ["schema_id", "schema_version", "event_time", "remote_id"]
important Optional A string to uniquely identify the status. This value must match the identifier within the work item configuration message.
Example: "important": ["assigned_to", "severity"]
parsed Optional A string to uniquely identify the tracker. This value must match the identifier within the work item configuration message.
Example: "parsed": ["description"]
hidden Optional A boolean for the open or closed state of the work item. True if the work item is closed.
Example: "hidden": ["comment"]
Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON

{
    "api_version": "1",
    "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
    "custom_schema": {
      "name": "Faux Schema",
      "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
      "schema_version": 2,
      "event_time": "2012-10-02T17:15:32.320Z",
      "fields": ["schema_id", "schema_version", "event_time", "remote_id", "associated_remote_id", "title", "rule", "deploy_url", "deploy_message", "comment"],
      "required": ["schema_id", "schema_version", "event_time", "remote_id", "rule"],
      "important": ["rule"],
      "parsed": ["deploy_message"],
      "hidden": ["comment"]
    }
}

XDS Activity API

Submission Parameters

Submission Queue
  • queue_name: eventq.custom
  • auto_delete: false
  • durable: true
Top Level
Parameter Required/Optional Description
api_version Required A string that matches the API version this document is for.
source_association_key Required A key generated by TeamForge EventQ that links incoming work items with the appropriate source server.
Example: "source_association_key": "kLM56uWtKAqpeLLm5qJF"
custom_data Required The object containing custom activity data conforming to the referenced schema/version.
Objects

custom_data - The fields specified below conform to the schema referenced, and provide activity information to EventQ:

Field Required/Optional Description
schema_id Required The identifier of the XDS schema this message conforms to. The schema needs to be sent before an activity referencing that schema is sent.
schema_version Required The version of the referenced schema this message conforms to.
event_time Required The identifier of this activity; this is used to collapse related activities together.
remote_id Required A string to summarize the work item.
Stock Fields Optional
The following field names are treated specially by EventQ, allowing a developer to show specific data in our UI where it can fit with our display patterns. All the fields are optional.
  • associated_remote_id - Specify the singular ID or array of IDs that your event should associate with, these IDs will be searched for in the source chosen in the pipeline custom source and shown in the Association section of the Details page.
  • created_by - The username or email address of the person who took the action. This is shown in the Details page.
  • updated_by - The username or email address of the person who took an action. This is shown in the Details page.
  • summary - The main title of the event. Shown in bold at the top of the Details page and also in the Activity Stream.
  • description - Detailed description of the event. Shown in full in the Details page, a truncated version is shown in the Activity Stream.
  • status_name - The name of the current status. This is a text field that is displayed in the Details page and Activity Stream. The value should be representational of the current state of the activity and match with the status_type. status_type - The type of status icon to show, containing values of "open", "success", "failed", each of which maps to a status icon displayed in the user interface.
  • link_to - The link back to the event on the source system. It take an array or single string. Array takes a URL along with the link label to customize the display text in the user interface. If only a URL string is passed without the label, the default label is "See More".
Custom Fields Optional These custom fields can only contain String data and will be displayed in a key value list in the Details page.
Examples

The following code examples are Copyright 2015 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]

Sample Submission JSON 1: A deploy example with string value for link_to field

{
    "api_version": "1",
    "source_association_key" : "8578c900-f8df-0131-84ff-3c07547a48b0",
    "custom_data": {
        //required fields
        "schema_id": "fc358dd0-11dc-0132-b9fe-3c07547a48b0",
        "schema_version": 2,
        "event_time": "2012-10-02T17:15:32.320Z",
        "remote_id": "deploy-1234",
        // stock fields
        "created_by": "Build-bot",
        "updated_by": "Deploy-bot",
        "summary": "Deploy at 4:52pm on a Friday",
        "description": "Deploying to fix [FOO-245] and [BAR-900] as critical bugs.",
        "associated_remote_id": "b4c8e50c908ade5c6f053e1ef6422f88",
        "link_to": "http://www.example.com/deploy/b4c8e50c908ade5c6f053e1ef6422f88",
        "status_name": "Deploying",
        "status_type": "open",
        // custom fields
        "environment": "production",
        "branch": "master"
    }
}

Sample Submission JSON 2: A build example with array value for the link_to field

{
    "api_version": "1",
    "source_association_key" : "1ebbbef0-2025-0132-8f68-3c15c2d51622",
    "custom_data": {
        //required fields
        "schema_id": "5193ca40-2025-0132-8f68-3c15c2d51622",
        "schema_version": 1,
        "event_time": "2012-10-02T17:15:32.320Z",
        "remote_id": "build-1234",
        // stock fields
        "created_by": "Build-bot",
        "updated_by": "Deploy-bot",
        "summary": "Build successful!",
        "description": "Build containing commits 109 through 112",
        "associated_remote_id": ["109","110","111","112"],
        "link_to": ["http://www.example.com/build/build-1234", "Build-1234"],
        "status_name": "Success",
        "status_type": "success",
        // custom fields
        "tests_passed": "1400",
        "tests_failed": "0",
        "tests_pending": "23"
    }
}

Reporting API

Overview

TeamForge EventQ Reporting API provides a means to query activity data in TeamForge EventQ. This API is for data retrieval only.

  • Submission URL: https://<eventq_hostname>/orc/api/<version>/reporting.
  • Method: POST (only).
  • Authentication: Requires a valid TeamForge session id.
  • Authorization: Requires the TeamForge EventQ “EventQ READ”, “REPORTING API” permission, or site admin permissions.

Convention

API requests are constructed from two building-blocks: commands with parameter(s) that can be chained one after another, followed by a single return type with its parameter(s). As such, API requests take the form:

command parameter(s)
command parameter(s)
command parameter(s) ...
return type parameter(s)
  • Each chained command is treated as an “AND” query filter.
  • Use separate queries to approximate “OR” requests.
  • Requests are limited to a single return type which must be supplied after the last command.
  • A query itself is a String constructed by chaining commands each separated from the next (or return) by a new line ‘\n’.
    • This ‘\n’ is very important since the parser looks for this when tokenizing the query.

Authentication and Authorization

In order to use the reporting api, your reporting client must have access to the endpoint of your TeamForge instance.

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.

To gain access to the Reporting API the user must have one either of the below permissions set in TeamForge:

  • TeamForge SITE ADMINISTRATOR
    • This will provided access to all active projects in EventQ.
  • REPORTING API EventQ Permissions on at least one project
    • This limits the projects to query against to only those which the user has REPORTING API permissions.
    • If the user is both SITE ADMIN and REPORTING API, SITE ADMIN will be used. There is no way to limit a SITE ADMIN’s access.

See the Examples below for a simple Java client.

Commands and Parameters

Command Description
restrict_to (string) Filter query results for certain classes of activity objects.
Example: restrict_to reviews
Accepted values: builds, commits, reviews, work_items, custom.
associated_to (array) Takes one or more object IDs and returns a list of activity summaries with associations to the object IDs specified.
Example: associated_to ["artf1002", "artf1002", "artf1003"]
associations (none) Used in command chains to modify query results to return associations. No parameters.
Example: associations
in_project (array) Restrict query results to activities in a given project. Takes array of project IDs as a parameter.
Example: in_project ["proj1123", "proj1134"]
sort_by (array) Sort the result set by the fields of the objects which are supplied as a parameter, ascending or descending order.
Example: sort_by ["status", "asc"]
Accepted values: any object field; see MQ API docs for object descriptions or XDS schema for custom objects. For instance, builds may be sorted by remote_id, status, test_results, duration, created_by, or time_created.
Accepted values: asc, desc
has_any (string) Filter query results to those activities that have matching class associations.
Example: has_any "builds"
Accepted values: builds, commits, review, work_items, custom.
has_none (string) Filter query results to those activities that do not have matching class associations.
Example: has_none "reviews"
Accepted values: builds, commits, review, work_items, custom.
limit (integer) Limit query results to the specified integer for pagination of results and performance. May be used in conjunction with offset.
Example: limit 100
Accepted values: positive integers.
offset (integer) Offset query results to specified integer for pagination of results and performance. May be used in conjunction with limit.
Example: offset 10
Accepted values: positive integers.
before (date/time) Filter results set to those activity summaries with events that occurred prior to the supplied date and time. May be used in conjunction with after.
  • Example: before 2014-10-02T17:15:45.320Z
  • Example: before 2.weeks.ago
Accepted values: RFC 3339 format date times in UTC and Ruby-style date references (minutes, hours, days, weeks, months, years).
after (date/time) Filter results set to those activity summaries with events that occurred after the supplied date and time. May be used in conjunction with before.
  • Example: after 2014-11-02T12:45:45.320Z
  • Example: before 1.day.ago
Accepted values: RFC 3339 format date times in UTC and Ruby-style date references (minutes, hours, days, weeks, months, years).
tagged_as (array) Filter results set to those activities from sources labeled with the supplied tag. Takes multiple tags to create an OR condition. Two or more tagged_as commands may be chained which constructs an AND condition, returning only those activities with tag A and tag B.
Example: tagged_as ["deploy","binary repository"] tagged_as ["production"]

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 2015 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());
      }

      }
    }

Efficient Querying with the EventQ Reporting API

Here’s a few guidelines for building efficient EventQ Reporting API queries.

Cutting vs Building

Unlike a SQL query, which connects separate tables together to form a result, the EventQ Reporting API starts with the full set of all activities, and is cut down to the size of the result by successively applying query restrictions. This difference makes query optimization quite different between SQL and NoSQL.

Ordering Guidelines

Some query commands will result in larger reductions to the than others. This of course also depends on the range applied to the query. In example: Restricting to a week of activities using “after 1.week.ago” will make a very small set of activities to work on, compared to “after 1.year.ago” which will include a large number of activities. In general however, the commands here are listed by most efficient to least efficient in scoping the query result:

  • Good:
:before ,  type :  :time
:after ,  type :  :time
:restrict_to ,  type :  :choice ,  choices :  %w(builds commits reviews work_items custom)
:in_source ,  type :  :json
:in_repository ,  type :  :string
:in_project ,  type :  :json
  • Mid:
:associated_to ,  type :  :json
:tagged_as ,  type :  :json
:offset ,  type :  :integer
  • Poor:
:associations
:field_contains ,  type :  :json
:sort_by ,  type :  :json
:has_any ,  type :  :string
:has_none ,  type :  :string
  • Returning command (must be run last):
:limit ,  type :  :integer
:timeseries ,  type :  :duration
:group_by_field ,  type :  :string
:fields ,  type :  :json
:count

Use Cases and Examples

:in_project ["proj1211"]
after 14.days.ago
restrict_to commits
field_contains ["settled",[true]]
has_any "reviews"

Exceptions in ordering and other exceptional behaviours to note

  • Limit: The limit command is best used at the end of the set. Using it before the end can result in more than the limit of items being returned at the end of the query.

  • Tagged_as: Is specifically for custom activities.

HTTP APIs

HTTP API for XDS Schema Creation and Viewing

Overview

  • TeamForge EventQ HTTP API for XDS Schema provides a means to create an XDS schema or view a schema and its versions. The API supports both data retrieval and submission.
  • Authentication: requires a valid TeamForge session id, passed with the ‘X-EventQ-Session’ header field. One way to acquire this session id is to programmatically log into TeamForge using TeamForge SOAP API.
  • Authorization: requires the TeamForge EventQ “EventQ CREATE” permission, or site admin permissions for creating schema. No permission required for viewing schema.

Convention

API requests for viewing and creating schemas are constructed as detailed below.

  • List all schemas
    • Request Type: GET
    • Request URL: https://<eventq_hostname>/api/1/schemas
    • Return Format: Array of JSON objects. Each of the JSON object is a schema.
  • List all schemas with a same schema_id

    • Request Type: GET
    • Request URL: https://<eventq_hostname>/api/1/schemas/SCHEMA_ID

    • Requires Parameter: SCHEMA_ID
    • Return Format: Array of one or more JSON object(s). Each of the JSON object is a schema with the given schema_id and all the versions.
  • Get one schema

    • Request Type: GET
    • Request URL: https://<eventq_hostname>/api/1/schemas/SCHEMA_ID/VERSION

    • Requires Parameter: SCHEMA_ID, VERSION
    • Return Format: Array with one JSON object. The JSON object is a schema with the given schema_id and given version.
  • Create a schema

    • Request Type: POST
    • Request URL: https://<eventq_hostname>/api/1/schemas
    • Return Format: An encoded (escaped) URL. This URL can be used to view the schema once it has been processed and saved.

TeamForge EventQ HTTP API for Tool Creation and Viewing

Overview

  • TeamForge EventQ HTTP API for Tool provides a means to create an Tool or view a tool. The API supports both data retrieval and submission.
  • Authentication: requires a valid TeamForge session id, passed with the ‘X-EventQ-Session’ header field. One way to acquire this session id is to programmatically log into TeamForge using TeamForge SOAP API.
  • Authorization: requires the TeamForge EventQ “EventQ CREATE” permission, project admin, or site admin permissions.

Convention

API requests for viewing and creating tools are constructed as detailed below.

  • List all tools

    • Request Type:
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools
    • Return Format:

      {
         "tools": [
         {
          "id": "unique_tool_id_1",
          "name": "Sample tool name One",
          "service_name": "Sample service name One",
          "project_id": "project id ",
          "active": true,
          "source_ids": [
      
           ]
         },
         {
          "id": "unique_tool_id_2",
          "name": "Sample tool name two",
          "service_name": "Sample service name two",
          "project_id": "project id ",
          "active": true,
          "source_ids": [
          "SourceID1",
          "SourceID2"
           ]
         }
        ]
      }
      
  • Return Codes

    • Success: 200
    • Error: 404, 503
  • Get one tool

    • Request Type: GET
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID
    • Return Format:

      {
        "tool": {
        "id": "TOOL_ID",
        "name": "Sample tool name two",
        "service_name": "Sample service name two",
        "project_id": "project id ",
        "active": true,
        "source_ids": [
          "SourceID1",
          "SourceID2"
         ]
       }
      }
      
  • Return Codes

    • Success: 200
    • Error: 404, 503
  • Create a tool

    • Request Type: POST
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools
    • Requires Parameter: PROJECT_URL_NAME
    • Request body:

      {
        "tool": {
        "name": "Sample tool name two",
        "source_ids": [
        "SourceID1",
        "SourceID2"
          ]
        }
      }
      
  • Return Format:

{
  "tool": {
    "id": "unique_tool_id_x",
    "name": "Sample tool name two",
    "project_id": "project id ",
    "active": true,
    "source_ids": [
      "SourceID1",
      "SourceID2"
    ]
  },
  "errors": {
    "base": [
      "error msg"
    ],
    "attribute_key": [
      "error msg"
    ]
  }
}
  • Return Codes

    • Success: 200
    • Error: 404, 503, 422
  • Update a tool

    • Request Type: PUT
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID
    • Requires Parameter: PROJECT_URL_NAME, TOOL_ID
    • Request body:

      {
        "name": "Tool New Name",
        "source_ids": [
        "sourceID3"
       ]
      }
      
  • Return Format:
    {
    "errors": {
      "base": [
        "error msg"
      ],
      "attribute_key": [
        "error msg"
      ]
    }
    }
    
  • Return Codes

    • Success: 200
    • Error: 404, 503, 422
  • Activate a tool

    • Request Type: PUT
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID/activate
    • Requires Parameter: PROJECT_URL_NAME, TOOL_ID
    • Return Format:

      {
         "errors": {
         "base": [
            "error msg"
         ],
         "attribute_key": [
          "error msg"
        ]
       }
      }
      
  • Return Codes

    • Success: 200
    • Error: 404, 503, 422
  • Deactivate a tool

    • Request Type: PUT
    • Request URL: https://<eventq_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID/deactivate
    • Requires Parameter: PROJECT_URL_NAME, TOOL_ID
    • Return Format:

      {
        "errors": {
         "base": [
           "error msg"
         ],
        "attribute_key": [
           "error msg"
        ]
       }
      } 
      
  • Return Codes

    • Success: 200
    • Error: 404, 503, 422

HTTP API for Source CRUD

Overview

  • TeamForge EventQ HTTP API for Sources provides a means to create or view a source. The API supports both data retrieval and submission.
  • Authentication: requires a valid TeamForge session id, passed with the ‘X-EventQ-Session’ header field. One way to acquire this session id is to programmatically log into TeamForge using TeamForge SOAP API.
  • Authorization: requires the EventQ “EventQ CREATE” permission or TeamForge’s project-admin / site-admin permissions.

Convention

API requests for viewing and creating sources are constructed as detailed below.

  • List all sources by Project

    • Request Type: GET
    • Request URL: https:///api/stable/projects/PROJECT_URL_NAME/sources
    • Return Format:

      {
         "sources": [
           {
             "id": "5578cd1c0fbb6ad771000001",
             "_type": "Build",
             "tool_id": "552c3736c69d3b3dfb000004",
             "active": true,
             "display_name": "Sample_Build_Source",
             "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
             "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
             "queue_server": "amqp://rabbitmqserver.example.com:5672",
             "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
             "associated_commit_server_id": "551d8560c69d3b474b000102"
           }
         ]
      }
      
    • Return Codes

      • Success: 200
      • Error: 404, 503
  • List all sources by Tool

    • Request Type: GET
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/tools/TOOL_ID/sources
    • Return Format:

      {
        "sources": [
         {
           "id": "5578cd1c0fbb6ad771000001",
           "_type": "Build",
           "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample_Build_Source",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "associated_commit_server_id": "551d8560c69d3b474b000102"
         }
        ]
       } 
      
  • Create a source

    • Request Type: POST
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources
    • Request body:

      Required: _type, display_name

      {
         "source": {
         "_type": "Build",
         "tool_id": "552c3736c69d3b3dfb000004",
         "display_name": "Sample_Build_Source",
         "associated_commit_server_id": "551d8560c69d3b474b000102"
        }
      }
      
    • Return Format:

      {
        "source": {
        "id": "5578cd1c0fbb6ad771000001",
        "_type": "Build",
        "tool_id": "552c3736c69d3b3dfb000004",
        "active": true,
        "display_name": "Sample_Build_Source",
        "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
        "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
        "queue_server": "amqp://rabbitmqserver.example.com:5672",
        "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
        "associated_commit_server_id": "551d8560c69d3b474b000102"
         },
         "errors": {
         "base": [
           "error msg"
         ],
         "attribute_key": [
         "error msg"
         ]
        }
      }
      
    • Return Codes

      • Success: 200
      • Error: 404, 503, 422
  • Get one source

    • Request Type: GET
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID
    • Return Format:

      {
         "source": {
         "id": "5578cd1c0fbb6ad771000001",
         "_type": "Build",
         "tool_id": "552c3736c69d3b3dfb000004",
         "active": true,
         "display_name": "Sample_Build_Source",
         "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
         "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
         "queue_server": "amqp://rabbitmqserver.example.com:5672",
         "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
        "associated_commit_server_id": "551d8560c69d3b474b000102"
        }
      }
      
    • Return Codes

      • Success: 200
      • Error : 404, 503
  • Update one source

    • Request Type: PUT
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID
    • Request body:

      {
        "tool_id": "552c3736c69d3b3dfb000004",
        "display_name": "Sample_Build_Source",
        "associated_commit_server_id": "551d8560c69d3b474b000102"
      }
      
    • Return Format:

      {
        "errors": {
         base": [
          "error msg"
         ],
        "attribute_key": [
          "error msg"
         ]
        }
      }
      
    • Return Codes

      • Success: 200
      • Error: 404, 503, 422
  • Activate one source

    • Request Type: PUT
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID/activate
    • Return Format:

      {
        "errors": {
        "base": [
          "error msg"
        ],
        "attribute_key": [
        "error msg"
        ]
       } 
      }
      
    • Return Codes

      • Success: 200
      • Error: 404, 503, 422
  • Deactivate one source

    • Request Type: PUT
    • Request URL: https://<ctf_hostname>/api/stable/projects/PROJECT_URL_NAME/sources/SOURCE_ID/deactivate
    • Return Format:

      {
         "errors": {
         "base": [
           "error msg"
         ],
         "attribute_key": [
           "error msg"
         ]
        }
      }
      
    • Return Codes

      • Success: 200
      • Error: 404, 503, 422

Return Types

The source objects have a set of common fields, while some of the fields depend on the _type of the source. The examples below show the type of source and the expected structure of the returned objects.

  • Source Type: Build
{
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "Build",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample_Build_Source",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "associated_commit_server_id": "551d8560c69d3b474b000102"
         }
      }
  • Source Type: Commit
{
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "Commit",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample_ExternalRepository",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "repository_uri": "ssh://sample_gitserver/sample_project"
         }
      }
  • Source Type: CommitCTF
{
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "CommitCTF",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "ctf_id": "cmmt1234",
          "display_name": "Sample_ExternalRepository",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "repository_uri": "ssh://sample_gitserver/sample_project"
         }
      }
  • Source Type: XDS
{
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "XDS",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample Custom Activity Name One",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "associated_activity_source_id": "55429d045667ba223e000010",
          "activity_source_tag_names": ["Exclusive", "Limited", "Sample"],
          "background_color_value": "#61c0e5",
          "icon_uri": "/sample_icons/custom_source/Sample_Icon_White_12.png"
          "custom_schema_store_id": object.custom_schema_store_id
        }
      }
  • Source Type: Review
{
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "Review",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample Review server Name One",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "commit_association_prefix": "Review"
        }
      }
  • Source Type: WorkItemSource
{
        "source": {
          "id": "5578cd1c0fbb6ad771000001",
          "_type": "Review",
          "tool_id": "552c3736c69d3b3dfb000004",
          "active": true,
          "display_name": "Sample Work Item Name One",
          "queue_username": "4d4eaf60-f1f9-0132-4687-185aeb8b25b8",
          "queue_password": "d70bc954b64e368f1f650bfeaba2e2ff6e5525774ae42f9a959f4ccf2314e9cb",
          "queue_server": "amqp://rabbitmqserver.example.com:5672",
          "source_association_key": "29bf0c90-3b40-0130-ae2d-dddd5893",
          "associated_commit_server_id": "551d8560c69d3b474b000102"
         }
      }

Validations

The following constitute the validations that are performed for the API request-response parameters.

  • _type

    • type: string
    • present for all sources
    • must be one of: Commit, CommitCTF, WorkItem, CustomActivity, Review, Build, XDS
  • active

    • type: boolean
    • present in all sources
    • must be true or false
    • default value: true
  • associated_activity_source_id

    • type: string
    • attribute in XDS, need not be present
    • references an existing activity source if present
  • commit_association_prefix

    • type: string
    • attribute in Review, must be present
    • must be unique
    • key length must be less than 101
  • activity_source_tag_names

    • type: array with string elements
    • attribute in XDS, need not be present
  • background_color_value

    • type: string
    • attribute of XDS, must be present
    • must be a valid RGB value or a HTML5 color name
  • associated_commit_server_id

    • type: string
    • attribute in Build and WorkItem, need not be present
    • must be associated with a valid commit server if present
  • custom_schema_source_id

    • type: string
    • attribute in XDS, need not be present
    • must be associated to an existing custom_schema_source if present
  • display_type

    • type: string
    • must be present in all sources
    • maximum length less than 101
  • icon_uri

    • type: string
    • attribute of XDS, need not be present
    • has the default value: “/assets/icons/custom_source/PNG_White/CN_Icon_White_12.png”
    • must be a valid uri if present
  • repository_uri

    • type: string
    • must be present in Commit and CommitCTF
    • must be a valid uri if present
    • must be a valid protocol (http, https, ssh, git) if present
  • ctf_id

    • type: string
    • must be present in CommitCTF
    • must be a valid ctf id if present
  • source_association_key

    • type: string in all sources
    • must be present
  • tool_id

    • type: string
    • need not be present or present in any source
    • must be associated with a valid tool if present