Confluence
The Confluence integration lets Q247 measure the effort put into documentation. Pages and comments are analyzed the same way as code and tickets, and their calorie score is added to the author's totals. Confluence also appears as a source type in the Sources list, identified by space key rather than the project key used in Jira.
This integration does not feed Flow Metrics. Those require Jira, because they are calculated from the ticket status history.
The data path to Q247
The mechanism is shared with Jira: events flow as webhooks from Confluence to the Enterprise Plugin, the content is analyzed locally, and the result goes to Q247. Without a working webhook the integration delivers nothing, because there is no fallback mode of periodic space scanning.
The plugin reacts to three events:
| Event | What it covers |
|---|---|
page_created | creating a page |
page_updated | updating a page |
comment_created | adding a comment |
In the On-Premise variant, updating a page has an additional condition: it only counts when the reason for the change was an actual edit to the content. Moving a page between spaces or changing permissions generates no entry in Q247.
Cloud and On-Premise
The split is the same as with Jira, and for the same reason. The Cloud variant routes events to a receiver on the Q247 side, the On-Premise variant to the plugin at the address given in the form. In Q247 forms the variants are named "Confluence Cloud" and "Confluence On-Premise"; Atlassian calls the second one Confluence Data Center.
Data available after activation
- The calorie score of pages and comments, added to the author's totals alongside code and tickets.
- A source of the Confluence type in the Sources list, assignable to a Q247 project by space key.
- Visibility of the contribution of people working on documentation, without commits in repositories. Without this integration their work does not appear in Q247 metrics.
Prerequisites
- A service account in Confluence with read permission on the spaces covered by the integration.
- An API token generated on that account. In Atlassian Cloud this is the same token that serves Jira, so if the Jira connector already works, you can simply reuse it. The generation paths are described on the Jira page.
- Confluence administrator access, once: to install the Q247 app (Cloud) or register the webhook (On-Premise).
- The Q247 app installed in the Atlassian site, for the Cloud variant only. If it was installed while setting up Jira, you do not need to install it a second time, because one link covers both products.
- The Q247 plugin with Confluence support enabled, configured by the Q247 deployment team, see Enterprise Plugin installation.
The network requirements match those described for Jira: outgoing traffic from the plugin to Confluence and to Q247, and in the On-Premise variant additionally traffic from the Confluence instance to the plugin.
The instance must have Administration → General Configuration → User List → Show user email addresses to all users enabled. When this option is off, the plugin cannot read the author's address and substitutes a placeholder one. The integration then appears to work correctly: pages are processed, the connector status shows Operational, and the contribution gets attributed to nonexistent people. No message warns about this.
Step-by-step setup
1. Creating the connector in Q247
In Configuration, in the Documentation section, next to the Confluence entry, the "+" button by the Connectors list opens a two-step form.
The Cloud variant requires a site address and credentials:
| Field | What it does | Example |
|---|---|---|
| Connector Name | your own name to recognize it in the list | Confluence firmowy |
| Atlassian Site URL | the base address of the site in Atlassian Cloud | https://firma.atlassian.net |
| API Token | the service account credential, the same one used for Jira | ATATT3xFfGF0... or $$ATLASSIAN_TOKEN |
| Account Email | the address of the account the token was generated on | q247-service@company.com or $$ATLASSIAN_USER |
Both credential fields accept an environment variable name with the $$ prefix instead of the value itself, the same as in Jira. If the Jira connector already uses this, you can point at the same variables here, because the token in Atlassian Cloud is shared between both products.
Instead of a site address, the On-Premise variant asks for the instance version and two addresses:
| Field | What it does | Example |
|---|---|---|
| Confluence Version | the instance version, picked from a list | 8.5.6 |
| Confluence Base URL | the address of the Confluence instance | https://wiki.company.com |
| Plugin server URL | the address at which Confluence will see the plugin | https://ep-plugin.company.com |
| Plugin server Port | only when the plugin listens on a non-default port | 8443 |
| API Username | the service account login, optional | leave empty with token authentication |
You can check the instance version in Confluence: the gear icon, then General Configuration, then Administration → System Information. A name with a number is displayed, for example "Confluence 8.5.6".
The plugin server address field works the same way as in Jira and is subject to the same caveat: it only serves to build the webhook address you copy and paste, and Q247 itself never connects to that address.
2a. Cloud variant: connecting the app with the organization
The second step of the form shows the EP Connect API Key field with a "Copy Key" button.
Confluence has its own entry on the Manage apps list, independent of the Jira entry, and a differently named field:
- In Confluence go to the list of installed apps and find Q247.
- Choose Configure.
- Paste the key into the Connect with your existing Q247 account field.
Installing the app itself, if it is not there yet, is described on the Jira page. The same installation link serves both products, and each one is configured separately.
2b. On-Premise variant: webhook in the Confluence instance
The second step of the form shows the EP Webhook URL field with a "Copy URL" button. That address contains a random key belonging to your organization, so handle it like a password.
Registration on the Confluence side:
- The gear icon, then General Configuration.
- In the left panel Settings → Webhooks.
- The Create a WebHook button.
- Fill in the Name field and paste the address into the URL field.
- In the Events section select page created, page updated and comment created.
- Click Test connection. This is the only built-in check on the Atlassian side, and it is worth using before you save.
- Click Save.
The On-Premise connector wizard names the other Atlassian product in its instructions, so it points at the Jira instance. This is the same message error described on the Jira page.
3. Assigning the source to a project
In Sources the "Add Sources" button lets you add a source of the Confluence type, giving the space key and the Q247 project it should belong to. Alternatively you can do this from the project level, through "Assign Source".
One space belongs to one Q247 project. When the documentation of one product is spread across several spaces, enter all their keys in a single form, separated by commas, for example SUPPORT, DOCS, PLATFORM.
The assignment form and the other source types are described in the Sources tab in the project details.
Verification and diagnostics
The connector statuses and the checking order when data is missing are the same as for Jira, with two differences.
First: the connection test button in the Confluence On-Premise webhook form tells you right away whether the instance can reach the plugin at all. This rules out part of the possible causes before you start looking further.
Second: when pages are processed but the contribution does not appear next to the right people, check the email address visibility option described in the prerequisites. This symptom does not look like an integration problem, because the integration is formally working.
Scope of processed data
The page content and its change history are analyzed locally by the plugin. What reaches Q247 is the page identifier, the space key, the URL, the author and the calorie score.
Q247 recognizes the link between a page and a ticket by searching for the ticket identifier in the page content, title and version description. The recognized identifier is passed on to Q247, so a fragment of the page content reaches the backend if it contains a reference to a ticket. Outside this case, the content of pages and comments does not leave the infrastructure the plugin runs in.
The full list of stored fields is described in Enterprise Plugin security.
See also
- Jira: tokens, network traffic and diagnostics described in detail
- Sources: assigning a space to a Q247 project
- Enterprise Plugin installation: enabling the Confluence add-on
- Enterprise Plugin security: the full scope of data exchange