Skip to main content

How to deploy a new Custom field with its field-level security settings

Quickly deploy a new Custom field with its FLS

Written by Paddy Lindley

Gearset deploys a new Custom field and its Field-level security (FLS) in one go, so you don't need a second deployment to move the profile changes across.

This guide uses a checkbox field called New Checkbox Field on the Account object as its example, deployed from a developer org to a staging org.

Creating the new Custom field

Create the Custom field in your source org, then set its Field-level security there for the Profiles that need it.

Deploying the field and its field-level security settings

  1. Compare the org you made the change in against the org you want to deploy to. Here, the developer org is the source and the staging org is the target.

  2. Use the On-demand comparison metadata filter, or any filter that includes the Custom object, Profile, and Permission set metadata types, which this deployment needs.

  3. In the comparison results, search for the API name of your field, for example New_Checkbox_Field. The results show a Custom field item and a Custom field permissions item.

  4. Select the Custom field item to add the field to your deployment package.

There are two ways to deploy the field-level security. Pick whichever suits the change.

Option 1: Deploy with the “Permission Set” and/or “Profile” items

Use this option to deploy the field level security change for some Profiles but not all, for example to make the change on the Admin Profile first as a test.

In addition to the Custom field item found within “New” items, the Permission Set and Profile items also affected in the change should appear under the “Changed” heading.

In this New_Checkbox_Field example, the checkbox field has been added to three Profiles:

  • Custom: Support Profile

  • Admin

  • Silver Partner User

To see what changes before you deploy, click any of the Profile items. The diff viewer below it has two tabs:

  • Permissions view (the lock icon, red arrow) shows which profiles the deployment affects.

  • XML viewer (the <> icon, purple arrow) shows the exact XML difference, so you can confirm that only the field permissions change and nothing else in each profile changes.

Select the Profile or Permission Set items you would like to include to add it to the Deployment Package.

Option 2: Deploying with “Custom Field permissions” items

The permissions for the new Custom field will also appear in the comparison as a new Custom field permissions item.

To see what changes before you deploy, click the Custom field permissions item. The diff viewer below it has two tabs:

  • Permissions view shows which profiles the deployment affects.

  • XML viewer shows the exact XML difference, so you can confirm that only the field permissions change and nothing else in each profile changes.

Select the Custom field permissions item corresponding to the targeted Custom field item to add it to the Deployment Package.

Deploying your changes

  1. Click NEXT.

  2. Check the problem analysis and environment variables.

  3. Click Pre-deployment summary and review the Summary of items to deploy.

  4. Click DEPLOY NOW.

Gearset records the deployment in your deployment history, so you can refer back to it later.

Deploying the false field permissions

Gearset doesn't show a field permission in the comparison results when both readable and editable are false:

<editable>false</editable>
<readable>false</readable>

The Salesforce Metadata API can return false permissions as though they don't exist, so rendering every non-existent field permission would be confusing. Gearset suppresses them instead, even when the metadata returns them explicitly.

This matters for CI jobs. Because the source doesn't return the FLS, the change shows as a deleted item rather than a changed item, so a CI job only deploys it if the job is set to deploy deleted changes. The same applies to Apex class and Apex page permissions.

For the full explanation, see False permissions and CI jobs.

Did this answer your question?