---
availability: INSTALLABLE
name: Manage Presence Collaborators
description: Lets employees add or remove collaborators in the ServiceNow WSD module and see which days those colleagues plan to be in, so office days line up with the right people, via the Moveworks AI Assistant.
installation_asset_uuid: 2a7e345f-0b5e-48cb-b2ee-3000ce31a6a1
purple_chat_link: https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I%27d+like+to+update+my+collaborators+for+the+Alpha+Project.+Can+you+add+Sarah+Miller+and+David+Chen+to+my+list+in+ServiceNow%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+Sarah+Miller+and+David+Chen+in+%3Cb%3EServiceNow%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22I+found+two+people+named+%3Cb%3ESarah+Miller%3C%2Fb%3E.+Which+one+would+you+like+to+add%3F%3Cul%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E%2C+Senior+Designer+%28Creative+Services%29%3C%2Fli%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E%2C+Product+Manager+%28Growth+Team%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22The+Senior+Designer.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27m+ready+to+add+these+colleagues+to+your+%3Cb%3EPresence+Collaborators%3C%2Fb%3E+list+so+you+can+see+when+they+are+in+the+office%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E+%28Senior+Designer%29%3C%2Fli%3E%3Cli%3E%3Cb%3EDavid+Chen%3C%2Fb%3E+%28Software+Engineer%29%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EShould+I+proceed%3F%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Add+Collaborators%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Add+them.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Updating+collaborator+list+in+%3Cb%3EServiceNow%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3ESuccess%21+%3Cb%3ESarah+Miller%3C%2Fb%3E+and+%3Cb%3EDavid+Chen%3C%2Fb%3E+have+been+added+to+your+collaborators.+You+will+now+receive+updates+on+their+office+attendance.%3C%2Fp%3E%3Cp%3E%3Ca+href%3D%5C%22https%3A%2F%2Fservicenow.com%2Fpresence%2Fdashboard%5C%22%3EView+Presence+Dashboard%3C%2Fa%3E%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22servicenow%22%2C%22citationTitle%22%3A%22Collaborator+List%3A+Alpha+Project%22%7D%5D%7D%5D%7D%5D%7D
solution_tags:
- Workplace
- Workplace Service Delivery
- Workplace Experience
- Facilities
- Workspace
- Collaboration
systems:
- servicenow
---
# Description
Coming into the office is only worth it when the right people are there too. With collaborators, an employee curates a short list of the colleagues they work most closely with — adding or removing them right from the Moveworks AI Assistant — and sees when those colleagues plan to be in. That makes it easy to line up office days with the right people, so in-person time is spent together instead of guessing and hoping. Fewer wasted trips, more of the face-to-face that actually needs an office.
# User Experience Preview
Refer to the [**Purple chat**](https://marketplace.moveworks.com/purple-chat?conversation=%7B%22messages%22%3A%5B%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22I%27d+like+to+update+my+collaborators+for+the+Alpha+Project.+Can+you+add+Sarah+Miller+and+David+Chen+to+my+list+in+ServiceNow%3F%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Searching+for+Sarah+Miller+and+David+Chen+in+%3Cb%3EServiceNow%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22I+found+two+people+named+%3Cb%3ESarah+Miller%3C%2Fb%3E.+Which+one+would+you+like+to+add%3F%3Cul%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E%2C+Senior+Designer+%28Creative+Services%29%3C%2Fli%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E%2C+Product+Manager+%28Growth+Team%29%3C%2Fli%3E%3C%2Ful%3E%22%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22The+Senior+Designer.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22%3Cp%3EOkay%2C+I%27m+ready+to+add+these+colleagues+to+your+%3Cb%3EPresence+Collaborators%3C%2Fb%3E+list+so+you+can+see+when+they+are+in+the+office%3A%3C%2Fp%3E%3Cul%3E%3Cli%3E%3Cb%3ESarah+Miller%3C%2Fb%3E+%28Senior+Designer%29%3C%2Fli%3E%3Cli%3E%3Cb%3EDavid+Chen%3C%2Fb%3E+%28Software+Engineer%29%3C%2Fli%3E%3C%2Ful%3E%3Cp%3EShould+I+proceed%3F%3C%2Fp%3E%22%7D%2C%7B%22buttons%22%3A%5B%7B%22buttonText%22%3A%22Add+Collaborators%22%2C%22style%22%3A%22filled%22%7D%2C%7B%22buttonText%22%3A%22Cancel%22%2C%22style%22%3A%22outlined%22%7D%5D%7D%5D%7D%2C%7B%22role%22%3A%22user%22%2C%22parts%22%3A%5B%7B%22richText%22%3A%22Add+them.%22%7D%5D%7D%2C%7B%22role%22%3A%22assistant%22%2C%22parts%22%3A%5B%7B%22reasoningSteps%22%3A%5B%7B%22status%22%3A%22success%22%2C%22richText%22%3A%22Updating+collaborator+list+in+%3Cb%3EServiceNow%3C%2Fb%3E...%22%2C%22connectorName%22%3A%22servicenow%22%7D%5D%7D%2C%7B%22richText%22%3A%22%3Cp%3ESuccess%21+%3Cb%3ESarah+Miller%3C%2Fb%3E+and+%3Cb%3EDavid+Chen%3C%2Fb%3E+have+been+added+to+your+collaborators.+You+will+now+receive+updates+on+their+office+attendance.%3C%2Fp%3E%3Cp%3E%3Ca+href%3D%5C%22https%3A%2F%2Fservicenow.com%2Fpresence%2Fdashboard%5C%22%3EView+Presence+Dashboard%3C%2Fa%3E%3C%2Fp%3E%22%7D%2C%7B%22citations%22%3A%5B%7B%22connectorName%22%3A%22servicenow%22%2C%22citationTitle%22%3A%22Collaborator+List%3A+Alpha+Project%22%7D%5D%7D%5D%7D%5D%7D) for a sample conversational experience between a user and the AI Assistant for this plugin.
# Pre-requisites
Before installing and using the **Manage Presence Collaborators** plugin, ensure that the following requirements are met:
## **1. ServiceNow's Workplace Concierge**
This plugin requires an active **Workplace Concierge** installation and configuration on your ServiceNow instance.
- If you have not installed and configure the application, follow the **[Install Workplace Concierge](https://www.servicenow.com/docs/r/employee-service-management/workplace-concierge/install-workplace-concierge.html)** documentation
- The minimum version of the Workplace Concierge application is: 1.7.11
- After the app is configured, follow our **[plugin installation documentation](https://help.moveworks.com/docs/ai-agent-marketplace-installation)** for detailed steps on how to install and activate the plugin in **Agent Studio**.
## **2. User Identity Ingestion from ServiceNow**
This plugin operates on presence records under the requesting user's own ServiceNow identity. The `requested_for` fields are populated by dot-walking the user's profile in the Data Bank: `meta_info.user.external_system_identities.snow.external_id`
The `external_id` serves two purposes:
1. **Authentication & role verification** — the `external_id` is used to verify that the user has the required `sn_wsd_core.workplace_user` role in ServiceNow. Without this, API calls will fail regardless of authentication status.
2. **Presence operations** — all presence operations are scoped to the authenticated user's identity in ServiceNow.
This reads the user's ServiceNow `sys_id` from the identity source linked to their Moveworks profile, so your users must be ingested from ServiceNow for this value to populate. To set up user identity for your org, read our help docs on Identity Configuration in [**Moveworks Setup**](https://help.moveworks.com/service-management/moveworks-setup/identity-configuration).
>⚠️ **Important — update this mapping to match your setup**. The `snow` key in that path must exactly match the name of `your` ServiceNow identity source in Moveworks Setup. If yours is named differently (e.g. `servicenow_prod`), update the Compound Action mapping to `meta_info.user.external_system_identities.servicenow_prod.external_id`. If it doesn't match, the path resolves to null and both authentication and presence operations will fail.
## **3. ServiceNow Connector**
This plugin requires an active **ServiceNow connector** configured with **OAuth 2.0 using the Authorization Code grant (user-based / User Consent auth)**.
- If you have not already configured the connector, follow the [**OAuth 2.0 Authorization Code guide**](https://docs.moveworks.com/agent-studio/connectors/http-connectors/oauth-20-authorization-code). The connector must be fully set up before installing this plugin.
# Implementation details
**Note:** References to the instance must be updated after the plugin is installed.
## Visual representation of how the plugin works
# **Implementation Details**
## API Details
Before running the cURL examples, replace `YOUR_INSTANCE` with your instance hostname and `ACCESS_TOKEN` with the OAuth access token issued for the user.
### **API: Resolve Collaborator Name**
This REST API is used to resolve the name of the employee based on the provided input, initially filtering on employees within their team before searching in the complete directory.
```bash
curl --location 'https://<YOUR_INSTANCE>/api/sn_wsd_core/wsd_unified_search/users_and_locations' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"search_term": "Alex Rivera",
"filterConfig": {"sys_user": "manager=<manager_sys_id>^ORmanager=<requester_sys_id>^ORsys_id=<manager_sys_id>^sys_id!=<requester_sys_id>"},
"options": {},
"sysparam_offset": 0,
"sysparam_limit": 25
}'
```
**Body parameters**
- `search_term`: This is name used to search for a user
- `filterConfig`: This is used to specify the table to search for a user (`sys_user`)
- `sysparam_limit`: This is the number of spaces returned that matches the `search_term`.
**Notes**
- Team is determined based on the email of the employee's manager.
### **API: Get Presence Collaborators**
This REST API is used before adding or removing a collaborator, to validate if they are already a collaborator.
```bash
curl --location 'https://<YOUR_INSTANCE>/api/sn_wsd_concierge/presence/collaborator' \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'
```
**Notes**
- If a collaborator has privacy enabled, their `routine`/`exceptions` information is omitted entirely.
- A collaborator's routine/exceptions information is computed for a maximum of three months (fixed).
### **API: Add Presence Collaborator**
This REST API is used to add collaborator by colleague name. A check is done upfront to determine if the colleague is already a collaborator.
```bash
curl --location 'https://<YOUR_INSTANCE>/api/sn_wsd_concierge/presence/collaborator' \
--request POST \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
"collaborator_ids": ["<resolved_user_sys_id>"]
}'
```
**Body parameter**
- `collaborator_ids`: An array of user sys_ids to include one or multiple colleagues as collaborator
**Note**
- The action is executed without a confirmation step.
### **API: Delete Presence Collaborator**
This REST API is used to remove collaborators. A check is done upfront to determine if a colleague is already a collaborator.
```bash
curl --location 'https://<YOUR_INSTANCE>/api/sn_wsd_concierge/presence/collaborator/<collaborator_sys_id>' \
--request DELETE \
--header 'Authorization: Bearer <ACCESS_TOKEN>' \
--header 'Accept: application/json'
```
**Path Parameter**
- `collaborator_sys_id`: Sys_id of one of the requester's current collaborators that must be removed.
**Note**
- The action is executed without a confirmation step.
### API References
This plugin uses **Workplace Concierge** and **Workplace Core REST APIs** to retrieve information.
For detailed information on request parameters, response formats, error handling, and versioning, refer to the **[official ServiceNow documentation](https://developer.servicenow.com/dev.do#!/reference/)**.
# **What Is In Scope for This Plugin?**
- Add a single colleague as a presence collaborator, resolved against the ServiceNow user directory (team/manager scope first, then the whole directory).
- Removing a presence collaborator.
- Only existing collaborators can be removed from being a presence collaborator.
# **What Is Out of Scope for This Plugin?**
- Listing or viewing the requester's current collaborators or their presence/routine data requires the `View Presence` plugin.
- Setting presence status or updating the weekly routine requires the `Set Presence Status` and `Update Presence routine` plugins.
- The plugin removes one presence collaborator per operation.