Terminology

Since the domain is quite complex, let’s start with some terminology:

Third-party system - the system we want to integrate with. This document describes integration with a fictional issue tracking system GitTab. The integration discussed here will be able to

• Display a column in Productboard UI allowing users to push PB features to GitTab
• Create a ticket in the third party system based on PB feature data
• Propagate changes from Productboard features to connected GitTab tickets
• Propagate ticket changes back to Productboard

Connection - Link between PB feature and a ticket in the third party system.

Integration column - column in the Productboard UI allows users to initiate a push to the third party system and see the status of the connection. It’s created using the Plugin integration API.

Productboard APIs - Productboard exposes APIs that enable building the integration.

In this document, we will use

• Features API that provides read and write access to PB Features
• Webhooks API that provides notifications in case of feature change
• Plugin integrations API that manages the integration column

Integration configuration - We assume that the integration will allow multiple configurations. For example, connecting different Productboard spaces to different GitTab projects or multiple columns in the Productboard UI allows pushing to different GitTab projects. Configuration management is up to the integration service.

Integration service - In order to connect Productboard and the third party service, we need an integration service that facilitates the actual integration. The integration service will have to perform the following tasks:

• Expose an integration configuration page.
• Store configuration and mapping data.
• Call Productboard and GitTab APIs.
• React to Productboard and GitTab callbacks.
• Expose the integration management page allowing the user to update and delete the integration configuration.

In this article, we assume that the integration service is not a part of the third-party service and that it interacts with both Productboard and the third-party service using APIs. A scenario, where the integration service is more tightly integrated with the third-party service is also possible.

Integration service

The integration service has the following responsibilities.

Integration configuration page

In order to configure the integration, the admin who is configuring the integration has to generate an authentication token in Productboard, an authentication token in GitTab and enter those data into a configuration page. The configuration page may require other data, like GitTab project ID. Once the data are entered, the integration service will

1. Create an integration column in Productboard.
2. Register a webhook in Productboard.
3. Register a notification channel from a third-party service (usually a webhook).
4. Store the data from the configuration page, the ID of the integration and IDs of the created Webhooks for future reference.

Creating integration column in Productboard

In order to add a column to Productboard, the integration service has to call PB Plugin integration API (see the documentation for more details). Once the plugin integration is created, the integration service should store the integration ID it received in the response, this will be used later.

Registering Productboard webhook

In order to get notified about updates in Productboard, the integration service has to register a Webhook using the corresponding API. We recommend adding the integration ID to the notification URL query or path parameter, so the webhook processing endpoint is able to decide to which integration the notification belongs.

Registering a notification channel from a third-party service

If the integration service wants to get notified about updates in the third party service, it needs to register some kind of notification channel. Depending on the system, it can be a webhook or something else.

Push flow

Once the Plugin integration is created in Productboard, a new column will become available in the tasks section on Productboard's feature board. When it’s added to the feature board, users can click the Push button. When a user clicks the button, the integration service gets notified. Productboard will send a HTTP request to the endpoint specified in the Plugin integration API.

1. The integration service uses the integration ID from the notification request to load the integration configuration from the database
2. It fetches feature data using PB Feature API. Feature ID (or URL) is provided in the notification request.
3. The integration service uses feature data to create a new ticket in GitTab.
4. It stores the mapping between the PB feature and GitTab ticket to know which PB ID. corresponds to which GitTab ticket ID.
5. In response to the notification request, it returns the new status of the connection.

Note: This flow should be triggered only when the value of the “trigger” field in the push notification body was button.push.

The Productboard UI will display the new connection between the feature and the GitTab ticket.

It’s also possible to implement asynchronous push flow. The integration service can return a progress connection status as soon as it receives the notification and once the connection is created it can set the connected connection status using the connection API.

Propagation of updates from Productboard

To propagate updates from Productboard to the third-party service, the integration service needs to react to webhook notifications. When a webhook notification is received, the integration service has to

1. Load the integration data based on the integration ID that was added to the webhook notification URI when registering the webhook
2. Fetch the feature data using Feature API
3. Update the GitTab ticket corresponding to the PB feature, using the mapping stored when the connection was created.

Propagation of updates from the third-party system

When the integration service receives a notification that GitTab ticket has been changed, it has to:

1. Load the integration data based on the integration ID it added to the webhook notification URI when registering the webhook.
2. Update the Productboard feature based on mapping stored when the connection was created.

Unlinking

The user can click on an unlink button in the Productboard UI. In this case, the notification endpoint will be called again, this time using the button.unlink trigger (see the Callbacks section in the documentation).

The integration service will have to

1. Use integration ID from the notification request to load the configuration from its database.
2. Remove the link from GitTab.
3. Remove the mapping from its database.
4. Return the connection in the initial state as a response to the callback to remove the connection from PB. See the documentation for details.

Unlinking can happen also due to feature (or GitTab task) deletion. The flow has to be implemented in the integration service based on deletion webhooks.

Integration management

The integration service can provide an integration management page allowing users to manage the integration configurations. When an integration is deleted, the integration service should remove the integration column using Plugin integration API and unregister all related webhooks.