TeamForge Orchestrate 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
Orchestrate 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 Orchestrate 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 in pipelines.
MQ API — Writing your own adapters
Each TeamForge Orchestrate 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 Orchestrate 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 Orchestrate 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
Orchestrate 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 Orchestrate, adapters can send Orchestrate 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 Orchestrate either through the MQ or HTTP API. Please read the Extensible Data Sources (XDS) walk-through and refer to the API documentation below.
Once a Schema is established, "XDS Sources" can be added to pipelines 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 Orchestrate 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.
API documentation
For more detailed documentation on the MQ and XDS APIs, see the API docs:
- Web: TeamForge Orchestrate Community — MQ API, XDS API
- Local: http(s)://<your-orchestrate-hostname>/orc/api/1/docs/index