Now that we know how to hide a ribbon button and how to add our custom buttons to the forms, the next step is to make these buttons do something a little more intelligent than just bring up a pop-up message.
For the purpose of this recipe, we can either continue on the customizations started in the Adding a new ribbon button recipe at the beginning of this chapter, or re-create the button and the action as described there.
In order to kick off a workflow using a ribbon button, perform the following steps:
- Add your new form button as described in the first recipe of this chapter.
- Create your custom workflow as part of the same solution.
- Start the workflow manually.
- Go to System Jobs and find the job running the workflow.
- Do a copy link. Paste that link into Notepad. You will see the following at the end of the link:
id=%7b[GUID]%7d
Where [GUID] is of the format
XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX. - Copy that GUID, as we will need it as a parameter in our JScript function.
- Add a new JScript web resource that contains our function.
- Add the following JScript function to our web resource:
function launchWorkflow(dialogID, typeName, recordId) { // Load modal var serverUri = Xrm.Page.context.getServerUrl() + "/cs/dialog/rundialog.aspx"; window.showModalDialog(serverUri + '?DialogId=' + dialogID + '&EntityName=' + typeName + '&ObjectId=' + recordId, null, 'width=615,height=480,resizable=1,status=1,scrollbars=1'), // Reload form window.location.reload(true); } - Export your solution to a location on your machine.
- Unzip the solution file and remember the location.
- Edit the
customizations.xmlfile within the unzipped solution. - Find the
Leadentity section. - Find the
RibbonDiffXmlsection within theLeadtag. - Find the ribbon button definition, and within it find the
Actionssegment. - Replace the Actions with the following XML code:
<Actions> <JavaScriptFunction Library="$webresource:Nav_JS_Common_Lib" FunctionName="launchWorkflow"> <!– workflowId, entityName, entityId –> <StringParameter Value="{e1037cac-756c-46e7-96d0-cdc572eafc65}" /> <StringParameter Value="lead" /> <CrmParameter Value="FirstPrimaryItemId" /> </JavaScriptFunction> </Actions> - Save and Publish your solution.
- Test it by creating a new Lead and clicking the new ribbon button.
The solution presented is comprised of the following main actions:
- Create a system workflow.
- Add a new ribbon button.
- Define the ribbon button action through JScript to point it to the custom workflow created.
Within the customizations.xml file, the following tags are important:
CustomActions: It allows us to define the location of where the ribbon button appears.CommandUIDefinition: It is a container control that defines user interface elements along with properties such aslabel,tooltip, andicon.CommandDefinition: It defines the command to be executed.Actions: It allows us to customize the JScript function to execute or the URL to forward to. In this section we can also define parameters.CrmParameter: It permits us to pass information directly from the calling form. In our example we passed the GUID of theLeadrecord.
In order to process a workflow rather than a dialogue, we can use a similar approach, and point to the workflow ID. In addition, for more complex situations, we can launch workflows from a dialogue, or vice versa.
- For additional details on parameters, see the MSDN documentation at http://msdn.microsoft.com/en-us/library/gg309332.aspx.