Smart hooks - Use user recommendations
Note: This component is designed for internal Atlassian development.
External contributors will be able to use this component but will not be able to submit issues.
useUserRecommendations
Custom hook for interfacing with Platform user-ranked searching.
Uses user-recommendations-service to retrieve users, reranked based on relevance.
The hook also fires analytics to inform smart reranking for future interactions.
For previous SmartUserPicker consumers, this hook is a drop-in replacement for the data layer of SmartUserPicker.
Usage
The useUserRecommendations hook can be used with any UI experience that deals with platform user searching. It works particularly well with experiences that benefit from relevance-based reranking, such as those involving repetitive interactions with a consistent set of users (e.g. Assignee field).
with UserPicker
Convert a @atlaskit/user-picker to a provider-backed user-picker using useUserRecommendations hook.
useUserRecommendations with @atlaskit/user-picker
Smart Picker props
useUserRecommendations Props
baseUrl string
Base url override for downstream APIs. Note: there is a trend for browsers blocking cookies for cross-site resources. This prop is added for legacy reasons and will likely be removed in the future. https://webkit.org/blog/10218/full-third-party-cookie-blocking-and-more/
childObjectId string
Context information for analytics. Eg: if the hook was consumed inside a ticket's comment, the childObjectId would be the ID of the comment and the ticket would be the objectId. Optional, but please provide if available.
containerId string
The container Id to identify context. e.g. Jira: projectId. Confluence: spaceId. Bitbucket: repositoryId.
debounceTimeMs number
Time to debounce the suggestions fetching (in milliseconds). Defaults to 150ms.
fieldId string required
Identifier for informing the server on what experience the hook is powering. The server uses the fieldId to determine which model to utilize when generating suggestions. All fieldId's will be bucketed into a model that provides generic smart results, except "assignee", "mentions" which are specifically trained for Jira Assignee and @Mentions. For specifically trained models, please contact #search-plex.
includeUsers boolean
Whether to include users in the result set (@default: true).
includeGroups boolean
Whether to include groups in the resultset (@default: false).
includeTeams boolean
Whether to include teams in the resultset (@default: false).
maxNumberOfResults number
(@default: 25)
objectId string
An identifier of the closest context object, e.g. issueId, pageId, pullRequestId. Used for analytics. Optional, but please include if available.
preload boolean
Preload the list of suggested users with an empty-query ('') search as soon as the hook is used. WARNING: please consider carefully before deciding to preload your suggestions as this will increase the load on the recommendations services (has caused HOTs). Please give #search-plex a ballpark on the expected request volume. (@default: false)
principalId string
AAID of the user interacting with the component. If not provided, server will extract principalId from the context header, assuming that the user is logged in when making the request. (@default: “context”)
productAttributes import
Product-specific Attributes - you should pass in the attribute type that matches your current SupportedProduct. Currently we support additional attributes (BitbucketAttributes) for bitbucket and (ConfluenceAttributes) for Confluence.
@atlaskit/smart-common.UserSearchProductAttributesproductKey string required
Product identifier. If you are an NPF, please ensure your product has been onboarded with
Cross-product user-search @see https://developer.atlassian.com/cloud/cross-product-user-search/
If you are still waiting for CPUS, you can use the people productKey in the interim.
cpusSearchQuery import
Pass-through for CPUS. Refer to @see https://developer.atlassian.com/cloud/cross-product-user-search/rest/api-group-search/#api-group-search for detailed docs on parameters.
@atlaskit/smart-common.UserSearchQuerytenantId string required
Identifier for the product's tenant, also known as siteId or cloudId. If product is not tenanted, the convention is to provide the productKey as the tenantId (e.g. "bitbucket") but this may vary across products. Check with #search-plex.