Feature: Resolve Slack @mentions by display name (not just user ID)

[adamrtalbot]

Problem

Users can @mention people in nf-slack messages using Slack's native <@U1234567890> syntax with internal user IDs, and this works correctly. However, most users don't know Slack user IDs off the top of their head.

Writing <@Jane> (by display name) does not work — Slack only resolves mentions by internal user ID, so the text is rendered literally rather than as a clickable mention that notifies the person.

slack {
    onStart {
        // ❌ Does NOT work — display name is not resolved by Slack
        message = [text: ':wave: Hi <@Jane>!']

        // ✅ Works — but requires knowing the internal user ID
        message = [text: ':wave: Hi <@U1234567890>!']
    }
}

Proposed Solution

The plugin should resolve display names to Slack user IDs before sending the message. When the plugin encounters <@DisplayName> in message text, it should:

1. Call the Slack users.list or users.lookupByEmail API to find the matching user
2. Replace <@DisplayName> with <@U1234567890> (the resolved user ID)
3. Send the message with the corrected mention syntax

Similarly for team/group mentions, resolve <!subteam^TeamName> to <!subteam^S1234567890>.

Matching strategy

Display names in Slack are not guaranteed unique, so the plugin should match against multiple fields in priority order:

1. Username (name field) — e.g. jane.doe
2. Display name (profile.display_name) — e.g. Jane
3. Real name (profile.real_name) — e.g. Jane Doe

If multiple users match, the plugin should warn and skip resolution (rather than guessing wrong).

Considerations

• Bot token scope: Requires the users:read OAuth scope to call users.list.
• Webhook limitation: This feature would only work with bot token mode, not incoming webhooks (which can't call users.list). Should fail gracefully or warn if using webhook mode.
• Performance: User list could be cached for the lifetime of the pipeline run to avoid repeated API calls.
• Ambiguity handling: If a display name matches multiple users, log a warning with the matches and leave the mention unresolved rather than mentioning the wrong person.

[adamrtalbot]

@claude please draft a first version of this.

[claude]

Claude finished @adamrtalbot's task in 9m 48s —— View job • claude/issue-46-20260220-1406 • Create PR ➔

---

First version: resolve Slack @mentions by display name

• Explore codebase structure and existing HTTP client usage
• Implement SlackUserResolver class with users.list + usergroups.list API support
• Integrate mention resolution into BotSlackSender.sendMessage()
• Write Spock tests for SlackUserResolver (21 test cases)
• Commit and push changes

---

What was implemented

New file: SlackUserResolver.groovy

Resolves <@DisplayName> mentions to <@U1234567890> in any message text (or JSON payload) before it's posted to Slack. Key properties:

• Priority order (first match wins): username → profile.display_name → profile.real_name
• Ambiguity-safe: if multiple users match, logs a warning and leaves the mention unresolved
• Deleted users excluded from all lookups
• Already-resolved IDs (<@U…> / <@W…>) are detected and left unchanged
• Subteam / usergroup mentions: <!subteam^team-handle> → <!subteam^S1234567890> via usergroups.list
• Pagination: follows next_cursor to fetch the full users.list regardless of workspace size
• Cache: user and group lists are fetched once per pipeline run (double-checked locking)
• Graceful degradation: if users:read scope is missing or the API is unreachable, a descriptive warning is logged and mentions are left unchanged — the pipeline is never failed
• Webhook-safe: SlackUserResolver is only wired into BotSlackSender; WebhookSlackSender is unaffected

Modified: BotSlackSender.groovy

sendMessage() now passes the payload through userResolver.resolveText() before calling postToSlack():

// before sending — transparent to callers
def resolvedMessage = userResolver.resolveText(message)
postToSlack(resolvedMessage)

New file: SlackUserResolverTest.groovy (21 tests)

Covers: ID format detection, no-op for plain text, priority ordering, multi-mention resolution, ambiguity handling, deleted-user exclusion, JSON payload passthrough, subteam resolution, fetch-failure graceful handling, cache-hit verification.

Example

// nextflow.config
slack {
    onStart {
        // ✅ Now works — display name resolved automatically
        message = [text: ':wave: Hi <@Jane>, please review <@jane.doe>!']

        // ✅ Still works — already a Slack ID, left unchanged
        message = [text: ':wave: Hi <@U1234567890>!']
    }
}

Bot token scope required

Add users:read to your Slack app's OAuth scopes for user-mention resolution, and optionally usergroups:read for <!subteam^…> group-mention resolution.

---

·