<CrmParameter> (RibbonDiffXml)

 

Applies To: Dynamics 365 (online), Dynamics 365 (on-premises), Dynamics CRM 2016, Dynamics CRM Online

Represents data retrieved from the Microsoft Dynamics 365 application that may be passed as a parameter.

Syntax

<CrmParameter
 Name = “String”
 Value= ["CommandProperties" |
         "PrimaryEntityTypeCode" |
         "PrimaryEntityTypeName" |
         "PrimaryItemIds" |
         "FirstPrimaryItemId" |
         "PrimaryControl" |
         "PrimaryControlId" |
         "SelectedEntityTypeCode" |
         "SelectedEntityTypeName" |
         "FirstSelectedItemId" |
         "SelectedControl" |
         "SelectedControlSelectedItemCount" |
         "SelectedControlSelectedItemIds" |
         "SelectedControlSelectedItemReferences" |
         "SelectedControlAllItemCount" |
         "SelectedControlAllItemIds" |
         "SelectedControlAllItemReferences" |
         "SelectedControlUnselectedItemCount" |
         "SelectedControlUnselectedItemIds" |
         "SelectedControlUnselectedItemReferences" |
         "OrgName" |
         "OrgLcid" |
         "UserLcid"]
 />

Attributes and Elements

The following table lists the attributes, child elements, and parent elements.

Attributes

Attribute

Description

Type

Usage

Name

Represents the name of a query string parameter passed for this value when using a Url element.

Represents the name of a query string parameter passed using the <Url> (RibbonDiffXml) element.

String

See Remarks

Value

Specifies the value to be passed as a parameter.

Valid values:

Value

Description

CommandProperties

An object with the following three properties: SourceControlId, CommandValueId, and MenuItemId

  • SourceControlId : The Id value of the Ribbon control that initiated the event.

  • CommandValueId : A string that is sent with the command event when a button is clicked.

  • MenuItemId: A reference from a control to the Id of a menu item.

Most entities will not return a MenuItemId value. Only the following entities will return this value:

  • BusinessUnit

  • Connection

  • CustomerAddress

  • Equipment

  • Goal

  • InvoiceDetail

  • Mailbox

  • MailMergeTemplate

  • PartnerApplication

  • QueueItem

  • QuoteDetail

  • RoutingRuleItem

  • SalesOrderDetail

  • ServiceAppointment

  • SharePointDocumentLocation

  • SharePointSite

  • Territory

PrimaryEntityTypeCode

Deprecated. Use PrimaryEntityTypeName instead. A number representing the unique type of entity for a specific Microsoft Dynamics 365 deployment. For custom entities this value will be different for every organization.

PrimaryEntityTypeName

A string representing the unique name of an entity.

PrimaryItemIds

A string array providing the GUID Id values for the Primary Item.

FirstPrimaryItemId

Provides one GUID identifier as a string for the record being viewed.

PrimaryControl

An Object referencing the Control that had focus when the Ribbon Command action occurred.

PrimaryControlId

A string providing the Id value of the control that had focus.

SelectedEntityTypeCode

Deprecated. Use SelectedEntityTypeName instead. A number representing the unique type of entity for a record selected in a grid. The Entity type code will vary between deployments. For custom entities this value will be different for every organization.

SelectedEntityTypeName

A string representing the unique name of the entity for a record selected in a grid.

FirstSelectedItemId

Provides one GUID identifier as a string for the first item selected in a grid.

SelectedControl

An Object referencing the Control that had focus when the Ribbon Command action occurred.

SelectedControlSelectedItemCount

The number of selected items in a grid.

SelectedControlSelectedItemIds

A string array of GUID Id values for all selected items in a grid.

SelectedControlSelectedItemReferences

An array of EntityReference objects that represent all the selected items in the grid.

This option is only available when used with the <JavaScriptFunction> (RibbonDiffXml) element.

SelectedControlAllItemCount

A number showing the total number of items displayed in a grid.

SelectedControlAllItemIds

A string array providing the GUID Id values for all items displayed in a grid.

SelectedControlAllItemReferences

An array of EntityReference objects representing all the items in the grid.

This option is only available when used with the <JavaScriptFunction> (RibbonDiffXml) element.

SelectedControlUnselectedItemCount

The number of unselected items in a grid.

SelectedControlUnselectedItemIds

A string array of GUID Id values for all unselected items in a grid.

SelectedControlUnselectedItemReferences

An array of EntityReference objects representing all the items not selected in the grid.

This option is only available when used with the <JavaScriptFunction> (RibbonDiffXml) element.

OrgName

The name of the organization.

OrgLcid

The Language Code representing the base Language for the organization.

UserLcid

The Language Code representing the language preference chosen by the user..

Enumeration

Required

Child Elements

This element has no child elements.

Parent Elements

Element

Description

<JavaScriptFunction> (RibbonDiffXml)

Specifies an action that calls a function from a specific JavaScript library.

<CustomRule> (RibbonDiffXml)

Specifies a rule used with an EnableRule definition that is composed of a reference to a function within a JavaScript library.

<Url> (RibbonDiffXml)

An action that opens a web page at a specified address.

Remarks

When the CrmParameter is a child of the <Url> (RibbonDiffXml) a Name attribute is required. When the CrmParameter is a child of the <JavaScriptFunction> (RibbonDiffXml) element, the Name attribute is not valid.

Note

  • Value attributes referring to a "Primary..." item refer to the record being viewed in the form.

  • Value attributes referring to the "Selected..." item refer to rows selected within a grid.

When a grid is presented within a form or as an associated view the "Primary.." values refer to the record context in which the grid is displayed. This is true as long as the grid is associated with an entity relationship.

When a grid is displayed independently from any entity relationship, such as in the Homepage grid or if a subgrid is added to a form without being associated with an entity relationship, the "Primary..." values will be null.

Note

Some CrmParameter values pass an EntityReference object. This object contains the following properties:

  • Id: A string of the GUID Id value for the record.

  • Name: A string of the value of the Primary field for the record.

  • TypeName: A string representing the unique name of the entity for the record.

The EntityReference also provides a TypeCode property which is a number representing the unique type of entity for the record. Use of this property is deprecated. Use TypeName instead. The number value for custom entities will typically be different from organization to organization and the number value cannot be used reliably for custom entities.

Element Information

XPath

//RibbonDiffXml/CommandDefinitions/CommandDefinition/Actions/JavaScriptFunction/CrmParameter |
//RibbonDiffXml/CommandDefinitions/CommandDefinition/Actions/Url/CrmParameter |
//RibbonDiffXml/RuleDefinitions/EnableRules/EnableRule/CustomRule/CrmParameter |
//RibbonDiffXml/RuleDefinitions/EnableRules/EnableRule/OrRule/Or/CustomRule/CrmParameter |
//RibbonDiffXml/RuleDefinitions/DisplayRules/DisplayRule/CustomRule/CrmParameter |
//RibbonDiffXml/RuleDefinitions/DisplayRules/DisplayRule/OrRule/Or/CustomRule/CrmParameter

Schema Name

  • CrmParameterType

  • CrmNamedParameterType

Validation File

RibbonTypes.xsd

Can be Empty

Yes

See Also

Customize commands and the ribbon

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright