CRM OptionSet Mapping Component

Documentation on the SSIS Integration Toolkit for Dynamics 365 component

Using the CRM OptionSet Mapping Component

The CRM OptionSet Mapping Component is an asynchronous SSIS data flow pipeline component offered since v3.0 that can be used to manage the translation and mapping of CRM OptionSet values.

The CRM OptionSet Mapping Component includes the following two pages to configure how you want to perform the translation and mapping for CRM OptionSet values:

  • General
  • Mapping

General Page

The General page of the CRM OptionSet Component allows you to specify the general settings of the CRM OptionSet Mapping component.

CRM OptionSet Mapping Editor

Input Column

The Input Column is the source system column from which you receive text values data that you want to translate to CRM OptionSet values. Note that you will get the translated OptionSet values from this column in the output of the current OptionSet Mapping component, which you can use as the input of the same OptionSet/Picklist field in your CRM destination component that you attach right after the current OptionSet Mapping component (OptionSet/Picklist field of our CRM destination component can take either string values or internal values).

It is worth noting that when working with a multi-select optionset field, the input value for the column should be written in the following format:

Option1;Option2;Option3

Note that we use a semicolon character as the delimiter when providing multiple option values as the input. You want to make sure that there are no spaces after the semicolon, otherwise, our software will treat it as one option - this design is by purpose.

CRM Connection Manager

The CRM OptionSet Mapping component requires a CRM connection in order to retrieve OptionSet metadata from the CRM server. The CRM Connection Manager option will show all DynamicsCRM connection managers that have been created in the current SSIS package.

CRM Entity

The CRM Entity option is used to specify the CRM entity that contains the OptionSet field which you need to work with.

OptionSet/Picklist Field

The OptionSet Picklist Field option allows you to specify which CRM OptionSet field you need to work with (OptionSet used to be called Picklist prior to CRM 2011) for the mapping.

Mapping Page

On the Mapping page, you can specify how you map input values to the OptionSet values in the CRM system, and how you want to handle non-matched values.

CRM OptionSet Mapping Editor

The top part of this window contains a grid that can be used to enter mapping values through four toolbar buttons. The first two buttons allow you to add or delete a mapping entry. The Import button allows you to import from a mapping that you previously saved or exported. The Export button allows you to export all mapping values in the grid to a .xml file so that edits can be made using a different tool that you feel more comfortable with.

The second part of the window is where you specify how to handle non-matched values. There are five options available.

Create option

When no match is found for a particular input value, this option allows you to create a new option using the input value for the specified CRM OptionSet/Picklist field.

When this option is chosen, you will be presented with the following three more options:

  • Internal integer value field(since v5.0) - Specify the input column which contains the internal integer value when creating the option.
  • Input column for statecode - This option is only available when the target OptionSet/Picklist field is statuscode, which allows you to specify the input value of statecode in order to create the statuscode option.
  • Input column for Locale ID(since 9.1) - Specify the Locale ID input to be used when creating new option values. In the case that the option's internal integration value already exists in the target CRM system, the provided label will be updated or created based on the Locale ID provided.
Replace as an existing option

When this option is used, you must specify the option value to be used if no match is found.

Set as empty

This option will set the output value of the column to empty if no match is found.

Leave it as is

This option allows you to pass through the input value without making any changes when no match is found.

Raise an error

This option allows you to throw an exception that fails the component entirely when no match is found for a particular input value.