Slack Enterprise Grid allows large organizations to collaborate across many workspaces. While many apps, integrations, and bots will work as expected on Enterprise Grid, there are enough new behaviors, conditions, nuances, and opportunities to warrant reviewing your app for full compatibility.
Read on if you are:
The best thing you can do is use the migration.exchange method to update all records you have for an existing workspace with those from an Enterprise Grid. Then you won't need to worry about a "translation layer" or maintaining two IDs for a single user.
Workspaces don't always start out part of an Enterprise. Thanks to mergers, acquisitions, and the inherent nature of life, a workspace may become part of an Enterprise Grid.
One single user may have an identity in Workspace A, and another in Workspace B. With Enterprise Grid, you can reconcile those identities and make that user a cross-referenced entity identifiable across multiple workspaces.
If your app is in a workspace that's part of an Enterprise Grid organization, you will observe a constant and unique enterprise_id attribute through API methods and events. Below are notable methods:
auth.test β We recommend using this method after acquiring an OAuth token. You'll want to poll it regularly for all workspaces you service, as workspaces migrate to Enterprise Grid.conversations.info β appears in shared channelsteam.infoIf you store data, you'll want to warehouse the enterprise_id value. Just as you'd never store information about a user or their data without tying it to a workspace first, it's best to associate Enterprise Grid workspace data with its enterprise_id.
If your app is installed on multiple workspaces within an Enterprise Grid organization, you may want to utilize that position effectively by grouping data by enterprise_id value and using the new enterprise_ID values as your primary source of truth.
Some platform features require additional support in Enterprise Grid workspaces.
Slack apps require you to:
The Events API requires you to:
The Web API requires you to:
users.info to retrieve additional information on cross-workspace user IDs not found in users.list.Slash commands require you to:
Legacy integrations
Legacy bot users are more likely than other integration points to require additional work for exemplary performance on Enterprise Grid workspaces.
Legacy custom integrations have few programmatic signals to interpret and off-the-shelf code may not know how to handle certain situations like shared channels.
Legacy message buttons require you to support user ID fields containing global user IDs and to support action invocations by users from other workspaces.
Legacy RTM API usage will require additional effort to prevent duplicative messages and other undesired behaviors. See Using the RTM API on Enterprise Grid for more detail.
If your app or integration is used as part of a shared channel, it will encounter users it is not aware of.
The users.list method won't return users from other workspaces in its payload.
To find users from another workspace on an Enterprise Grid, use the users.info method and query by their "foreign" user ID.
Many apps need only a user's ID and don't need additional information to operate.
Not only will you encounter user IDs belonging to other workspaces, but also the artifacts of their existence and workspace cross-pollination:
Messages will be authored by these users, and if they fall within your app's functionality, you should respond as you normally would. Messages may also mention users on other workspaces.
If your messages contain interactive elements, you may receive invoked actions from these users, and should handle them just as you would a "native" workspace user.
If you provide a slash command, you'll want to handle mentions of members from other workspace's. We strongly recommend turning on entity resolution so you can resolve mentioned users.
If you're using the Events API, you do not have to worry about duplicate messages from shared channels. We'll only send one event regardless of how many workspaces within the organization your app is installed on.
Look for the authed_teams node that arrives as part of the "wrapper" around delivered events. It contains a collection of team IDs within an organization that this delivery is on behalf of.
Here's an example payload of a shared channel's message being delivered on behalf of multiple workspaces:
{
"token": "ecto1EZslimer",
"team_id": "T111AAA111",
"api_app_id": "A123ABC456",
"event": {
"type": "message",
"user": "W123ABC456",
"text": "It's time to slacktivate!",
"team": "T111AAA111",
"source_team": "T111AAA111",
"user_team": "T111AAA111",
"user_profile": {
"avatar_hash": "g56821b98743",
"image_72": "https://...png",
"first_name": "Jesse",
"real_name": "Jesse Slacksalot",
"name": "jesse.slacksalot"
},
"ts": "1485371714.000002",
"channel": "C123ABC456",
"event_ts": "1485371714.000002"
},
"type": "event_callback",
"authed_users": [
"W3MBP5799"
],
"authed_teams": [
"T222BBB222",
"T111AAA111"
]
}
In this example, the application is installed on two workspaces on an Enterprise Grid and is party to a conversation in a shared channel.
The message originates from team T111AAA111 and is delivered as a single event for both teams, including T222BBB222.
In most cases, an Enterprise Grid is formed by combining multiple independent Slack workspaces together. During this period of time where data is migrated and made compatible with Grid's organization structures, platform interactions may be unavailable, both for users and your applications.
On the Web API, you may encounter the team_added_to_org error during this time.
Migration time varies depending team-to-team and organization-to-organization. When encountering errors, practice an exponential backoff strategy to help manage these periods by attempting connections at incrementally increasing rates: 1 second to 3 seconds to 10 seconds to 30 seconds to 1 minute, and so on.
To best plan for migrations, subscribe to Enterprise Grid-related app events as part of the Events API. Using these events, your app can pause and resume activity as appropriate:
If your app has disabled the translation layer, use the migration.exchange method to receive global user IDs for any of your stored local user IDs.
User objects on Enterprise Grid workspaces now have an enterprise_user attribute, containing fields with additional context about the user in the larger Enterprise Grid organization:
enterprise_user fields |
Description |
|---|---|
id |
The user's ID, which might start with U or W. |
enterprise_id |
The unique ID for this particular Enterprise Grid organization. |
enterprise_name |
The name of this umbrella organization. |
is_admin |
A boolean value indicating whether this user administers this Enterprise Grid. |
is_owner |
A boolean value indicating whether this user is the owner of this enterprise organization. |
teams |
An array of team (workspace) IDs within the containing enterprise organization that this user belongs to. |
Within an Enterprise Grid, all users have a single, global ID beginning with either the letter U or W. The specific prefix does not indicate anything in particular.
Slack will automatically convert users' pre-Enterprise-migration ID references to their singular Enterprise ID. This allows your app to remain backwards compatible for users identified on a workspace before the days of Enterprise Grid.
Users created after a workspace became part of an Enterprise have no pre-Enterprise-migration ID.
Slack Apps can turn on a translation layer in their app settings that will display "local" historical user IDs beginning with U for users that existing prior to an Enterprise Grid migration for a workspace the app was already installed on. It also lets you use these classic user IDs within a migrated workspace. It's meant to be used for a short while.
We strongly recommend you turn this translation layer off after using migration.exchange and going all-in with global user IDs, regardless of which letter they start with.
Disable the translation layer by navigating to application management for your app and finding the User ID Translation panel.
If you need to update local user IDs you've stored in a database or in other ways, first use the migration.exchange method with the relevant user or bot tokens to receive global user IDs in bulk.
As with all Slack apps, installation and ownership of apps is on a workspace-basis. Apps that are locked to a single workspace cannot be installed across an Enterprise Grid.
If your app is part of the Slack Marketplace, you'll want to let us know that you've prepared for Enterprise Grid workspaces. We'll do some additional testing and give you feedback on anything that could be improved.
Building properly for shared channels or Enterprise Grid requires experiencing the unique constraints and opportunities yourself.
If you don't already have access to an Enterprise Grid of workspaces, please complete the form below to request a sandbox. We'll get back to you as soon as possible.