Translation on Uwe Braig

SfMetadataToolkit: Bulk manage Picklist Values, Labels and Translations in Salesforce with Excel

Fri, 17 Jul 2026 00:00:00 +0000

The Configuration Challenge

Creating, updating and translating picklist values in Salesforce can be a time-consuming exercise. In this article, I will:

Review how this is done manually via the Salesforce Setup UI.
Briefly examine the metadata XML file that can be extracted and deployed via the Salesforce Command Line Interface (CLI).
Demonstrate how an Excel-based data dictionary can be used as input for the SfMetadataToolkit to generate deployment-ready metadata.

Via The Salesforce Setup UI

This requires multiple steps in the Setup UI. A typical sequence to add and translate values looks like this:

Navigate to the Global Value Set / Picklist Value Set:
- Click New to add new picklist values. This is the only step in the sequence where a bulk-operation is possible by copying and pasting multiple values in one go.
- If you want the Master Label to differ from the API value, then go through all values one by one and click Edit to update Label and/or API Name.
- If you want to reorder the values to a specific sequence, click Reorder to move individual values up and down, one click at a time.
If you then want to translate the labels, you have to go to a different setup screen: Navigate to the Translation Workbench:
- Select the first language.
- Navigate to Setup Component ‘Global Value Set’.
- Select the value set and wait to see the current translations.
- Click through all translations to add/update.
- Click Save.
If you need this for another language, repeat the Translation Workbench process.

Obviously, this is not an efficient approach for more than some one-off changes.

An example for a picklist value set as shown in the Salesforce Setup UI

An example for a picklist edit operation in the Salesforce Setup UI

An example for a picklist translation in the translation workbench

Via the Salesforce Command Line Interface (CLI)

With the Salesforce Command Line Interface (CLI, also known as SFDX), you get direct access to the raw XML version of the metadata, in this case a Picklist Value Set, in your local file system:

Retrieve the files via sf project retrieve command(s), e.g. as given below.
Edit the XML file(s) as needed.
(Re-)Deploy with the corresponding counterpart sf project deploy start ...

1
2
3


sf project retrieve start -m GlobalValueSet:MyPicklistValueSet
sf project retrieve start -m GlobalValueSetTranslation:MyPicklistValueSet-en
sf project retrieve start -m GlobalValueSetTranslation:MyPicklistValueSet-de

Example output for the preceding retrieve command

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSet xmlns="http://soap.sforce.com/2006/04/metadata">
    <customValue>
        <fullName>A</fullName>
        <default>false</default>
        <label>A - Master Label</label>
    </customValue>
    <customValue>
        <fullName>B</fullName>
        <default>false</default>
        <label>B - Master Label</label>
    </customValue>
    <customValue>
        <fullName>C</fullName>
        <default>false</default>
        <label>C - Master Label</label>
    </customValue>
    <masterLabel>My Picklist Value Set</masterLabel>
    <sorted>false</sorted>
</GlobalValueSet>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


<?xml version="1.0" encoding="UTF-8"?>
<GlobalValueSetTranslation xmlns="http://soap.sforce.com/2006/04/metadata">
 <valueTranslation>
 <masterLabel>A - Master Label</masterLabel>
 <translation>A - German Translation</translation>
 </valueTranslation>
 <valueTranslation>
 <masterLabel>B - Master Label</masterLabel>
 <translation>B - German Translation</translation>
 </valueTranslation>
 <valueTranslation>
 <masterLabel>C - Master Label</masterLabel>
 <translation>C - German Translation</translation>
 </valueTranslation>
</GlobalValueSetTranslation>

Obviously, this isn’t an efficient approach either because you now have to deal with XML syntax and its associated pitfalls.

Introducing SfMetadataToolkit

This approach at a glance:

Fill your picklist values, labels and translations into an Excel (or a corresponding .csv) template.
Run the toolkit’s importer and builder commands to create the corresponding metadata XML files
Optionally, run the diff tool of your choice (e.g. git diff) to see changes.
Use Salesforce CLI to deploy.

The full benefit is realized if you use the spreadsheet as a Data Dictionary holding the source of truth: The Data Dictionary is the documentation that is always up to date because the metadata is automatically derived from it.

Build Metadata From The Excel-based Template

Fill in the worksheet _GlobalValueSets to declare the Global Picklist Value Sets to be created:

Worksheet ‘_GlobalValueSets’ of the Excel template

Fill in the worksheet _PicklistValues and for each Picklist Value Set, define the order, values, labels and translations as needed:

Worksheet ‘_PicklistValues’ of the Excel template

Run the following toolkit commands:

1
2
3


$Metadata = Import-SfMetadataModel -Path .\EXAMPLE-DataDictionary.xlsx
Build-SfGlobalValueSetMetadata $Metadata
Build-SfGlobalValueSetTranslationMetadata $Metadata -LanguageCodes ('de', 'en')

Build Metadata From The CSV Template

The toolkit also accepts CSV files as long as those are structured the same way. So, if you prefer sources other than Excel, here is the way to go.

Prepare the file _GlobalValueSets.csv:

Example file _GlobalValueSets.csv

Prepare the file _PicklistValues.csv:

Example file _PicklistValues.csv

Put all relevant CSV files together into one directory and run the following toolkit commands:

1
2
3


$Metadata = Import-SfMetadataModel -Path .\csv-example\
Build-SfGlobalValueSetMetadata $Metadata
Build-SfGlobalValueSetTranslationMetadata $Metadata -LanguageCodes ('de', 'en')

Examine and Diff the Result Files as Needed

The resulting files in the force-app folder look like this:

Resulting force-app folder as shown in Visual Studio Code

Deploy…:

1

sf project deploy start -m GlobalValueSet GlobalValueSetTranslation

…and enjoy:

The deployed picklist value sets as per Salesforce Setup UI

A single example deployed picklist value set as per Salesforce Setup UI

Deployed picklist label translations as per Translation Workbench in Salesforce Setup UI

How It Works

The SfMetadataToolkit operates on top of the Salesforce project structure managed by Salesforce CLI. It does not communicate directly with your Salesforce org nor does it issue any sf cli commands on its own. Instead, it only reads from and writes to the *.*-meta.xml files in the force-app folder. So it can be combined with any DevOps/deployment workflow, IDE and diff tool (git or non-git-based) of your choice.

📝 Note

If you don’t yet have a full developer setup: The minimum requirement is the CLI itself. You don’t have to set up VS Code (Notepad++ with XML plugin will do), you don’t need git (any file diff tool of your choice will do, e.g. Notepad++) and you don’t need to configure a Dev Hub.

You can use it for any one-off mass-creation of picklist values. The full strength of this approach, however, becomes apparent when you let the data dictionary be the source of truth for your implementation. With the metadata created from the documentation, the documentation and the implementation will always be in sync.

With certain limitations, it will also support a round-trip approach where the data dictionary Excel can be reverse-engineered from the org’s metadata.

How To Get It

The module is based on PowerShell 7.x, which is open source and available on Windows, macOS, and Linux:

Install PowerShell on Windows, Linux, and macOS
PowerShell on GitHub
What is PowerShell?

The SfMetadataToolkit is published on Codeberg and on the PowerShell Gallery:

SfMetadataToolkit
To install: Install-Module -Name SfMetadataToolkit
Codeberg Repo

PowerShell directly supports importing from and exporting to CSV files. To work with .xlsx files, the ImportExcel module needs to be installed from the PowerShell Gallery:

ImportExcel
To install: Install-Module -Name ImportExcel
GitHub Repo

What’s Next

This Data-Dictionary-driven approach has been battle-tested in various projects over the past years. The PowerShell code is currently being refactored and cleaned from some technical debt in order to be published as open source gradually. So stay tuned to see more functionality to come.

How to get Picklist Labels in Salesforce Flow

Fri, 16 Aug 2024 00:00:00 +0000

When working with picklist fields in Salesforce Flows, e.g. in a formula or a text template, the flow can only “see” the picklist API value and not the picklist label as shown in the GUI. This might not be an issue in your org if API value and label are configured to be always same and translation workbench is not in use. In all other cases, this can create usability constraints, e.g. when it comes to showing picklist values in Screen Flows or sending e-mails from within the Flow.

I will discuss the following solutions:

Use the Picklist screen component to extract the label.
Use a set of Get Record elements to query the PicklistValueInfo standard object in order to find the label for a given picklist value.
Use an invocable action in Flow to have an APEX class return the information from metadata.

All options in this article focus on handling single records and getting labels to display information on the screen or use text templates, for example to put together e-mails to be sent by the flow.

There are additional challenges when it comes to working with record collections, for example, to be used in the Data Table screen component. There might be a future article about this.

The Basic Scenario

A Salesforce org with the translation workbench enabled.
Active languages are English, German and Spanish.
Translations are in place for English and German only.
A custom object MyCustomObject__c and its corresponding custom tab.
A custom picklist field MyPicklist__c using the global value set MyPicklistValueSet.
This global value set and its translations are shown in the table below.

MyPicklistValueSet

Our example record looks like this:

Example Record

We do a simple flow that gets the example record by its record ID and puts its fields on a screen component:

Basic Scenario Flow

The screen component will show:

The Field component for the custom field MyPicklist__c of our example record.
A Display Text component that outputs the content of
a) the picklist field directly,
b) a text formula field referencing the picklist field,
c) a text template referencing the picklist field.

Field Component

Display Text Component

Text Formula

Text Template

And here comes what is wrong with it when we run this flow: Although the field component properly renders the picklist field with its (translated) label as we would expect it, all further references to the picklist only show the API value.

Flow Output

Solution #1: Picklist Choice Set

There is a difference between putting the Field Component of the picklist custom field on a screen and putting a Picklist Choice Set on a screen. As opposed to the basic scenario, here we use the Picklist Choice Set:

Add a new ressource of type Picklist Choice Set.
Set Object to the custom object where our picklist field is located.
Set the picklist field.

MyPicklistChoiceSet

Now the first component in our screen will be a picklist component that will refer to above Picklist Choice Set:

Multiple Options = No
Component Type = Picklist
Choice = link to Picklist Choice Set as created above
Default Value = The picklist field value from our example record.

Plus: Add the Picklist Component in the Display Text section.

Picklist Component

Our debug run will now look like this:

Flow Output

The text output of the Picklist Component will also work in formulas and text templates.

Considerations for this approach:

Obviously it will only work in screen flows, i.e. not suitable for record-triggered flows nor scheduled flows.
The Picklist Component must be rendered and visited during the screen flow, i.e. it MUST be shown to the user. It could be set to read-only (Disabled = {!$GlobalConstant.True}), but not to hidden. Otherwise it won’t be initialized with its default value and will be empty on accessing it. This might or might not be compatible with your specific use case.
Not suitable for record collections, especially for showing picklist labels in the Data Table component.
Per-Transaction Flow Limits: Does not count towards “Total number of SOQL queries issued”.
It will always deliver the label for the language of the running user, i.e. either the Master Label or the label as per translation workbench.

Solution #2: „Get Record" to Query PicklistValueInfo

In this approach, we will query the standard objects EntityDefinition, FieldDefinition and PicklistValueInfo with the “Get Record” element in order to get the picklist label:

Query for the object definition of our object MyCustomObject__c
Query for the field definition of our custom field MyPicklist__c
Query for the picklist value info (including the label) for the value in our example record.

Flow with PicklistValueInfo

Here the details for getObjectDefinition:

getObjectDefinition

With the DurableId from there, we can query the field definition:

getFieldDefinition

And with the DurableId of the field definition we can finally query for the Picklist Value Info:

getPicklistValueInfo

Now we are able to reference the picklist label from the result of getPicklistValueInfo and use it in the screen display text or formula fields or text templates:

Display Text Screen Component

Our debug run will now look like this:

Flow Output

Considerations for this approach:

Independent of any screen components, i.e. suitable for screen flows, record-triggered flows and scheduled flows.
Per-Transaction Flow Limits: Each Get Record element counts as a SOQL query towards the “Total number of SOQL queries issued” limit. So be aware when it comes to getting labels for multiple picklist fields and/or with looping, for example, when working for record collections and the Data Table screen component.
It will always deliver the label for the language of the running user, i.e. either the Master Label or the label as per translation workbench.

Solution #3: Invocable Apex Methods

For this approach, we need APEX code that can access the Schema objects and return labels for API values. Such APEX class can provide its methods as an “Invocable Method” which in turn can be accessed in a flow action.

A good summary explanation for invocable actions can be found under https://www.salesforceben.com/salesforce-invocable-apex-methods-a-complete-breakdown/ and an example implementation for such approach can be found under https://unofficialsf.com/flow-action-get-picklist-values/.

Considerations:

All pros and cons of APEX coding, e.g. the need for developer capability and capacity and having proper test classes and code coverage in place.
Per-Transaction Flow Limits: Does not consume SOQL queries within the “Total number of SOQL queries issued” limit.
Suitable for screen flows, scheduled flows and record-triggered after-save flows.
Not suitable for record-triggered before-save flows as those do not allow sub flows and actions.

Conclusion

These approaches are basically just workarounds for a, from my view, major lack of feature in Salesforce flow. It definitely should be a standard feature to be able to chose whether we want to see the API value or the label in the flow. I suggest to vote the following ideas on the IdeaExchange: