Create and update choices (option sets) using the Web API

Typically, you use global option sets to set table columns so that different columns can share the same set of options, which are maintained in one location. Unlike local option sets that are defined only for a specific column, you can reuse global option sets. These values are also used in request parameters in a manner similar to an enumeration.

Note

You can only change an existing managed option set if you are the publisher. In order to make a change such as rename option or delete option on these option sets, an Upgrade must be made to the solution that added the option set. More information: Upgrade or update a solution

When you define a global option set using a POST request to [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions, we recommend that you let the system assign a value. Let the system assign the value by passing a null value when you create the new OptionMetadata instance. When you define an option, it contains 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 environments where your managed solution is installed. For more information, see Merge option set options.

Messages

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

Message	Web API Operation
CreateOptionSet	Use POST request to [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions.
DeleteOptionSet	Use DELETE request to [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>').
RetrieveAllOptionSets	Use GET request to [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions.
RetrieveOptionSet	Use GET request to [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>').

The following table lists the messages you can use with local and global option sets

Message	Web API Operation
DeleteOptionValue Deletes one of the values in a global option set.	DeleteOptionValue Action Example: Delete Option
InsertOptionValue Inserts a new option into a global option set.	InsertOptionValue Action Example: Insert options
InsertStatusValue Inserts a new option into the global option set used in the Status column.	InsertStatusValue Action Example: Insert status value
OrderOption Changes the relative order of the options in an option set.	OrderOption Action Example: Order options
UpdateOptionSet	Use PUT request with a OptionSetMetadataBase EntityType to [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions(metadataid) Only those properties defined by the OptionSetMetadataBase can be updated. These properties doesn't include the options. Use other actions to make changes to options.
UpdateOptionValue Updates an option in an option set.	UpdateOptionValue Action Example: Update options
UpdateStateValue Inserts a new option into the option set used in the Status column.	UpdateStateValue Action

Examples

• Create a global option set
• Create a choice column using a global option set
• Insert options
• Update options
• Order options
• Delete Option
• Insert status value

Create a global option set

The following example uses these properties to create a global choice.

OptionSetMetadata properties	Values
Name	sample_colors
DisplayName	Colors
Description	Color Choice
OptionSetType	Picklist
Options	value:727000000, label:Red value:727000001, label:Yellow value:727000002, label:Green

The following example creates global choice using the properties.

The URI for the global choice is returned in the response. You can also refer to this global choice using the name: GlobalOptionSetDefinitions(Name='sample_colors').

Request:

POST [Organization Uri]/api/data/v9.2/GlobalOptionSetDefinitions
MSCRM.SolutionUniqueName: examplesolution
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 2769

{
  "@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata",
  "Options": [
    {
      "Value": 727000000,
      "Label": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [
          {
            "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
            "Label": "Red",
            "LanguageCode": 1033,
            "IsManaged": false
          }
        ],
        "UserLocalizedLabel": {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Red",
          "LanguageCode": 1033,
          "IsManaged": false
        }
      }
    },
    {
      "Value": 727000001,
      "Label": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [
          {
            "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
            "Label": "Yellow",
            "LanguageCode": 1033,
            "IsManaged": false
          }
        ],
        "UserLocalizedLabel": {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Yellow",
          "LanguageCode": 1033,
          "IsManaged": false
        }
      }
    },
    {
      "Value": 727000002,
      "Label": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [
          {
            "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
            "Label": "Green",
            "LanguageCode": 1033,
            "IsManaged": false
          }
        ],
        "UserLocalizedLabel": {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Green",
          "LanguageCode": 1033,
          "IsManaged": false
        }
      }
    }
  ],
  "Description": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Color Choice",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Color Choice",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "DisplayName": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Colors",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Colors",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "Name": "sample_colors",
  "OptionSetType": "Picklist"
}

Response:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/GlobalOptionSetDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Create a choice column using a global option set

The following example uses these properties to create a choice column using a global choice.

Picklist attribute properties	Values
SchemaName	sample_Colors
DisplayName	Sample Colors
Description	Colors Global Picklist Attribute
RequiredLevel	None
GlobalOptionSet	This single-valued navigation property must be set using the @odata.bind syntax with a reference to the global choice. This example uses the MetadataId as the key, but it could also use the alternate key with Name: GlobalOptionSetDefinitions(Name='sample_colors')

The following example creates a local column using the properties and adds it to the sample_bankaccount table.

The URI for the attribute is returned in the response.

Request:

POST [Organization Uri]/api/data/v9.2/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes
MSCRM.SolutionUniqueName: examplesolution
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 1465

{
  "@odata.type": "Microsoft.Dynamics.CRM.PicklistAttributeMetadata",
  "AttributeType": "Picklist",
  "AttributeTypeName": {
    "Value": "PicklistType"
  },
  "SourceTypeMask": 0,
  "GlobalOptionSet@odata.bind": "/GlobalOptionSetDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)",
  "Description": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Colors Global Picklist Attribute",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Colors Global Picklist Attribute",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "DisplayName": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Sample Colors",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Sample Colors",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "RequiredLevel": {
    "Value": "None",
    "CanBeChanged": false,
    "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
  },
  "SchemaName": "sample_Colors"
}

Response:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

Insert options

The following example uses the InsertOptionValue Action to add a new option with the value 727000005 and label Echo to the local choice column created by Create a choice column.

Request:

POST [Organization Uri]/api/data/v9.2/InsertOptionValue
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 612

{
  "AttributeLogicalName": "sample_choice",
  "EntityLogicalName": "sample_bankaccount",
  "Value": 727000005,
  "Label": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Echo",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Echo",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "SolutionUniqueName": "examplesolution"
}

Response:

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.InsertOptionValueResponse",
  "NewOptionValue": 727000005
}

Update options

To update individual options, you must use the UpdateOptionValue Action. The following example updates the TrueOption from the Boolean column example in Create a boolean column and changes the label so that it's Up rather than True. Because this is a 'local' option set, it uses AttributeLogicalName and EntityLogicalName. For a global option set, use the OptionSetName parameter instead.

Request:

POST [Organization Uri]/api/data/v9.2/UpdateOptionValue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "AttributeLogicalName": "new_boolean",
  "EntityLogicalName": "new_bankaccount",
  "Value": 1,
  "Label": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Up",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Up",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "MergeLabels": true
}

Response:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Order options

The following example shows how to re-order options of a local optionset using the OrderOption Action. The Value property contains the values of the option in the desired order.

To use this with a global option set, specify the OptionSetName parameter rather than EntityLogicalName and AttributeLogicalName.

The SolutionUniqueName parameter applies the changes as part of the specified solution.

Request:

POST [Organization Uri]/api/data/v9.2/OrderOption
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 253

{
  "EntityLogicalName": "sample_bankaccount",
  "AttributeLogicalName": "sample_choice",
  "Values": [
    727000002,
    727000000,
    727000003,
    727000001,
    727000005,
    727000004
  ],
  "SolutionUniqueName": "examplesolution"
}

Response:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Delete Option

The following example shows how to delete an option for a local choice column using the DeleteOptionValue Action.

To use this with a global option set, specify the OptionSetName parameter rather than EntityLogicalName and AttributeLogicalName.

The SolutionUniqueName parameter applies the changes as part of the specified solution.

Request:

POST [Organization Uri]/api/data/v9.2/DeleteOptionValue
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 116

{
  "AttributeLogicalName": "sample_choice",
  "EntityLogicalName": "sample_bankaccount",
  "Value": 727000004
}

Response:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Insert status value

The following example shows how to add an option to a status column using the InsertStatusValue Action.

Use the StateCode parameter to specify which statecode option the status value applies to. The SolutionUniqueName parameter applies the changes as part of the specified solution.

The NewOptionValue property returned by the InsertStatusValueResponse ComplexType contains the value assigned to the option.

Request:

POST [Organization Uri]/api/data/v9.2/InsertStatusValue
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 609

{
  "AttributeLogicalName": "statuscode",
  "EntityLogicalName": "sample_bankaccount",
  "Label": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Frozen",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Frozen",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "StateCode": 1,
  "SolutionUniqueName": "examplesolution"
}

Response:

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.InsertStatusValueResponse",
  "NewOptionValue": 727000000
}

See also

Customize choices
Create and edit global choices overview
Create a choice