Confluence

Changelog

1. 0.10.0

   Confluence 0.10.0: the wiki to read is a Confluence connection

   Confluence used to be configured on the plugin's own page: a url, an email and a token. That meant one wiki per workspace, and its token typed into a plugin setting rather than kept where a workspace keeps hosts.

   The plugin now brings a connection kind of its own, Confluence. Add one with the wiki's root as the URL - https://your-site.atlassian.net/wiki for Cloud - and point the plugin's confluence parameter at it. Cloud authenticates with Basic and email:token as the secret; Server and Data Center with a Bearer personal access token. Which of the two it is used to be read off whether an email was set, and is now read off the connection's auth kind - so the search and people lookups still pick the right API for each.

   Coming from 0.9: the url, email and token parameters are gone. Make a Confluence connection from them and point confluence at it. This needs a server that hands a plugin's own kind of connection over with its address; on an older one the plugin says so rather than calling nowhere.

2. 0.9.0

   Confluence 0.9.0: a skill for the two steps between a name and a page

   "What has Ada written" and "where is Ada mentioned" look like text searches, and searching for the name is the wrong answer to both. A page stores a mention as an identifier and draws the name from it at display time, so text ~ "Ada Lovelace" finds the pages that happen to type her name and misses every page that mentions her - which are the ones being asked about.

   The plugin has had both halves since 0.8.0 and nothing said they went together. findUsers turns a name into an id, and CQL takes that id in mention, creator, contributor and watcher. Two calls, obvious once somebody knows the id exists and invisible before that, which is exactly what a skill is for: a tool description is read by something that has already decided to call it, and this decision happens a step earlier.

   It also says not to match the id as text. text ~ "5b10ac8d…" sometimes works and is a fallback rather than the tool: the search index holds what a page renders and not always the markup behind it, so it misses pages mention finds. That is the sort of thing somebody discovers at the end of an afternoon rather than at the start of one.

   contributor over creator where the question is what a person has worked on - a page somebody rewrote entirely is still not theirs by creator - and the reverse direction stated, since openPage answering mentions and openUser resolving one makes the pair symmetrical: a person gives you their pages, a page gives you its people, and neither starts from a name.

   Ending where the first skill ends, because it is the same trap: an empty answer is often permissions rather than absence, and the way to tell is a query with nothing to do with people.

3. 0.8.0

   Confluence 0.8.0: find people by name, which no id could answer

   Everything else here takes an identifier. A page carries a mention as a user key, openUser turns that into a person, and the one question left over was the one somebody actually asks out loud: who is Jo Smith. A display name is not an identifier anywhere in Confluence's API, so there was no way in from a name at all.

   findUsers is that way in. It matches on the full name the way the people directory does, so a fragment is enough, and it answers people carrying the ids every other call here takes - which makes it the front door to openUser rather than a second way of doing the same thing.

   This is the one place the two deployments genuinely part, and it is the same split the jira plugin makes for the same reason: Cloud has an endpoint for searching people, and Server answers the question through the CQL search everything else goes through, with type=user saying what is being looked for. Which one runs is read off email, like every other difference here.

   A person found by name is the same User shape a person opened by id is. Both go through one mapper now rather than two that would drift, and the avatar fields come back empty from a search rather than absent - a search fetches no pictures, and a caller reading avatarKey should get the same kind of nothing either way.

4. 0.7.0

   Confluence 0.7.0: fetch the avatar, and stop building its url wrongly

   Two things about the picture a user lookup answers, one of which was broken the moment it shipped.

   The url hung off the wrong root. An avatar's path is absolute from the site, and on Cloud it already carries the /wiki that the configured url ends with - so joining the two the obvious way asked for /wiki/wiki/aa-avatar/… and got a 404. It is built from the scheme and host now, which is right on both deployments. Every avatarUrl 0.6.x answered on Cloud was a dead link.

   And the field was named for something it was not. It was picture in 0.6.0, holding a url, and something downstream read a field of that name as image content and refused a url as bad base64. avatarUrl says what it holds. The lesson is worth keeping: a name is an interface, and one that promises bytes had better carry bytes.

   Which is what withAvatar now does. An avatar sits behind the same login as the wiki, so the url alone shows nothing to anybody who is not signed in - handing somebody the link is not handing them the face. Asked for, the plugin fetches it with its own credential and answers three things: the base64, what those bytes are, and a key naming them in the session store, so a picture reaches Slack as a contentKey rather than as a few kilobytes retyped by a model.

   Off by default, because a name and an email are what a lookup is usually for and bytes nobody asked for are bytes through the model. A fetch that fails leaves the three empty and the lookup whole: an avatar is decoration, and failing a person lookup over a missing default picture would be the wrong trade entirely.

5. 0.6.0

   Confluence 0.6.0: a mention is an id, and now it can be a person

   A page body does not say who was mentioned. It says this:

   <ac:link><ri:user ri:userkey="ff8080816f2b1c34016f2b1c34000001"/></ac:link>
   

   which is a string of hex where a name should be, and Cloud writes the same thing as ri:account-id. So "who owns this runbook" was a question this plugin could fetch the answer to and not read.

   openPage now answers a mentions list beside the body: every id the markup carries, each once, in the order the page uses them. It is parsed rather than asked for - the ids are already in the body - and it matches on the ri: attribute itself, so an <ri:user> inside any macro counts, not only the mention one. A profile macro and an author parameter are the same question.

   openUser turns one into a person: display name, email where Atlassian will say, whether the account is somebody or an app, whether they are a guest, an avatar and a profile link. It takes whatever names them - the bare id, the mention pasted whole out of a page, a profile url, or on Server a username.

   Which kind of id a bare string is depends on the deployment, and that is decided off email the way everything else here is: Cloud retired usernames for account ids, so on Cloud there is nothing else it could be, while on Server a 32-character hex string is a user key and anything else is a username. That is Confluence's own distinction rather than a guess.

   Two limits worth saying out loud. A display name is not an identifier - Confluence looks a person up by key, not by label, so there is no openUser("Jo Smith") and searching is what that question takes. And email comes back null more often than not, which is an answer rather than a gap: Atlassian withholds an address its owner has not made public, whatever the token can otherwise see.

   Resolve the one that matters. A page mentioning eight people costs eight calls if all eight are asked for, and the question was almost always about the owner - which is why this answers ids and a way to resolve one, rather than resolving them all on the way past.

6. 0.5.0

   confluence 0.5.0: a skill, and now every plugin that needed one has one

   Two calls, and the whole skill is about the first. search passes the query through as written, so a model that does not know CQL exists gets full-text matching - which on a wiki of any size returns the twenty pages that mention the words and not the one that is about them.

   So it leads with CQL and real queries, the fields worth knowing, and the sharpest habit: prefer title ~ where you roughly know what the page is called, because a runbook is titled like a runbook while its body mentions a hundred things it is not about. Then read the excerpts and open exactly one page - opening five to find the right one costs five bodies of context and the first was usually right.

   Two things it says that are easy to get wrong. The body is Confluence storage format, which is XHTML rather than markdown, so it is read as HTML and summarised rather than quoted back. And an empty result is usually permissions: Confluence filters by what the credential can see, so a query that works in a browser answers nothing through a narrower token - worth saying as a possibility rather than telling somebody their wiki has no runbook.

   The three url forms it promises openPage takes were checked: a bare id, a Cloud /spaces/KEY/pages/123/ link and a Server ?pageId=123 one all parse, and anything else is refused by name.