Tools Variables

Variables tools

This page is generated from the code by scripts/gen_wiki_tools.py — do not edit by hand.

8 tools · category token variables · enable with DATAVERSE_TOOLS=variables (unset enables every category)

Tool-Index · Home

Write tools additionally require DATAVERSE_ALLOW_WRITE=true; delete tools require DATAVERSE_ALLOW_DELETE=true.

---

dataverse_create_environment_variable

Write · non-idempotent · category variables

Create a new environment variable definition and optional initial value.

Creates the environmentvariabledefinition record. If value is supplied a bound environmentvariablevalue record is created in the same operation.

type values: 100000000=String, 100000001=Number, 100000002=Boolean, 100000003=JSON, 100000004=Data source, 100000005=Secret.

Requires DATAVERSE_ALLOW_WRITE=true.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
schema_name	str	yes	—	Schema name for the environment variable definition (e.g., 'new_MyVariable'). Must include a publisher prefix and be unique. (min_len=1, pattern=^[a-zA-Z_][a-zA-Z0-9_]*$)
display_name	str	yes	—	Display name for the environment variable. (min_len=1)
type	int	yes	—	Data type of the environment variable. 100000000=String, 100000001=Number, 100000002=Boolean, 100000003=JSON, 100000004=Data source, 100000005=Secret. (ge=100000000, le=100000005)
default_value	str | None	no	None	Default value stored on the definition. Used when no environment-specific value record exists.
description	str | None	no	None	Description of the environment variable.
value	str | None	no	None	Initial current value to set. If provided, a bound environmentvariablevalue record is created immediately alongside the definition.
solution_unique_name	str | None	no	None	Unique name of the solution to associate the new definition with. Passed as the MSCRM.SolutionUniqueName request header. (pattern=^[a-zA-Z_][a-zA-Z0-9_]*$)

Returns {"created": ..., "schema_name": ..., "display_name": ..., "environment_variable_definition_id": ..., "environment_variable_value_id": ..., "solution_unique_name": ...}. Errors return {"error": true, "message": "..."}.

---

dataverse_create_environment_variable_value

Write · non-idempotent · category variables

Create a new environment variable value record bound to a definition.

Provide definition_id (GUID) or name (schema name or display name) to identify the parent definition. Schema name is tried first; display name is the fallback.

The value record is created via POST with an OData bind to the definition. One value record per definition per environment is the Dataverse convention; use dataverse_update_environment_variable_value to change an existing value.

Requires DATAVERSE_ALLOW_WRITE=true.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
definition_id	str | None	no	None	GUID of the environment variable definition to bind the new value to. Mutually exclusive with name. (min_len=36, max_len=36)
name	str | None	no	None	Schema name or display name of the environment variable definition. Schema name is tried first (exact match); display name is the fallback. Mutually exclusive with definition_id. (min_len=1)
value	str	yes	—	The value to store in the new environmentvariablevalue record. (min_len=1)

Returns JSON. Errors return {"error": true, "message": "..."}.

---

dataverse_delete_environment_variable

Delete · idempotent · category variables

Delete an environment variable definition, its current value, or both.

target='definition' deletes the definition record. Dataverse cascades the delete to the linked value record automatically. target='value' deletes only the environmentvariablevalue record, leaving the definition intact. Useful to reset to the defaultvalue. target='both' explicitly deletes the value record first, then the definition.

Only unmanaged environment variables can be deleted. Managed ones must be removed by uninstalling the owning solution.

Requires DATAVERSE_ALLOW_DELETE=true.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
environment_variable_definition_id	str	yes	—	GUID of the environment variable definition. Required when target is 'definition' or 'both'. When target is 'value', this is used to locate the value record. (min_len=36, max_len=36)
target	str	yes	—	What to delete: 'definition' removes the definition record (and cascades to the value record), 'value' removes only the current value record (leaving the definition intact), 'both' removes the value record first then the definition.

Returns JSON. Errors return {"error": true, "message": "..."}.

---

dataverse_delete_environment_variable_value

Delete · idempotent · category variables

Delete an environment variable value record (reset to default).

Provide exactly one targeting path:

• value_id: delete the value record by its own GUID directly.
• definition_id: resolve the definition, look up its value record, delete it.
• name: resolve the definition by schema name or display name, look up its value record, delete it. Schema name is tried first; display name is the fallback.

Deleting the value record causes the environment variable to fall back to the definition's defaultvalue. The definition itself is not affected. To delete the definition (and cascade to the value), use dataverse_delete_environment_variable with target='definition' or 'both'.

Requires DATAVERSE_ALLOW_DELETE=true.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
value_id	str | None	no	None	GUID of the environmentvariablevalue record to delete directly. Mutually exclusive with definition_id and name. (min_len=36, max_len=36)
definition_id	str | None	no	None	GUID of the environment variable definition. The tool looks up its value record and deletes it. Mutually exclusive with value_id and name. (min_len=36, max_len=36)
name	str | None	no	None	Schema name or display name of the environment variable definition. Schema name is tried first (exact match); display name is the fallback. Mutually exclusive with value_id and definition_id. (min_len=1)

Returns JSON. Errors return {"error": true, "message": "..."}.

---

dataverse_get_environment_variable_values

Read · idempotent · category variables

Get environment variable value record(s).

Provide exactly one targeting path:

• value_id: fetch a single value record by its own GUID directly.
• definition_id: list value record(s) linked to the given definition GUID.
• name: resolve the definition by schema name or display name, then list its value record(s). Schema name is tried first; display name is the fallback.

Returns a list shape (records, count, has_more) in all cases for a consistent calling convention, even when a single record is expected. When no value record exists for a definition the list will be empty.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
value_id	str | None	no	None	GUID of the environmentvariablevalue record to fetch directly. Mutually exclusive with definition_id and name. (min_len=36, max_len=36)
definition_id	str | None	no	None	GUID of the environment variable definition whose value record(s) to retrieve. Mutually exclusive with value_id and name. (min_len=36, max_len=36)
name	str | None	no	None	Schema name or display name of the environment variable definition. Schema name is tried first (exact match); display name is the fallback. Mutually exclusive with value_id and definition_id. (min_len=1)
top	int	no	50	Maximum number of value records to return. (ge=1, le=5000)

Returns JSON. Errors return {"error": true, "message": "..."}.

---

dataverse_get_environment_variables

Read · idempotent · category variables

List environment variable definitions with their current values.

Each record includes the definition fields (schemaname, displayname, type, defaultvalue, description, ismanaged) plus the current value from the linked environmentvariablevalue record. The value field is null when no value record exists — fall back to defaultvalue in that case.

Provide name (schemaname or displayname) to look up a single definition. Schema name is tried first; display name is the fallback. name cannot be combined with solution_id or solution_unique_name.

Scope results to a specific solution with solution_id or solution_unique_name (componenttype 380 solutioncomponents query). Omit both to list all definitions in the environment.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
name	str | None	no	None	Schema name or display name of a single environment variable to look up. Schema name is tried first (exact match); display name is the fallback. When provided, returns that single definition merged with its current value. Cannot be combined with solution_id or solution_unique_name. (min_len=1)
solution_id	str | None	no	None	GUID of the solution to scope results to. Only definitions included in this solution are returned. Provide either solution_id or solution_unique_name, not both. Cannot be combined with name. (min_len=36, max_len=36)
solution_unique_name	str | None	no	None	Unique name of the solution to scope results to (e.g., 'MyApp'). Only definitions included in this solution are returned. Provide either solution_unique_name or solution_id, not both. Cannot be combined with name. (min_len=1, pattern=^[a-zA-Z_][a-zA-Z0-9_]*$)
top	int	no	50	Maximum number of records to return. (ge=1, le=5000)

Returns JSON. Errors return {"error": true, "message": "..."}.

---

dataverse_update_environment_variable

Write · idempotent · category variables

Update an environment variable definition and/or its current value.

Patches definition fields (display_name, default_value, description) when provided. The value field uses upsert logic: queries for an existing environmentvariablevalue record and PATCHes it if found, otherwise POSTs a new one bound to the definition.

Requires DATAVERSE_ALLOW_WRITE=true.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
environment_variable_definition_id	str	yes	—	GUID of the environment variable definition to update. (min_len=36, max_len=36)
display_name	str | None	no	None	New display name for the environment variable. (min_len=1)
default_value	str | None	no	None	New default value to set on the definition.
description	str | None	no	None	New description for the environment variable.
value	str | None	no	None	New current value. If an environmentvariablevalue record already exists it is PATCHed; otherwise a new one is POSTed bound to this definition.

Returns JSON. Errors return {"error": true, "message": "..."}.

---

dataverse_update_environment_variable_value

Write · idempotent · category variables

Update an existing environment variable value record.

Provide exactly one targeting path:

• value_id: PATCH the value record by its own GUID directly.
• definition_id: resolve the definition, look up its value record, PATCH it.
• name: resolve the definition by schema name or display name, look up its value record, PATCH it. Schema name is tried first; display name is the fallback.

If no value record exists for the resolved definition, returns an error — use dataverse_create_environment_variable_value to create one first.

Requires DATAVERSE_ALLOW_WRITE=true.

Param	Type	Req	Default	Notes
dataverse_url	str	yes	—	Required Dataverse organization URL for this request (e.g., 'https://yourorg.crm.dynamics.com').
value_id	str | None	no	None	GUID of the environmentvariablevalue record to PATCH directly. Mutually exclusive with definition_id and name. (min_len=36, max_len=36)
definition_id	str | None	no	None	GUID of the environment variable definition. The tool looks up its value record and PATCHes it. Mutually exclusive with value_id and name. (min_len=36, max_len=36)
name	str | None	no	None	Schema name or display name of the environment variable definition. Schema name is tried first (exact match); display name is the fallback. Mutually exclusive with value_id and definition_id. (min_len=1)
value	str	yes	—	The new value string to store in the value record. (min_len=1)

Returns JSON. Errors return {"error": true, "message": "..."}.

---