Customize global option sets

Applies to Dynamics 365 (online), version 9.x

Typically, you use global option sets to set fields so that different fields can share the same set of options, which are maintained in one location. You can reuse global option sets. You will also see them used in request parameters in a manner similar to an enumeration.

When you define an option value by using CreateOptionSetRequest, we recommend that you let the system assign a value. You do this by passing a null value when you create the new OptionMetadata instance. When you define an option, it will contain an option value prefix specific to the context of the publisher set for the solution that the option set is created in. This prefix helps reduce the chance of creating duplicate option sets for a managed solution, and in any option sets that are defined in organizations where your managed solution is installed. For more information, see Merge option set options.


The following table lists the messages that you can use with global option sets.

Message Web API Operation SDK Assembly
CreateOptionSet Use POST request to create a new global option set. CreateOptionSetRequest
DeleteOptionSet Use DELETE request to delete a global optin set. DeleteOptionSetRequest
Deletes one of the values in a global option set.
DeleteOptionValue Action DeleteOptionValueRequest
Inserts a new option into a global option set.
InsertOptionValue Action InsertOptionValueRequest
Inserts a new option into the global option set used in the Status attribute.
InsertStatusValue Action InsertStatusValueRequest
Changes the relative order of the options in an option set.
OrderOption Action OrderOptionRequest
RetrieveAllOptionSets Use GET request to retrieve all the global option sets. RetrieveAllOptionSetsRequest
RetrieveOptionSet Use GET request to retrieve a global option set. RetrieveOptionSetRequest
UpdateOptionSet Use PUT request to update a global option set. UpdateOptionSetRequest
Updates an option in a global option set.
Inserts a new option into the option set used in the Status attribute.
UpdateStateValue Action UpdateStateValueRequest

Retrieve a global option set

The following sample shows how to retrieve a global option set by name using the RetrieveOptionSetRequest message:

// Use the RetrieveOptionSetRequest message to retrieve  
// a global option set by it's name.
RetrieveOptionSetRequest retrieveOptionSetRequest =
    new RetrieveOptionSetRequest
        Name = _globalOptionSetName

// Execute the request.
RetrieveOptionSetResponse retrieveOptionSetResponse =

Console.WriteLine("Retrieved {0}.",

// Access the retrieved OptionSetMetadata.
OptionSetMetadata retrievedOptionSetMetadata =

// Get the current options list for the retrieved attribute.
OptionMetadata[] optionList =

Create a global option set

Use the CreateOptionSetRequest message to create a new global option set. Set the IsGlobal property to true to indicate that the option set is global. The following code example creates a global option set called “Example Option Set”:

#region How to create global option set
// Define the request object and pass to the service.
CreateOptionSetRequest createOptionSetRequest = new CreateOptionSetRequest
    // Create a global option set (OptionSetMetadata).
    OptionSet = new OptionSetMetadata
        Name = _globalOptionSetName,
        DisplayName = new Label("Example Option Set", _languageCode),
        IsGlobal = true,
        OptionSetType = OptionSetType.Picklist,
        Options = 
        new OptionMetadata(new Label("Open", _languageCode), null),
        new OptionMetadata(new Label("Suspended", _languageCode), null),
        new OptionMetadata(new Label("Cancelled", _languageCode), null),
        new OptionMetadata(new Label("Closed", _languageCode), null)

// Execute the request.
CreateOptionSetResponse optionsResp =

Create a picklist that uses a global option set

The following sample shows how to create a picklist attribute that uses a global option set by using CreateAttributeRequest:

// Create a Picklist linked to the option set.
// Specify which entity will own the picklist, and create it.
CreateAttributeRequest createRequest = new CreateAttributeRequest
    EntityName = Contact.EntityLogicalName,
    Attribute = new PicklistAttributeMetadata
        SchemaName = "sample_examplepicklist",
        LogicalName = "sample_examplepicklist",
        DisplayName = new Label("Example Picklist", _languageCode),
        RequiredLevel = new AttributeRequiredLevelManagedProperty(AttributeRequiredLevel.None),

        // In order to relate the picklist to the global option set, be sure
        // to specify the two attributes below appropriately.
        // Failing to do so will lead to errors.
        OptionSet = new OptionSetMetadata
            IsGlobal = true,
            Name = _globalOptionSetName


Update a global option set

The following sample shows how to update the label for a global option set by using UpdateOptionSetRequest:

// Use UpdateOptionSetRequest to update the basic information of an option
// set. Updating option set values requires different messages (see below).
UpdateOptionSetRequest updateOptionSetRequest = new UpdateOptionSetRequest
    OptionSet = new OptionSetMetadata
        DisplayName = new Label("Updated Option Set", _languageCode),
        Name = _globalOptionSetName,
        IsGlobal = true


//Publish the OptionSet
PublishXmlRequest pxReq1 = new PublishXmlRequest { ParameterXml = String.Format("<importexportxml><optionsets><optionset>{0}</optionset></optionsets></importexportxml>", _globalOptionSetName) };

Ordering options

The following sample shows how the options in a global option set can be ordered by using OrderOptionRequest:

// Change the order of the original option's list.
// Use the OrderBy (OrderByDescending) linq function to sort options in  
// ascending (descending) order according to label text.
// For ascending order use this:
var updateOptionList =
    optionList.OrderBy(x => x.Label.LocalizedLabels[0].Label).ToList();

// For descending order use this:
// var updateOptionList =
//      optionList.OrderByDescending(
//      x => x.Label.LocalizedLabels[0].Label).ToList();

// Create the request.
OrderOptionRequest orderOptionRequest = new OrderOptionRequest
    // Set the properties for the request.
    OptionSetName = _globalOptionSetName,
    // Set the changed order using Select linq function 
    // to get only values in an array from the changed option list.
    Values = updateOptionList.Select(x => x.Value.Value).ToArray()

// Execute the request

//Publish the OptionSet
PublishXmlRequest pxReq4 = new PublishXmlRequest { ParameterXml = String.Format("<importexportxml><optionsets><optionset>{0}</optionset></optionsets></importexportxml>", _globalOptionSetName) };

Retrieve all global option sets

The following sample shows how to retrieve all global option sets by using RetrieveAllOptionSetsRequest:

// Use RetrieveAllOptionSetsRequest to retrieve all global option sets.
// Create the request.
RetrieveAllOptionSetsRequest retrieveAllOptionSetsRequest =
    new RetrieveAllOptionSetsRequest();

// Execute the request
RetrieveAllOptionSetsResponse retrieveAllOptionSetsResponse =

// Now you can use RetrieveAllOptionSetsResponse.OptionSetMetadata property to 
// work with all retrieved option sets.
if (retrieveAllOptionSetsResponse.OptionSetMetadata.Count() > 0)
    Console.WriteLine("All the global option sets retrieved as below:");
    int count = 1;
    foreach (OptionSetMetadataBase optionSetMetadata in
        Console.WriteLine("{0} {1}", count++,
            (optionSetMetadata.DisplayName.LocalizedLabels.Count >0)? optionSetMetadata.DisplayName.LocalizedLabels[0].Label : String.Empty);

Delete a global option set

The following sample shows how to check whether a global option set is being used by another solution component by using RetrieveDependentComponents message (RetrieveDependentComponents Function or RetrieveDependentComponentsRequest), and then how to delete it by using DeleteOptionSet message (For Organization Service, use DeleteOptionSetRequest):

  // Create the request to see which components have a dependency on the
  // global option set.
  RetrieveDependentComponentsRequest dependencyRequest =
      new RetrieveDependentComponentsRequest
          ObjectId = _optionSetId,
          ComponentType = (int)componenttype.OptionSet

  RetrieveDependentComponentsResponse dependencyResponse =

  // Here you would check the dependencyResponse.EntityCollection property
  // and act as appropriate. However, we know there is exactly one 
  // dependency so this example deals with it directly and deletes 
  // the previously created attribute.
  DeleteAttributeRequest deleteAttributeRequest =
      new DeleteAttributeRequest
      EntityLogicalName = Contact.EntityLogicalName,
      LogicalName = "sample_examplepicklist"


  Console.WriteLine("Referring attribute deleted.");
  // Finally, delete the global option set. Attempting this before deleting
  // the picklist above will result in an exception being thrown.
  DeleteOptionSetRequest deleteRequest = new DeleteOptionSetRequest
      Name = _globalOptionSetName


See also

Customize Dynamics 365 Customer Engagement applications
Extend the Metadata Model for Dynamics 365
Insert, update, delete, and order global option set options
Sample: Create Global Option Set
Sample: Work with Global Option Sets
Sample: Dump Global Option Set Information to a File