# Connect Confluence

> Monitor Confluence Cloud without the email digest. Mentions, page edits, new comments, your tasks and any CQL reach your Mac's notch, signed in with the same API token as Jira.

Source: https://coisland.app/docs/connect-confluence/

## What you need

- **You need:** Atlassian API token, from id.atlassian.com › Security › API tokens (https://id.atlassian.com/manage-profile/security/api-tokens)
- **The form asks:** Confluence site, Connector name, Email, API token
- **You can watch:** Search (CQL), Mentions, Page updates, Comments, Tasks
- **Access:** CQL searches and reads only

To connect Confluence to CoIsland you need your site's address, the email of your Atlassian account and an API token, the same kind Jira Cloud uses. Already connected Jira Cloud? CoIsland can reuse that connector's sign-in. CoIsland calls your site's REST API straight from your Mac, with no CoIsland server or account in between, and keeps the token in your login Keychain. This page covers the token, the connector form, the five Confluence monitor kinds, and the errors you may meet.

## What you need

- **Confluence Cloud:** your site, such as `https://your-team.atlassian.net`. Confluence Data Center and Server are not supported.
- **The email of your Atlassian account**, and an **API token** created for it. CoIsland signs in with basic authentication, email and token.

One API token acts as your account on every product of the site: a token that signs in to Jira Cloud on `your-team.atlassian.net` signs in to Confluence there too, as long as your account can use Confluence.

## Create an Atlassian API token

1. Sign in at [id.atlassian.com › Security › API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Select **Create API token**, not **Create API token with scopes**.
3. Name it after what it is for, such as `CoIsland`.
4. Pick an expiry date, from 1 to 365 days away.
5. Select **Create**, then copy the token.

Why no scopes: Atlassian's scoped tokens are called through `api.atlassian.com/ex/confluence/{cloudId}`, while CoIsland calls your site's own address, so it needs a token without scopes. A token lasts at most a year; when yours expires, checks fail with the token message listed in [Troubleshooting](#troubleshooting-confluence-connector-errors). Only you can create a token for your account.

### When your organization blocks API tokens

An organization admin can block user API tokens in an authentication policy (Atlassian Administration › Security › Authentication policies › User API tokens). A blocked token cannot be created or used, and CoIsland says: **Your organization's admin blocks API tokens for this account. Ask them to allow user API tokens, or connect a personal account.** Only the admin can change it.

## Connect Confluence in CoIsland

Open **Settings › Connectors**, click **+** at the top right (or **Add Connector** when you have none yet), and choose **Confluence**.

The form has two groups, **Site** and **Access**:

| Field | What to enter |
|---|---|
| Reuse Jira connector | Shown when you have a Jira Cloud connector. Pick it to copy its site, email and token: the token goes from its Keychain item to the new one, never through the form. Leave it on **None** to type them. |
| Confluence site | The address you open Confluence at, with `https://`. A pasted page link works. |
| Connector name | What monitors call it, filled in from the site until you type your own: `your-team` for `your-team.atlassian.net`. Letters, digits, `_` and `-`. |
| Email | The Atlassian account the token belongs to. |
| API token | The token you created. |

Then click **Test connector**, which saves nothing. It calls `/wiki/rest/api/user/current` with the token. A success reads **Connected**, with your name, your email, Confluence Cloud and the host.

Click **Add Connector**. The site and the email go to `~/Library/Application Support/CoIsland/connectors.json`, the token to your login Keychain. The first Confluence connector becomes the default. A reused token is a copy: when you replace the token later, add both connectors again.

## Choose what to watch: the five Confluence monitor kinds

Open **Monitors**, add a monitor and choose **Confluence**. Every kind alerts on what enters its answer, with **Runs on**, **Alert when**, **Check every** (15 minutes by default) and **Sound**. A new-items monitor's first check records what already matches and raises nothing.

### Search (CQL)

Any CQL, as in Confluence's advanced search. A page, blog post, comment or attachment alerts when it starts matching.

```sql
type = page AND space = ENG
  AND created >= now("-7d")
```

Other starting points: `type = blogpost AND created >= now("-7d")`, `label = incident AND lastmodified >= now("-1d")`, and, with **Alert when** set to a count, `space = OPS AND label = runbook AND lastmodified < now("-180d")` for runbooks nobody updated in six months.

### Mentions

Someone @-mentioned you on a page, a blog post or a comment. Pick the spaces (none is every space) and how far back to look, from 1 to 30 days; the editor writes it as `space:ENG within:7d`. Keep the look-back longer than the check interval. A page edited again after it left the look-back comes back as fresh, and alerts again.

### Page updates

A CQL for the pages to follow, such as `watcher = currentUser()`, `space = ENG` or `ancestor = 123456` for a page tree. Each new version alerts, with who made it; several edits between two checks alert once, with the latest. CoIsland adds `type in (page, blogpost)` and `lastmodified >= now("-2d")` unless your CQL says which types or since when. The alert page shows what changed since the version before, then the page.

### Comments

A CQL for the pages whose comments to watch, such as `type = page AND creator = currentUser() AND lastmodified >= now("-30d")`. Each new footer or inline comment of the last 7 days alerts. Keep it to a few pages: a check reads 50 at most, and when more match it compares nothing and asks you to narrow the query.

### Tasks

Inline tasks assigned to you and not done. Pick the spaces, **Assigned and open** or **Overdue only**, and for open tasks how soon they are due. A task alerts when it is assigned to you, and again the day after its due date.

Click **Test** to run a monitor once: nothing is saved or alerted. A search reads up to 500 items; when more match, nothing is compared.

## What a Confluence monitor's watch file looks like

Every monitor is a `.sql` file in `~/.coisland/watches`. The `-- kind:` line names the Confluence kind, and the body is the CQL or the fields:

```sql
-- name: Mentions of me
-- kind: confluence.mentions
-- connector: acme
-- every: 5m
-- alert: new-rows

within:7d
```

The kinds are `confluence.search`, `confluence.mentions`, `confluence.updates`, `confluence.comments` and `confluence.tasks`. [Watch files](https://coisland.app/docs/watch-files/) lists every header key.

## Permissions the Confluence account needs

The account needs Confluence on the site and **View** on the spaces you watch. Confluence returns only what the account can see, so a missing permission shows as fewer results, not an error. CoIsland only reads: it searches, and reads pages, comments and tasks.

## Troubleshooting Confluence connector errors

- **The token was refused. Check it has not expired or been revoked.** Confluence answered 401, or answered as a signed-out user: on sites open to anonymous readers, a wrong token reads as the anonymous user, which CoIsland refuses so a monitor never shows public pages as yours.
- **Confluence on acme.atlassian.net refused this account.** The site answered 403. The token may be wrong, expired or revoked (on a site closed to anonymous readers that reads the same), or the account cannot use Confluence there.
- **Your organization's admin blocks API tokens for this account.** See [When your organization blocks API tokens](#when-your-organization-blocks-api-tokens).
- **acme.atlassian.net does not answer as a Confluence Cloud site.** Check the address; CoIsland never follows redirects.
- **Confluence refused the query:** then Confluence's reason, such as a misspelled type. Fix the CQL in Confluence's advanced search, then paste it back.
- **No space ENG on this site.** A Mentions or Tasks space key does not exist. Keys are case-sensitive.
- **This page is no longer on Confluence, or no longer visible to you.** On an alert: the page was deleted, trashed or moved out of your reach. The alert keeps what it saved.

## Common questions

### Can I use my Jira API token for Confluence?

Yes, on the same Atlassian Cloud site. Pick your Jira connector under **Reuse Jira connector**.

### Does CoIsland work with Confluence Data Center?

No, only Confluence Cloud.

### Can CoIsland change my Confluence pages?

No. It only reads. The token stays in your login Keychain and goes only to your Confluence site.

Next: [Getting started](https://coisland.app/docs/getting-started/), or the [Confluence connector](https://coisland.app/confluence/) for everything it can watch.