update_dataverse_optionset
Modify Dataverse option sets by adding new choices, updating existing options, removing obsolete values, or changing display properties to maintain data consistency across all related columns.
Instructions
Updates an existing option set by modifying its properties and managing its options. Use this to add new choices, update existing ones, remove obsolete options, or change the option set's display name and description. Changes affect all columns using this option set.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addOptions | No | New options to add to the option set | |
| description | No | New description of the option set | |
| displayName | No | New display name for the option set | |
| name | Yes | Name of the option set to update | |
| removeOptions | No | Values of options to remove from the option set | |
| updateOptions | No | Existing options to update |
Implementation Reference
- src/tools/optionset-tools.ts:157-272 (handler)Main handler function executing the tool: updates option set metadata, adds/removes/updates options via Dataverse API actions (InsertOptionValue, DeleteOptionValue, UpdateOptionValue).async (params) => { try { // Update basic properties if provided if (params.displayName || params.description) { // First, retrieve the current option set definition to get MetadataId const currentOptionSet = await client.getMetadata<OptionSetMetadata>( `GlobalOptionSetDefinitions(Name='${params.name}')` ); // Create the updated option set definition by merging current with new values const updatedOptionSet: any = { ...currentOptionSet, "@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata" }; // Update only the specified properties if (params.displayName) { updatedOptionSet.DisplayName = createLocalizedLabel(params.displayName); } if (params.description) { updatedOptionSet.Description = createLocalizedLabel(params.description); } // Use PUT method with MetadataId as per Microsoft documentation // Only OptionSetMetadataBase properties can be updated this way await client.putMetadata( `GlobalOptionSetDefinitions(${currentOptionSet.MetadataId})`, updatedOptionSet, { 'MSCRM.MergeLabels': 'true' } ); } // Add new options using InsertOptionValue action if (params.addOptions && params.addOptions.length > 0) { for (const option of params.addOptions) { const insertOptionData = { OptionSetName: params.name, Value: option.value, Label: createLocalizedLabel(option.label), Description: option.description ? createLocalizedLabel(option.description) : undefined, Color: option.color }; await client.callAction("InsertOptionValue", insertOptionData); } } // Remove options using DeleteOptionValue action if (params.removeOptions && params.removeOptions.length > 0) { for (const optionValue of params.removeOptions) { const deleteOptionData = { OptionSetName: params.name, Value: optionValue }; await client.callAction("DeleteOptionValue", deleteOptionData); } } // Update existing options using UpdateOptionValue action if (params.updateOptions && params.updateOptions.length > 0) { for (const option of params.updateOptions) { const updateOptionData: any = { OptionSetName: params.name, Value: option.value, MergeLabels: true // Required parameter for UpdateOptionValue action }; // Only include properties that are being updated if (option.label) { updateOptionData.Label = createLocalizedLabel(option.label); } if (option.description) { updateOptionData.Description = createLocalizedLabel(option.description); } if (option.color) { updateOptionData.Color = option.color; } await client.callAction("UpdateOptionValue", updateOptionData); } } let message = `Successfully updated option set '${params.name}'.`; if (params.addOptions?.length) { message += ` Added ${params.addOptions.length} options.`; } if (params.updateOptions?.length) { message += ` Updated ${params.updateOptions.length} options.`; } if (params.removeOptions?.length) { message += ` Removed ${params.removeOptions.length} options.`; } return { content: [ { type: "text", text: message } ] }; } catch (error) { return { content: [ { type: "text", text: `Error updating option set: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } }
- src/tools/optionset-tools.ts:138-155 (schema)Zod input schema defining parameters for updating an option set: name, optional displayName/description, addOptions/updateOptions/removeOptions arrays.inputSchema: { name: z.string().describe("Name of the option set to update"), displayName: z.string().optional().describe("New display name for the option set"), description: z.string().optional().describe("New description of the option set"), addOptions: z.array(z.object({ value: z.number().describe("Numeric value for the new option"), label: z.string().describe("Display label for the new option"), description: z.string().optional().describe("Description for the new option"), color: z.string().optional().describe("Color for the new option (hex format)") })).optional().describe("New options to add to the option set"), updateOptions: z.array(z.object({ value: z.number().describe("Numeric value of the option to update"), label: z.string().optional().describe("New display label for the option"), description: z.string().optional().describe("New description for the option"), color: z.string().optional().describe("New color for the option (hex format)") })).optional().describe("Existing options to update"), removeOptions: z.array(z.number()).optional().describe("Values of options to remove from the option set") }
- src/tools/optionset-tools.ts:133-273 (registration)server.registerTool call within the exported updateOptionSetTool function, registering the tool with its schema and handler on the MCP server.server.registerTool( "update_dataverse_optionset", { title: "Update Dataverse Option Set", description: "Updates an existing option set by modifying its properties and managing its options. Use this to add new choices, update existing ones, remove obsolete options, or change the option set's display name and description. Changes affect all columns using this option set.", inputSchema: { name: z.string().describe("Name of the option set to update"), displayName: z.string().optional().describe("New display name for the option set"), description: z.string().optional().describe("New description of the option set"), addOptions: z.array(z.object({ value: z.number().describe("Numeric value for the new option"), label: z.string().describe("Display label for the new option"), description: z.string().optional().describe("Description for the new option"), color: z.string().optional().describe("Color for the new option (hex format)") })).optional().describe("New options to add to the option set"), updateOptions: z.array(z.object({ value: z.number().describe("Numeric value of the option to update"), label: z.string().optional().describe("New display label for the option"), description: z.string().optional().describe("New description for the option"), color: z.string().optional().describe("New color for the option (hex format)") })).optional().describe("Existing options to update"), removeOptions: z.array(z.number()).optional().describe("Values of options to remove from the option set") } }, async (params) => { try { // Update basic properties if provided if (params.displayName || params.description) { // First, retrieve the current option set definition to get MetadataId const currentOptionSet = await client.getMetadata<OptionSetMetadata>( `GlobalOptionSetDefinitions(Name='${params.name}')` ); // Create the updated option set definition by merging current with new values const updatedOptionSet: any = { ...currentOptionSet, "@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata" }; // Update only the specified properties if (params.displayName) { updatedOptionSet.DisplayName = createLocalizedLabel(params.displayName); } if (params.description) { updatedOptionSet.Description = createLocalizedLabel(params.description); } // Use PUT method with MetadataId as per Microsoft documentation // Only OptionSetMetadataBase properties can be updated this way await client.putMetadata( `GlobalOptionSetDefinitions(${currentOptionSet.MetadataId})`, updatedOptionSet, { 'MSCRM.MergeLabels': 'true' } ); } // Add new options using InsertOptionValue action if (params.addOptions && params.addOptions.length > 0) { for (const option of params.addOptions) { const insertOptionData = { OptionSetName: params.name, Value: option.value, Label: createLocalizedLabel(option.label), Description: option.description ? createLocalizedLabel(option.description) : undefined, Color: option.color }; await client.callAction("InsertOptionValue", insertOptionData); } } // Remove options using DeleteOptionValue action if (params.removeOptions && params.removeOptions.length > 0) { for (const optionValue of params.removeOptions) { const deleteOptionData = { OptionSetName: params.name, Value: optionValue }; await client.callAction("DeleteOptionValue", deleteOptionData); } } // Update existing options using UpdateOptionValue action if (params.updateOptions && params.updateOptions.length > 0) { for (const option of params.updateOptions) { const updateOptionData: any = { OptionSetName: params.name, Value: option.value, MergeLabels: true // Required parameter for UpdateOptionValue action }; // Only include properties that are being updated if (option.label) { updateOptionData.Label = createLocalizedLabel(option.label); } if (option.description) { updateOptionData.Description = createLocalizedLabel(option.description); } if (option.color) { updateOptionData.Color = option.color; } await client.callAction("UpdateOptionValue", updateOptionData); } } let message = `Successfully updated option set '${params.name}'.`; if (params.addOptions?.length) { message += ` Added ${params.addOptions.length} options.`; } if (params.updateOptions?.length) { message += ` Updated ${params.updateOptions.length} options.`; } if (params.removeOptions?.length) { message += ` Removed ${params.removeOptions.length} options.`; } return { content: [ { type: "text", text: message } ] }; } catch (error) { return { content: [ { type: "text", text: `Error updating option set: ${error instanceof Error ? error.message : 'Unknown error'}` } ], isError: true }; } } );
- src/index.ts:161-161 (registration)Top-level call to updateOptionSetTool registration helper in the main server initialization file.updateOptionSetTool(server, dataverseClient);
- src/tools/optionset-tools.ts:7-23 (helper)Helper function to create standardized LocalizedLabel objects used in option set metadata updates.function createLocalizedLabel(text: string, languageCode: number = 1033): LocalizedLabel { return { LocalizedLabels: [ { Label: text, LanguageCode: languageCode, IsManaged: false, MetadataId: "00000000-0000-0000-0000-000000000000" } ], UserLocalizedLabel: { Label: text, LanguageCode: languageCode, IsManaged: false, MetadataId: "00000000-0000-0000-0000-000000000000" } };