Matrix Loader CSV fields and field options upload and export

Use the Matrix Loader to bulk create, edit, and export fields, field options, and product pickers in CPQ. Define data in CSV files with supported columns and formats, then upload or download them for faster configuration management and environment migration.

CSV fields upload

All field types can be added and edited via the Matrix Loader. This section assumes the reader will work in a spreadsheet file (Google Sheets, Microsoft Excel, or similar), then export the result to a CSV file for upload to the Matrix Loader. This topic outlines the columns and data that the Matrix Loader accepts in the field upload.

Table 1. CSV file columns

Column name	Description	Valid values	Notes
field_type	Defines the data type of the field	text | textField boolean | booleanField number | numberField picklist | pickListField	Required
name	The name that the admin sees on field list Admin page	Valid strings can be composed of up to 255 characters, including letters, numbers, spaces, and the following special characters: {}[]()|\~`_^@?<=>;:/.-,+*ʼ&%$#”!	Required
variableName	Distinct string used to reference the field	Valid field variable names consist of up to 128 letters, numbers, and underscores. The first and last character must be a letter or number.	Required; must be unique
required	Not currently used by the application	TRUE | FALSE <empty>	Optional; not currently used by the application
defaultValue	Provide an initial value in field when config experience starts	[See note]	Optional; relevant to textField, booleanField, numberField, and single pickListField only. Multi pickListFields set defaults in the fieldOptions upload file.
minLength	Minimum number of characters accepted	<number>	Optional; relevant to textField only
maxLength	Maximum number of characters accepted	<number>	Optional; relevant to textField only
precision	Define digits of precision to the right of the decimal	<number>	Optional; relevant to numberField only
minValue	Minimum numeric value accepted	<number>	Optional; relevant to numberField only
maxValue	Maximum numeric value accepted	<number>	Optional; relevant to numberField only
selectType	Define whether pickListField is single-select or multi-select	single multi <empty>	Optional; relevant to pickListField only. If <empty>, assumes single

Note:

When a field has defined values, the default value must conform to one of the defined values. For example:

• Valid Boolean field default values are TRUE and FALSE.
• If a number field has minValue or maxValue defined, the specified default value must conform to the definition.
• The default value of a single pickListField must match an option value defined for the field. This option value can be defined in a field option CSV file that is processed by the Matrix Loader in the same batch as the field CSV file.
• Text field values are limited to 2000 characters.

The order of columns is not fixed. For convenience, admins can rearrange the columns in their spreadsheet and the resulting CSV file.

The fields upload explainer file shows the variety of fields and field parameters accepted by the Matrix Loader. Cells with gray backgrounds denote that the cell is not relevant to the context of the row. To download the explainer file, in the Matrix Loader, click the Fields link in the Sample Files section.

Note:

This fileʼs content is not intended to be uploaded to a environment as is. Instead, use the format examples to build an upload file that meets the requirements of your current project, export it to CSV format, and upload it to your environment by using the Matrix Loader.

Just as fields added via the Admin UI must be associated with one or more blueprints, so must fields that are added in bulk via the Matrix Loader. For instructions, see Associate a field with a blueprint.

CSV fields export

For convenience, admins can export a CSV file of fields and field options defined in the environment via the following steps:

1. In the Admin navigation pane, click Fields.

   You see a list of all defined fields.

2. (Optional) Enter a search string and press <enter> to narrow the list of fields.
3. Click Export. A message temporarily appears at the bottom of the page.
4. Click the notification center in the lower left corner.

   

5. Click Download to download the CSV file.

   

The resulting ZIP file contains the fields CSV file and the field options CSV file.

CSV field options upload

The field options upload defines pickListField options and attribution. This section assumes the reader will work in a spreadsheet file (Google Sheets, Microsoft Excel, or similar), then download/export the result to a CSV file for upload to the Matrix Loader. The following outlines the columns and data the Matrix Loader accepts in the field option upload.

Table 2. CSV file columns

Column name	Description	Valid values	Notes
variableName	The variable name of the field for which this rowʼs option will be added	<field variableName>	Required
name	Option name visible to end- user	Valid strings can be composed of up to 255 characters, including letters, numbers, spaces, and the following special characters: {}[]()|\~`_^@?<=>;:/.-,+*ʼ&%$#”!	Required
value	Distinct string will use to reference the field option	Valid field option variable names consist of up to 128 letters, numbers, and underscores. The first and last character must be a letter or number. Field option variable names must be unique in the scope of the same field.	Required
defaultValue	Provide an initial value in field when config experience starts	TRUE FALSE <empty>	Optional; relevant to multi pickListFields only
extendedDescri ption	Contextual description for Admin reference	Valid strings can be composed of up to 255 characters, including letters, numbers, spaces, and the following special characters: {}[]()|\~`_^@?<=>;:/.-,+*ʼ&%$#”!	Optional
imageUrl	Image will show end-user for this pickListField option	<URL>	Optional; for use with pickListField. Display type is defined as VisualPicker or MultiSelectVisua lPicker in layout

The fields upload explainer file shows the variety of field options and field option parameters accepted by the Matrix Loader. Cells with gray backgrounds denote that the cell is not relevant to the context of the row. To download the explainer file, in the Matrix Loader, click the Fields link in the Sample Files section.

Note:

This fileʼs content is not intended to be uploaded to a environment as is. Instead, use the format examples to build an upload file that meets the requirements of your current project, export it to CSV format, and upload it to your environment by using the Matrix Loader.

Field options CSV export

Field options are exported in the same motion used to export fields from CPQ. For instructions, see the "CSV fields Export" section above.

CSV upload: product picker

This section outlines the steps to create a product picker named "My product picker", which will include the following products/options:

• Option1/Product1 - Product One
• Option2/Product2 - Product Two
• Option3/Product3 - Product Three

To create a product picker, follow these steps.

1. Extract a sample CSV file for fields from the Matrix Loader.

   This CSV file should contain the field information required for creating a product picker. Ensure that you add an extra line at the top of the sample file specifying the field type as product picker (this field type may not be present in the sample file).

   

2. Extract a sample CSV file for field options from the Matrix Loader.

   This CSV file should contain the product names that will be displayed in the end-user UI for the fields created in the previous step.

   

3. Create a new .yaml file.

   This file should include the fields contained in the product picker, as defined in the CSV file in Step 1. The .yaml file will be used to link the two CSV files during the upload process in the Matrix Loader. Without it, the product picker will not be created.

   Example .yaml Syntax:

   ---
   - variableName: myProductPicker
   	fields:
   	- variableName: myProductPicker.value
   		target: ProductId
   	- variableName: myProductPicker.select
   	- variableName: myProductPicker.quantity
   		target: ProductQuantity

4. Upload files to the Matrix Loader: Compress the two .csv files and the .yaml file from the previous steps into a zipped folder. Then, go to the Matrix Loader, upload the zipped folder, click Import, and then click Continue.

   

5. Validate in UI: The newly created product picker should be available in the CPQ Admin fields as shown below.

   

CSV export: product picker

To export a product picker, click fields in CPQ Admin. Click Product Pickers, select the product picker to export, and then click Export.

Related tasks

• Matrix Loader: CSV table upload

Related reference

• Matrix Loader: CSV rules upload