Migrating from single-workspace to org-wide deployment
Those other pages cover what's new and differs from single-workspace apps that you might've built. But how do you migrate an existing single-workspace app (one that's ready for Enterprise) into an org-wide deployment?
Here are a few tips to keep in mind to make the transition from single-workspace to org graceful.
- Opt into org-wide deployment
- Use a minimum version of the SDKs
- Token storage
- Tokens from previous installations
- User IDs
- Scopes are inherited
- Webhooks cannot be used
- Chat.postMessage requires channel IDs
- Apps for Enterprise administration aren't supported
First things first: you'll want to specify in your app config that your app may be deployed to an entire Enterprise org.
Find the Org Level Apps section in the app config sidebar, and press the Opt-in button.
That's it: your app can now be installed by an Org Admin or Owner at the organization level, rather than on an individual workspace.
If you make use of Bolt frameworks or other SDKs to build Slack apps, make sure your version supports org-wide apps.
3.0.0 or higher.
To use Bolt for Python, you'll need version
1.1.0 or higher.
To use Bolt for Java, you'll need version
1.4.0 or higher.
Check the other SDKs' individual documentation for version requirements.
When your app turns from a single-workspace app into one that's deployed across an org, you may want to rethink the way you store tokens.
Previously, you might have stored one row in a database for each installation, and each row might contain a token.
Now, you can change your schema to reflect a one-to-many relationship between tokens and installations.
Alternatively, you can maintain the same one-to-one relationship and have rows for each installation and token, but you'll probably want to organize these with a sort key: the
If your app is installed on an entire org, where previously it was installed for specific users and workspaces, you might still have thousands of existing user tokens. These tokens will continue to function after you become an org-wide app.
After the app is installed on the organization, you'll be able to use a single org-wide user token for any users that authenticate after that moment (or reauthenticate).
And don't worry: your existing paths to gain user tokens (like Sign in with Slack, or just a regular OAuth sign-in flow for users) will still work. Those permissions will each be added to your org-wide user token, rather than creating a new token.
For the bot user token, which is likely what you use for most action, the case is simpler. After an org-wide deployment, all the workspaces where your bot was installed will automatically be accessible to the new org-wide token.
Your app does not lose access to workspaces or need to interrupt users. You can use the org-wide bot user token for workspaces where your app had already been installed.
If you previously had User ID translation
ON in your Enterprise app, now is the time to turn it
Single enterprise user IDs are now available. There's no benefit to continuing to maintain local IDs. Use
migration.exchange to obtain the new single IDs for any users that you have remaining local IDs for.
When your app is install across an org, the scopes set during that installation pass down to each installation on individual workspaces within that org. Even if you pass different scopes during the OAuth redirect when you gain access to an individual workspace, you'll still receive only the scopes set during the org-wide install.
Usually, when you call the chat.postMessage method to post a message to Slack, you specify the channel using a channel ID.
If, however, you specified the channel using a channel name, the call from your org-wide app will not succeed. You'll want to begin using channel IDs instead.
Some Slack app features that are specifically designed for Enterprise administration—including Audit Logs, SCIM, and other Admin APIs—already work with Enterprise organizations, rather than individual workspaces.
You will not be able to use an org-wide deployed app with any of these APIs—use a regular Slack app instead.