Org admins for teams on Coda’s Enterprise plan can already control which Packs are accessible within their workspaces. And with custom Pack configurations, org admins have the additional ability to control:

Who within their organization can install a Pack
What parts of that Pack can be used and how users can use the Pack
How docs containing that Pack can be shared within their organization

For example, you might want to allow org members to only be able to view data from the Slack Pack without being able to take actions in Slack. Or maybe you want Group A to access all projects from the Jira Pack, and block Group B from accessing ProjectX.

If you’re an org admin, you can create these Pack configs using JSON to only authorize access to specific parts of a Pack for a specific users (or user groups). Read on to learn all about Pack configurations!

Enable Pack configurations

In order to start creating custom Pack configurations, org admins must first enable this control in their Organization settings. To do so, just follow these steps:

Go to coda.io/workspace
In the bottom left corner, click on More options
Select Organization settings
Click into the Pack approvals tab
Make sure the Require admin approval and configure policies setting is toggled on.

Now that this setting is on, org members will need to request approval anytime they want to add a new Pack to a doc. You can read all about these Pack requests and approvals here.

You will also see a list of Packs that are already used by members of your organization under the Packs in your organization section. By default, the configuration for Packs that are in use will be set to Allow all access, which means that any org member has unrestricted access to the Pack. You can optionally change this configuration to be more restrictive if needed. Check out the section below for a full guide on this.

Note: Enabling Pack approvals will disconnect any Pack connections between users in your org and docs outside your org and vice versa and prevent the linking of these going forward. It will also prevent users in your org from creating Pack connections in docs outside your org and vice versa.

Create custom configurations

If you are an Enterprise org admin that has Packs approvals enabled, you will now see the option to view and manage configurations for any Pack that’s allowed in your organization. To get started, follow these steps:

Go to coda.io/docs
In the lower left corner, click on More options
Select Organization Settings
Click into the Packs approvals tab
Under Packs in your organization, find the Pack you’d like to modify. Expand to see details. You should see at least one existing configuration for that Pack.
1. Note: When you approve a Pack, the default configuration is set to Allow all access which means any member within your organization can install the Pack and access all functionalities.
To modify an existing configuration, click the corresponding Edit configuration
To create a new configuration, click + Add new configuration

From here, there are two main ways to utilize Pack configurations:

Limit which users have access to a Pack (Restrict Pack users)
Limit how those members can use the Pack (Restrict Pack functionality)

Check out the corresponding sections below for details on each.

Restrict Pack users

To change who can access a specific Pack, click on Edit Configuration and turn off Entire organization has permission to use this configuration.

Then you can add specific users and groups that are allowed to use this Pack below. If you use SCIM groups, you should be able to see and select your SCIM groups in auto-suggest as you type.

To delete a user or group from having access to Pack, you can click on the delete button (small x) next to the user or group name.

Restrict Packs functionality

If you want to control what aspects of the Pack is made available to specific users and groups, you can do so by editing the Pack configuration. The configuration uses a JSON schema and is flexible in supporting any policy you might want to set.

Restricting Pack components

There are two flavors to choose from when restricting Pack functionality:

Broad-based restrictions: You can independently choose to allow Pack components that fetch data from the third-party system (called fetches ) and Pack components that update data in the third-party’s system (called actions)
Granular restrictions: You can choose to enable individual formulas in the Pack (via the formulas configuration) and individual Packs tables (via the syncTables configuration).

If you choose to restrict Pack components via either of these directives, any Pack component that is not explicitly enabled will be disallowed.

You can see what building blocks and OAuth scopes are used by a Pack by clicking on the open button next to the heading. You will be taken to the Packs page which has all the details about the Pack in the About and Security tabs to help you decide if you want to restrict access to any part of the Pack.

To get started easily, you can click on the Quick start menu to see the syntax for a few examples of policies that you may want to set for the Pack. You can select one of these examples and click on the Use button to apply the syntax.

Note that the Quick Starts are meant to just provide the initial outline. You must then edit the initial outline of configuration policy with the necessary details.

Here’s a little bit about the different kinds of Quick Start policies you can configure for a Pack:

Allow all usage: This is the default option that allows unrestricted access to all building blocks and functionalities of a Pack.
Only allow buttons with private connections: Use this to only allow users to use buttons using their private accounts to take actions. Shared accounts will be disabled for all actions, and other functionality of the pack such as sync tables will also be disabled.
Only allow a few Packs tables: Use this to only allow users to specific authorized sync tables. All other sync tables, and other functionality of the pack such as buttons will be disabled.
Restrict sharing to users who can access this Pack config: Use this to restrict sharing of docs with Pack data to only the set of users that have access to the Pack. Sharing of the doc with anyone else will be disabled.
- Note: This is a restrictive action and we only recommend using this policy on Packs that have sensitive data that shouldn’t be visible to users outside authorized SCIM groups.
Allow explicitly declared OAuth scopes: Use this if you want to allow specific OAuth scopes that the Pack has permission to.

For a detailed set of examples, please see our Configuration cookbook.

Restricting Pack component inputs

If you implement granular Pack component restrictions (via above), you can choose to further restrict inputs to those components in order to solve a particular use case. This is accomplished via the following

For Pack tables and formulas, inputs to these components can be restricted by editing the parameters component of the config.
For dynamic Pack tables, the dynamicUrl input can be restricted by editing the dynamicUrl component of the Pack table config.

If a configuration has a restriction on an input (parameters or dynamicUrl), then that parameter will be required and must pass validation in order for the component to work.

Please see Configuration cookbook for some examples for how this can be used.

Best practices

Any changes you make to Pack configurations will have an immediate impact on users and docs within your organization that rely on that Pack configuration.

Typically, it is desirable to test out a new Pack configuration by:

Creating a new configuration (not disrupting any existing configurations)
Sharing that new configuration with a trusted set of testers and using that Pack configuration in a doc, iterating on it as required.
After the policy has been deemed suitable to the use case, there are two different ways of rolling out the change, depending upon if this is a newly approved Pack or one already in use.
- For a newly approved pack, share the newly create configuration with the users who require it
- If there is an existing configuration already in live docs, modify the existing configuration. Then, delete the configuration used to test the policy.

Additional documentation

There are several mechanisms for getting help about writing Pack configurations:

Contextual editor help: In the Pack configuration editor, as you edit the JSON config there will be tooltips over the various options, autocomplete for options, and highlights for issues in the schema.
Schema documentation: On every Pack listing page (linked from the Coda gallery or the Pack configuration editor), the Administer tab contains a full list of JSON options for the particular pack (including the various formulas, Pack tables, and parameters).

Configuration cookbook: Detailed examples of some common use cases for Pack configurations.

User experience with Pack configurations

This sections explains what members of your org will experience when encountering various aspects of Pack configurations.

When installing a Pack

Once Pack approvals are enabled for your org, members can only install a Pack if they’ve been given access via at least one Pack configuration. When a Pack is installed, the configuration associated with that Pack (and all policies contained within) is bound to that doc until the Pack is uninstalled from the doc.

If the user does not have access to any Pack configurations: If a none of the existing configurations for that Pack give access to this particular user, the user will be unable to install a Pack and will be given the option to request access to a Pack.
If the user has access to multiple configurations: In some instances, it may be desirable to have multiple configurations for a single Pack. For example, you could have a limited Pack configuration applicable to your entire organization, and then a more open configuration for a trusted set of users. In such a case, the installing user will get a prompt similar to the one below asking them which configuration they want to bind to the Pack.

Disabled Pack functionality

When an org admin restricts Pack functionality, this is exposed to the user via a number of mechanisms.

Disabled user experience: Coda will disable parts of the Packs experience that are incompatible with the installed Pack configuration of the doc. Members will see a message in their doc that explains the limitation.
Runtime errors: When an action occurs that violates the policy of a Pack configuration, Coda will return an error telling the user that the action they tried to perform violates the policies of the IT administrator.
Uninstalling a Pack: When an action occurs that causes the doc and Pack to become incompatible with the configuration that the Pack was installed with, the Pack will be uninstalled. For more details on when this happens, see Policy enforcement amid changes.

FAQs

Which Packs can I create custom configurations for?

Pack configurations are a platform-level concept within Coda and can be used to control and configure the usage of all Packs within Coda.

What happens if I update a Pack configuration?

If a Pack is already in use in docs in your org, you may wonder what will happen when you make changes to (or even delete) the configuration for that Pack. When a Pack configuration is updated, the behavior depends on the kind of policy change that was made. If they are connection changes or changes to restrict access to a specific pack component / scope, the updated policy would apply to any new docs that’d be created. Existing docs with Pack connections will be unaffected but any invocation of the restricted pack components will be blocked.

If the policy change was made to restrict sharing of docs containing Pack data, the Pack will be uninstalled from docs that use this configuration and are incompatible with the updated policy.

You can read more about various scenarios here.

What happens when a user group has access to a Pack config but the user is removed from the group?

If the user is deleted from a group or if the group is deleted, we will automatically uninstall the Pack from their documents. The user will no longer be able to able to install the Pack if they don’t have access to it.

I have a config that restricts sharing docs that have data from a specific Pack to only those users that are allowed access to the Pack. What happens if the user tries to share the doc more broadly?

If doc sharing restrictions are enabled for a Pack, users will not be able to share docs that have data from that specific Pack with unintended users. Coda will block users from sharing the doc with members that do not have access to the Pack. If the doc is moved to folder that has users who don’t have access to the Pack config, the Pack will be uninstalled from the doc. To learn more about how different changes to user, doc or folder affect policy enforcement, see Policy enforcement amid changes.

What happens if an org member / group is deleted from a Pack configuration?

When permission on a Pack configuration is deleted, all Pack installs using that configuration are evaluated to see if the installer of the Pack configuration still has access to the configuration.

If neither the original Pack installer nor the doc owner have access to the Pack configuration, then the pack is uninstalled.

If doc.sharing.enforcePackConfigurationPermissions is set to true in the configuration, we will also validate that the updated set of permissions on the Pack configuration remains compatible with the doc permissions for all Pack installs using the configuration. If they are not compatible, the Pack will be uninstalled.