Apps deployed across an Enterprise organization are installed somewhat differently and have slightly different API usage.
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?
Read on for tips to keep in mind to make the transition from single-workspace to org graceful.
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.
To use Bolt for JavaScript, you'll need version 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 enterprise_id
.
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 OFF
.
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.
Webhooks aren't supported with org-wide apps. Use chat.postMessage
and our modern messaging suite of tools.
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 only need to install your app at the org level to use these Admin APIs — You won't need to deploy your app across your org.