Permissions System Migration Guide
This document provides suggestions on how to build a migration plan from the legacy permissions management system to the new unified platform permissions system.
Platform Permissions is in Expanded Early Access and is only available to select customers. If you are interested in trying this feature, contact your Tealium Support representative.
Terminology
Before you plan out your migration strategy, review the following basic concepts:
- A product is a grouping of features licensed at the account level (for example, Tealium AudienceStream CDP, Tealium EventStream API Hub, Tealium iQ Tag Management, etc.)
- A feature is a subsection of a product that allows management and access to data and configurations.
- An account contains configuration and access that spans multiple profiles.
- A profile is a configuration set for either Server Side or Client Side products and features.
- A user is an individual login to an account, defined by the user’s email address.
The new unified permissions system introduces the following two new concepts:
- A permission group (usually referred to as group) defines a set of product access levels for the profiles, products, and product features in your account. They also determine publishing rights. Users in a group inherit those permissions for the associated profiles, making it easier for you to manage permissions for a large number of users.
- An admin role defines a set of account access levels for the users in your account. Using admin roles make it easier for you to delegate management of your account and product features to a team of users. Users without admin roles receive a basic user role.
How it works
Previously, account administrators had to administer client-side users, server-side users, and administration rights separately. Separately administering accounts required a lot of time and effort to audit each user’s viewing and editing rights as well as manage their access to profiles.
Tealium now provides a unified permissions system so you can manage user access to your account and profiles through permission groups and admin roles.
For more about the new permissions management system, see Platform Permissions System.
Benefits of migration
Migrating from the old permissions system to the new one gives you an opportunity to audit the permissions, security, and structure of your account:
- Remove users who no longer use the platform or work for your organization.
- Use admin roles to delegate account management responsibility to others.
- Remove unnecessary levels of access on the platform.
- Organize access to profiles for easier management.
- Give permission groups descriptive names for easier security auditing and management.
- Gather data for any future plans to break up profiles into multiple regional profiles to better handle regional brands, offices, management structures, and data privacy compliance regulations.
It is also easier for the Tealium account team to assist you with access issues on the new permissions system than with the legacy system.
Best practices
Some important things to consider as you plan your migration:
- Non-disruptive migration - Building your permissions groups and admin roles under the new permissions system will not disrupt your current permissions and access. Your account will continue to use the legacy permissions until you enable Permissions Enforcement to use the new system. If you have any major problems with the new system, you can switch back to the legacy system to make any necessary changes.
- Permission groups are additive - You can create a permission group with view rights on one profile, create another permission group with Editor rights on other profile, and then add a user to both. The user will inherit permissions from both groups, and if the permissions overlap, the user will inherit the greater permissions for a resource.
- Client-side profiles are separate from server-side profiles - However, you can create a permission group that manages user access to both client-side and server-side profiles, simplifying the process of assigning and managing permissions.
- Access requires a group - To access Tealium, users must be assigned to one or more permission groups that provide the necessary product and feature permissions.
General migration strategy
Use the following steps to help you build your migration strategy:
- Make an inventory of your users’ current access levels and permissions.
- Audit those permissions to ensure they’re accurate for the users’ needs.
- Analyze the results of your audit to determine logical functional groups.
- Add permission groups to match those bundles of access rights to profiles and product features.
- Add users to those permission groups.
- Assign admin roles to users in your account to delegate management of users, features, and profiles.
- Set PII permissions for each user.
- Test the permissions with your users.
- Adjust the permission groups and admin roles as needed.
If you need assistance with this process, contact the Tealium account team.
Planning the permissions structure
Perform the following steps to create an inventory of your current users and permissions:
Step 1: Make an inventory
There are several available methods for you to build an inventory of your current users and their permissions:
Export users
The Export Users function allows you to download a comma-separated value (CSV) file with the account’s users, profiles, and legacy user permissions for each profile. This funcionality makes it easy to audit your users and their permissions to build permission groups and assign admin roles in the new platform permissions system.
- From the client-side’s User Menu, click Manage Users. The table displays a list of users on the account with their general permissions.
- Click Export Users.

Client-side inventory using the User Permissions Exporter Tool
Use the User Permissions Exporter Tealium Tool to export a CSV file that contains each user’s permission on client-side profiles.
- For instructions on how to install and use the Tealium Tool Browser Extension, see Tealium Tools Browser Extension.
- For instructions on how to install and use the User Permissions Exporter, see Tealium Tool User Permissions Exporter.
You must have the Manage Users permission in the active account to run this tool.
The following screenshot demonstrates a downloaded CSV file imported into a Google Sheet, with minor formatting adjustments on row 1 for readability:

Manage Site Scans will appear in the exported data. It is a legacy function, and you will not need it for migration purposes.
In this example, user3 appears three times in the User column. Unlike the other users, who have the same permission on all the profiles on the account, user3 has different permissions on the profiles Website A, Website B, and Website C. Because of this, separate rows in the spreadsheet contain user3’s profile permissions.
Because this tool only exports client-side users and permissions, you will need to export server-side users and permissions manually.
Manual inventory of client-side users and permissions
If you cannot use an automatic export or prefer to perform a manual inventory, you will need to manually collect each user’s permissions on the client side. Perform the following steps to export each users’ permissions on the client side:
- From the client-side’s User Menu, click Manage Users. The table displays a list of users on the account with their general permissions.
- Create a spreadsheet and label the first column Users.
- In the spreadsheet, add the user list to the first column.
- In the spreadsheet, label the second column Profile.
- Click the first account.
- Click Edit/View User Settings. The dialog box displays the user’s permissions on the account and on each profile (Full, Partial, or None).
- In the spreadsheet, create three new columns with this information and note the column names to use later when you are setting up the Manage Account and Manage Users admin roles:
- Account
- Profiles
- JavaScript Code
- Click Close.
- Click Edit/View User Permissions. The dialog box will display the Account, Profiles, and JavaScript permissions (You already have this information).
- Click Next.
- Select Select from Currently Assigned Profile(s).
- Select each profile from the drop-down box and click Next. The dialog box will display the user’s permissions on every profile.
- If the user has the same permissions on every profile, put All in the Profile column of the spreadsheet and note the user’s permissions. If the user has different permissions on profiles, duplicate the user’s row in the spreadsheet so each line represents a different profile, enter the profile names in the Profile column, and note their permissions in columns titled:
- Manage Users
- Manage Resource Locks
- Publish to Dev/Custom Environment
- Publish to QA Environment
- Publish to Prod Environment
- Manage Tag Templates
- Save Existing Versions
- Save As New Versions
- Promote to Dev/Custom Environment
- Promote to QA Environment
- Promote to Prod Environment
- Click Cancel.
- Repeat this process for each user.
You now have all the client side user permissions.
Manual inventory of server-side users and permissions
Perform the following steps to export each user’s permissions on the server side:
- From the server side’s User Menu, click Manage Users. If a server side user doesn’t already exist on the spreadsheet, add it to the first column.
- Click the user account.
- Click Next. The dialog now displays the user’s permissions in every profile.
- If the user has the same permissions on every profile, enter All in the Profile column and note the user’s permissions in the spreadsheet. If the user has different permissions on profiles, duplicate the user’s row in the spreadsheet so each line represents a different profile, enter the profile names in the Profile column, and note the permissions in the appropriate rows.
- No Access - Cannot access profile.
- Reader - Read-only access to profile.
- Editor - Edit and save the profile, but cannot publish.
- Publisher - Editor, plus save and publish the profile
- Click Close
- Repeat this process for each user.
Based on the previous example, the following screenshot demonstrates a spreadsheet updated with server-side users and permissions:

In this example, user6, user7, and user8 do not have any permissions on the client side, and they had to be added manually to the spreadsheet. Also, user7 has different permissions on the server-side profiles App A and App B, so separate rows in the spreadsheet were created for user7’s profile permissions.
You now have all the user permissions for client-side and server-side profiles from the legacy permissions system.
Step 2: Audit the spreadsheet
Now that you have everyone’s permissions in a spreadsheet, check for users with too much access or not enough access to the profiles they need to perform their job. Remember that a user must be in at least one permission group to access a profile’s resources. Update the spreadsheet to reflect their actual needs.
Also, be sure to remove any users who longer work for the company or require access to the account.
Step 3: Add individual needs to the spreadsheet
Now that you have each user’s profile rights on the spreadsheet, you need add some final product and data-level needs to the spreadsheet for each user:
- The level of access to PII data the user should have.
- The products and product features each user should be able to access.
- The level of access each user should have on each product feature.
PII data needs
PII Permissions control who can see PII data and who can edit the Restricted Data property that identifies PII data. Only one level of PII permissions can be assigned to a user. The three levels of PII permissions are as follows:
- No PII – Users can view PII attributes, but cannot see the values of these attributes. PII is obscured wherever it is shown, including Trace and Live Events.
- View – Users can view the values of PII attributes, data but cannot edit or manage PII data.
- Manage & View – Users can view, edit, and manage PII data.
Note in your spreadsheet whether a user should have no access, View access, or Manage & View access for PII.
In EA and EEA, PII permissions are managed by groups. PII permissions management will be moving from group-based management to user-based management in the GA release. We are planning to automatically migrate PII permissions set by group in EA and EEA when this change has been made.
Product and feature needs
Product access permissions specify the Tealium products and features that users can access:
- Tealium iQ Tag Management
- AudienceStream
- EventStream
- Data Access
- Data Connect
- Predict
- Functions
- Server-Side Tools
- Server-Side (Others)
Product access permissions are divided into feature permissions, and may vary depending on the product permissions assigned to the group, as shown in the following table.
Users that have View & Edit or View, Edit & Delete permission also have Save permission.
Product | Features | Available Permissions |
---|---|---|
Tealium iQ Tag Management | JavaScript Extension | No Access View, Edit & Delete |
Advanced JavaScript Extension - Promote to Dev | ||
Advanced JavaScript Extension - Promote to QA | ||
Advanced JavaScript Extension - Promote to Prod | ||
Publish to Dev/Custom | ||
Publish to QA | ||
Publish to Prod | ||
Save | ||
Publish Settings | ||
Code Settings | ||
Resource Lock | ||
Client-Side Versions | No Access View View & Edit |
|
Tag Templates | ||
Tags, Extensions, Load Rules, Data Layer | No Access View View & Edit View, Edit & Delete |
|
AudienceStream | Dashboard | No Access View |
Discovery/Sizing | ||
Audiences | No Access View View & Edit View, Edit & Delete |
|
Audience Connectors | ||
Visitor/Visit Attributes | ||
EventStream | Data Sources | No Access View View & Edit View, Edit & Delete |
Event Attributes | ||
Event Connectors | ||
Event Specs | ||
Live Events | ||
Omnichannel | ||
Data Access | Access Keys | No Access View |
Data Insight | ||
EventStore Legacy | ||
AudienceDB | No Access View View & Edit View, Edit & Delete |
|
EventDB | ||
AudienceStore | No Access View View & Edit View, Edit & Delete |
|
EventStore | ||
Data Connect | Tables | No Access View View & Edit View, Edit & Delete |
Dashboard | No Access View |
|
Integrations | ||
Predict | All features | No Access View View & Edit View, Edit & Delete |
Functions | Credentials/Authentications Global Variables |
No Access View View & Edit View, Edit & Delete |
Server-Side Tools | Manage Rules | No Access View View & Edit View, Edit & Delete |
Visitor Delete | ||
Visitor Lookup | ||
Visitor Profile Sampler | No Access View |
|
Server-Side (Others) | Labels | No Access View View & Edit View, Edit & Delete |
Trace | No Access View |
|
Versions |
Cross-feature permission issues
Carefully consider when you disable access to a feature or product. If you disable access to a feature for a user, that user willl not be able to access the feature in any other features that depend on it. For example:
- If you disable access to AudienceStream audiences for a user, that user will not be able to select an audience to action in an AudienceStream connector.
- If you disable access to server-side labels for a user, the user will not see labels on the server-side. They will still be able to access connectors or other elements with labels on them, but they will not see or be able to edit the labels themselves.
If you disable a product for a user, but the user has server-side Publish permission and access to another product that shares elements with the first product, the user can still publish changes to those shared elements. For example, EventStream and AudienceStream share some elements, such as rules and labels. If a user has Publish permission and only has access to EventStream, they can publish changes to rules and labels they made in EventStream, and those changes will also affect AudienceStream. Similarly, if a user has Publish permission and only has access to AudienceStream, their published changes to rules and labels also affect EventStream.
Update the spreadsheet
Create columns in the spreadsheet for each product and feature, and mark the level of access that the user should have on each.

Congratulations. You now have all your users’ individual needs in the spreadsheet.
The next step is to organize the users into groups.
Step 4: Add organizational information
Every organization has a unique structure, needs, and workflow. Setting permissions to match your organization’s workflow can ensure that each person has access appropriate for their job role, and does not have access to data due to privacy regulations. So, you will need to ask some questions about your users and organization to help sort them into groups.
Here are some suggestions:
- Do you want separate permission groups for your client-side and server-side profiles because different parts of your organization manage these products?
- Do you want to create permission groups based on job responsibilities (Developer, QA, Data Manager, Engineer, Compliance, etc.) so that when you add, move, or remove users, you can quickly assign permissions based on their job title?
- Do you want to break down permission groups by region because your profiles and users are organized by geographic campaigns and sites, and different data storage and data privacy laws apply to them?
- Do you want to break down permission groups by product (AudienceStream, EventStream, Customer Data Hub, etc.)?
For each Yes answer, add another column to the spreadsheet, and add notes in that column about how that question impacts that user’s relationship to the organization and workflow.

Profile audit
If you have only one main client-side profile and one main server-side profile, but your brand and organization is split among multiple regions and responsibility structures, this data can be useful as part of a future project to configure regional profiles on your account. However, Tealium recommends that you set up and test permissions on the new permissions system first.
Step 5: Sort the users into groups
Now that you have all the users’ needs and relationships to the organization documented in your spreadsheet, sort the users by each of the columns.
You can now organize those users into groups based on their common needs and access rights:
- The profiles users in the group needs to access.
- The level of access group members need on each profile.
- Whether group members should have publishing rights for client-side and server-side profiles.
- The products and product features each group should be able to access.
- The level of access each group should have on each product feature.
You can break the users into smaller groups based on your organization’s other needs, such as managing users by department or job function, grouping them by geography, and so on.
These final groups of users are the permission groups you need to create.
Step 6: Add admin roles
Now that you have the groups planned out, it’s time to plan out the admin roles.
Looking at your spreadsheet, ask yourself some questions about the account itself:
- Who needs full access to the account?
- Who will be managing users and user membership in the account’s groups?
- Who will handle the technical configuration of the account?
- Who will be handling the Personally Identifiable Information (PII) data rights on the account?
- Who will be managing the account’s profiles?
The Admin and Profiles settings from the client side inventory of user permissions can help you determine who should get admin roles for the account in the new permission system:
- Account Admin - This role has full access to the account (Includes the permissions of other roles).
- User Admin - This role manages permission groups and user permissions. Anyone responsible for adding users, editing users, and assigning users to permission groups should have this role.
- Technical Admin - This role manages account configuration features, such as first-party domains.
- Privacy Admin - This role manages the PII permission level in groups (Requires the User Admin role). Anyone responsible for data privacy and compliance should be a candidate for this role.
- Profile Admin - This role manages access to profiles and libraries. Anyone who builds and organizes profiles on your account should have this role. This role does not include profile editing or publishing permissions; those are granted through rights in a permission group.
For more information abour admin roles, see Admin Roles.
Deployment strategies
Now that you have your planned list of users, permission groups, and admin roles, you’re ready to deploy your new permissions structure.
- For instructions on how to create a permission group, see Permission Groups.
- For instructions on how to assign an admin role to a user, see Managing Users.
- For instructions on how to enforce the new permissions settings, see Platform Permissions System.
Before turning on Permissions Enforcement, make sure that users have been added to groups and admin role permissions have been assigned to users that manage users, groups, and PII permissions. If you turn on permissions enforcement before you assign users to groups or assign admin roles to users, you may lose access to your account.
The following examples describe strategies for deploying the new permissions system:
Deployment Strategy 1 - Build job functions and roles, then add people
This strategy uses small groups of users with identical needs and roles that you generated after the final audit of your inventory. Users with similar or identical responsibilities can be bundled and added to groups with the correct permissions and access,
- Assign admin roles to the users that will help you with the migration and testing process.
- Create permission groups for the groups of users with identical needs and roles.
- Add users to the appropriate permission groups.
- Warn your users that you will be testing the new permissions system and ask for feedback.
- Set the Permissions Enforcement toggles to ON.
- Gather feedback from your users, and implement any changes in permissions that are necessary.
- If there are too many issues to deal with quickly, set the Permissions Enforcement toggle to OFF so you can revise your plans, permission groups, and admin roles before running another test.
The advantage of this method is that you are organizing users into groups based on similar job responsibilities and roles in your organization, so group membership will parallel your organization chart and workgroups.
The disadvantage is that users who perform multiple or overlapping roles or require special access may need some extra planning and adjustment.
Deployment Strategy 2 - Stacked granular permission groups
Another possible strategy for creating permission groups uses stacking of multiple permission groups to build access for each user. This strategy uses the additive property of permission groups, where a user who is a member of multiple groups inherits the greatest access of those groups. This allows you to manage your users through multiple layers of resource access groups instead of job role or workgroup based groups.
- Assign admin roles to the users that will help you with the migration and testing process.
- Create 4 permission groups: Publish to Dev/Custom, Publish to QA, Publish to Prod, and Publish Server Side.
- Assign users to these groups as necessary based on their rights to publish.
- Create permission groups that bundle access to product features as needed for various roles in your organization (Development, QA, Data Manager, Account Manager, etc.)
- Add users to the appropriate permissions groups.
- Create additional permission groups with:
- Read, Edit, and Delete rights on each profile as necessary
- Read, Edit, and Delete rights on each feature as necessary.
- Add users to the appropriate permissions groups.
- Set PII permissions for each of your users.
- Warn your users that you will be testing the new permissions system and ask for feedback.
- Set the Permissions Enforcement toggles to ON.
- Gather feedback from your users, and implement any changes in permissions that are necessary.
- If there are too many issues to deal with quickly, set the Permissions Enforcement toggle to OFF so you can revise your plans, permission groups, and admin roles before running another test.
The advantage of this method is that you are organizing groups by a resource’s permission levels, and you can add or remove users from groups as their needs change.
The disadvantage is that you need to manage many more groups when a new user joins your organization or when a user changes job responsibilities or leaves.
This page was last updated: March 13, 2023