Using "@mentions" in Confluence

[rlueckl]

Hi,

are there any plans to bring @mentions to confluencebuilder? They look like this in the storage format:

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

The userkey looks like an MD5 hash. When using the WYSIWYG editor I just need to start typing @username and if a match is found I simply select the desired user.

I see 2 ways this could be implemented: either the @sometext format is recognized and confluencebuilder resolves username->hash during build or we could put a list of usernames->hashes in conf.py (similar how Jira links are done with confluence_jira_servers) and confluencebuilder simply looks up the username in this dictionary. Latter would be more work for the user, but probably easier to implement.

Alternative 1: use ri:username instead of ri:userkey - no need to look up hashes.

Alternative 2: since "username" and "userkey" are both deprecated (see: https://developer.atlassian.com/cloud/confluence/api-changes-for-user-privacy-announcement/) maybe we could use "accountId" ("ri:account-id" ?). This would require a similar approach as the userkey (look up the ID during build or put a list of IDs in conf.py).

[jdknight]

Would not object to the inclusion of a directive which would support rendering a mention-based Confluence link. A quick look at this, confluence_mention may be a good candidate for the directive name -- but, other suggestions would be welcome.

If all active (non-EOL) Confluence editions support just the accountId value (mentioned in "Alternative 2"), it would probably be best to just focus on supporting this capability (over attempts to use username or userkey). Additional comments are as follows:

• It may be good to support directly placing an account UID directly in a directive instance; for example:

Talk to :confluence_mention:`<prefix?>:8fb069c8-af4b-4e61-985e-636e2c559493` for more information.

• A name mapping translation (as mentioned in the original comment) could be ideal as well. For example:

(reStructuredText)
Talk to :confluence_mention:`rlueckl` for more information.

(conf.py)
confluence_mentions = {
    'rlueckl':  '<prefix?>:8fb069c8-af4b-4e61-985e-636e2c559493',
}

[rlueckl]

Unfortunately I can't find out which Confluence versions support accountId. Here's a list of supported Confluence versions: https://confluence.atlassian.com/support/atlassian-support-end-of-life-policy-201851003.html

And here are the docs to the current (7.3.3) Confluence Server API which doesn't mention accountId anywhere: https://docs.atlassian.com/ConfluenceServer/rest/7.3.3/#api/user-getUser

The only mention of the accountId I could find were:

• in the Announcement https://developer.atlassian.com/cloud/confluence/deprecation-notice-user-privacy-api-migration-guide/
• the Jira Cloud API docs (v2 and v3 - however I don't know which Jira version uses which API version): https://developer.atlassian.com/cloud/jira/platform/rest/v3/#api-rest-api-3-user-bulk-migration-get
• and the Confluence Cloud API docs: https://developer.atlassian.com/cloud/confluence/rest/#api-api-user-bulk-migration-get

Maybe the removal of userKey only refers to Confluence Cloud and Jira Cloud platform, but not the Confluence Server versions? :thinking:

I'm using Confluence 6.15 and when I query my user through the API, I get the userKey back:

$ curl -s https://******/rest/api/user?username=rlueckl -u '******' -H 'Accept: application/json' | jq .
Enter host password for user '******':
{
  "type": "known",
  "username": "rlueckl",
  "userKey": "8acf41924e6e1fbe014e723*********",
  "profilePicture": {
    "path": "/download/attachments/917510/user-avatar",
    "width": 48,
    "height": 48,
    "isDefault": false
  },
  "displayName": "XXX YYY",
  "_links": {
    "base": "https://******",
    "context": "",
    "self": "https://******/rest/api/user?key=8acf41924e6e1fbe014e723*********"
  },
  "_expandable": {
    "status": ""
  }
}

[mschoenlaub]

@jdknight willing to tackle that. Would you mind taking part in hacktoberfest though? :)

[jdknight]

@mschoenlaub, sure -- let's do this. 🎊

I'm not too familiar with Hacktoberfest, but I believe I set up everything based on their instructions.

[girivs82]

I would be interested in this feature as well.

[jdknight]

It has been awhile since this enhancement was first brought up, but initial support has been introduced (#653) to support mentions through Sphinx roles. This change has been added into the main branch and should be made available next stable release. If users wish to use this capability before a release is made, the development version of this extension can be installed.

[jdknight]

v1.9 is now available on PyPI -- marking as closed.