Изменить

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

This article explains how to create and update Microsoft Dataverse choices (option sets) by using the Web API, so you can maintain consistent option values across table columns. Use global choices when multiple columns need the same options, and use local choices for a specific column.

Note

You can only change an existing managed option set if you're the publisher. To rename or delete an option in these option sets, you must upgrade the solution that added the option set. For more information, see Upgrade or update a solution.

When you define a global option set by 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 you define in environments where your managed solution is installed. For more information, see Merge option set options.

Web API operations for choices

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 don'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

Web API examples for choices

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 by 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 by using a global option set

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

Picklist attribute properties Values
SchemaName sample_Colors
DisplayName Sample Colors
Description Colors Global Picklist Attribute
RequiredLevel None
GlobalOptionSet Set this single-valued navigation property by 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 by using the properties and adds it to the sample_bankaccount table.

The response returns the URI for the attribute.

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, use the UpdateOptionValue Action. The following example updates the TrueOption from the Boolean column example in Create a boolean column and changes the label to Up rather than True. Because this option set is local, the example 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 reorder options in a local option set by using the OrderOption Action. The Value property contains the values of the option in the desired order.

To use this action with a global option set, specify the OptionSetName parameter instead of EntityLogicalName and AttributeLogicalName.

Use the SolutionUniqueName parameter to apply 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 in a local choice column by using the DeleteOptionValue Action.

To use this action with a global option set, specify the OptionSetName parameter instead of EntityLogicalName and AttributeLogicalName.

Use the SolutionUniqueName parameter to apply 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 by 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

  • Last updated on