Pass Microsoft Dynamics 365 data from a page as a parameter to Ribbon Actions


Updated: November 29, 2016

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

When you define an action in a ribbon, you frequently have to pass data from the page to either a JavaScript function or a URL. This topic describes options for using the <CrmParameter> (RibbonDiffXml) element to retrieve these values.

The majority of the values available for the <CrmParameter> (RibbonDiffXml) element are related to working with data displayed in a grid or hierarchy chart. By using the Value attribute enumeration options, you can easily isolate items by:

  • Selected items

    • SelectedControlSelectedItemCount

    • SelectedControlSelectedItemIds

    • SelectedControlSelectedItemReferences

  • All items

    • SelectedControlAllItemCount

    • SelectedControlAllItemIds

    • SelectedControlAllItemReferences

  • Unselected items

    • SelectedControlUnselectedItemCount

    • SelectedControlUnselectedItemIds

    • SelectedControlUnselectedItemReferences

For each of these groupings, you can gather the number of items and the GUID identifier. If you are passing the values to a URL, you can also retrieve EntityReference objects that contain all the information that you need to uniquely identify the objects in the grid. These parameters apply whether the page viewed is the main grid (HomepageGrid) or a sub grid located in a form. When used together with the SelectedEntityTypeName parameter, you have all the information that you must have to pass to another application.

With a form ribbon, you can use the collection and the Xrm.Page.ui.controls collection to retrieve values for known fields. However, if you want to pass the value of a selected form field, you’ll have to do more scripting to get the value.

You can use the PrimaryControlId parameter to get the Id value for the control that has focus when the ribbon control received focus. This Id is the Document Object Model (DOM) Id value. To get the data value, you will have to try using that value by using code such as that in the following example:

var focusFieldValue = Xrm.Page.ui.controls.get(PrimaryControlId).getAttribute().getValue()

In addition to data values, you can retrieve additional context information by using <CrmParameter> (RibbonDiffXml).

For convenience, the Value attribute options OrgName, OrgLcid, and UserLcid are available without requiring that you use Xrm.Page.context to use the getOrgUniqueName, getOrgLcid, and getUserId methods. For a <Url> (RibbonDiffXml) action, you can also use the PassParams attribute to include contextual information.

Value options PrimaryEntityTypeName and FirstPrimaryItemId provide information for an entity record. You can use PrimaryItemIds for a HomepageGrid ribbon to get a list of all the displayed items.

Finally, you can use the CommandProperties value to pass details about the event from the ribbon control. You can use this to send contextual information to a central function where specific actions can be determined based on the context of the event.

Microsoft Dynamics 365

© 2016 Microsoft. All rights reserved. Copyright