xRM Formula #286 - Custom Dialogs - Replace Close Opportunity Functionality

Views:

Overview

There are many scenarios when you need to build custom dialogs to meet your business requirements. With the North52 business rules engine we make it easy to create a custom dialog using standard forms and North52 functions.

In this example we are going to replace the out-of-the-box Close Opportunity functionality which can't be modified via configuration. For another example of updating multiple Opportunities via a custom dialog form, see this knowledge article.

Rules for Custom Close Opportunity Dialog

Rule #	Description
1	When a user selects an Opportunity from the main grid they can Close the Opportunity using a custom ribbon button and custom form. Clicking the button opens a dialog form with Won/Loss, Actual Amount and Actual Close Date fields set to required and the Loss Reason field hidden.
2	The user can choose to select whether to close the Opportunity as Won or Lost.
3	If Won is selected the Actual Amount and Actual Close Date fields are required and the Loss Reason field is hidden.
4	If Lost is selected, the Actual Amount is set to zero and disabled, and the Loss Reason field is shown and set to required.
5	The user then clicks the North52 Quick Button Close Opportunity, which calls a North52 Formula to create an Opportunity Close records using the values supplied in the form. After processing has completed the window is closed.

North52 Decision Suite Solution

The North52 Decision Suite solution works like this (note you need Business Process Activities v1.0.0.642, Quick Button v9.30 and Quick Ribbon v9.30 or later to build this functionality):

A custom form is set up on the Opportunity table which is configured with a North52 Quick Button
A custom ribbon button is set up to open the custom form using the North52 Quick Ribbon functionality
A Formula is set up on the Opportunity Form which after being opened with the custom ribbon button:
- Sets initial field values and requirements on load
- Set field values and requirements on change of the Win/Loss field
A Formula is set up on the Opportunity table which is called by the North52 Quick Button:
- Creates an Opportunity Close record with the values from the form passed into the Formula from the Quick Button
- Once the Opportunity Close record has been created the Formula closes the custom dialog form

Set up Custom Form, Ribbon Button, and Formulas

There are multiple components needed to build the custom dialog form to close an Opportunity. The steps are outlined in the following sections.

Custom Form

The custom form will be opened as a dialog window to allow the user to input values. It will not save data like a traditional form as we only use it to capture information to be passed to a Formula which then processes the information. The steps to allow this to happen are outlined below:

Create a new Main Form called Custom Close Opportunity Form
Remove tabs and sections so that the form has only a single tab and section
- To remove required fields from the form e.g. Owner, add a column to a Tab and move all required fields to this column. Then remove the column from the Tab. The required fields will be removed with the column.
- Rename the remaining section to Complete the details below to close this Opportunity
Create a new Single Line of Text field called Bulk Edit Guids, add it to the form and check the Hide option - this will be used to contain the Opportunity GUID of the selected record in the main grid
Create a new Choice field with the two choices Won and Lost, and add it to the form
Add the existing fields Actual Revenue and Actual Close Date to the form
Create a new Multiple Lines of Text field called Loss Reason, add it to the form and check the Hide option (it will be shown by a Formula if the Lost option is selected)
Add a HTML Web Resource and select North52 Quick Button Unified Interface web resource (the North52 Quick Button solution needs to have been previously installed)
- In the Custom parameter data field enter (See the North52 Quick Button documentation for details on these parameters):
```
Sav|Close Opportunity|pure-button button-success|submitmodevisible|||||Are you sure you want to close this Opportunity?
```
- Set the Component Height option to 1 row
- Set the Scrolling option to Never
- Uncheck the Display Border option
Set the Section, Tab and Related to be Hidden (use the Show Hidden toggle to display even when set to hidden)
Add event functions to the form to remove the chrome and disable save (this allows the form to behave like a dialog when interacting with North52 Formulas):
- Under the On Save section click on Event Handler
  - Select the Javascript Command Execution (north52_/javascript/commandexecution) library (you will need to add this to the form, search for command execution)
  - For Function enter North52.CommandExecution.TurnOffAutoSave
  - Check the Pass execution context as first parameter option
- Under the On Load section click on Event Handler
  - Select the Javascript Command Execution library
  - For Function enter North52.CommandExecution.HideChrome
  - Check the Pass execution context as first parameter option
- Under the On Load section click on Event Handler
  - Select the Javascript Command Execution library
  - For Function enter North52.CommandExecution.SetSubmitModeNeverAllFields
  - Check the Pass execution context as first parameter option
Click Save and Publish

Ribbon Button

The custom ribbon button needs to be added your App:

Open the App in which you wish to place the custom ribbon button
Edit the command bar for the Opportunities view
Select the Main grid
Add a new Command button in the desired position with the following settings:
- Label: Custom Close Won/Loss
- Icon: Use Icon, MarkAsWon
- Action: Run JavaScript
- Library: north52_quick_ribbon.js
- Function Name: N52QuickRibbon.OpenForm
- Add 7 Parameters in the following order:
  1. PrimaryControl
  2. SelectedControlSelectedItemIds
  3. String, n52demo_bulkeditguids (this is the field that will be used to pass selected record GUIDs to the Formula)
  4. String, opportunity (schema table name)
  5. String, GUID (guid of the custom form to open when button is clicked)
  6. String, Close Opportunity (title to be displayed on modal popup form)
  7. String, refreshlist (this refreshes the list when the modal form is closed)
- Visibility: Show on condition of formula
- Formula bar: CountRows(Self.Selected.AllItems)=1
- Click Save and Publish

Formula - UI Rules

This Formula controls the user interface rules. It has two sheets; Onload Setup and Won/Loss Change. To create the Formula:

Open the North52 App
Navigate to Business Process Activities > Formulas
Create a new formula, setting the following values in the Formula Guide:
- Source Entity set to Opportunity
- Set Formula Type to ClientSide - Perform Action
- Select the Decision Table editor
Change the Name of the formula to Opportunity - Modal Demo - Close Opportunity Form UI
Click Save
Expand Source & Target
Ctrl-Select Onload and Won/Loss from the Custom Close Opportunity Form Events

Sheet - Onload Setup

Double click the sheet name and rename to Onload Setup
Select cell A2, then from the Functions list select GetFormTriggerEvent
- Select cell A4 and enter 'onload'
Select columns B to G, right-click and select Insert > Insert Action
Select cell B2, then from the Source tree select the Won/Lost column
- Select cell B4, then from the Functions list Ctrl+Click the SetRequiredFields function, this will enter {{{SetRequiredFields}}} into the cell
Select cell C2, then from the Source tree select the Actual Close Date column
- Select cell C4, then from the Functions list Ctrl+Click the SetRequiredFields function
Select cell D2, then from the Source tree select the Actual Close Date column
- Select cell D4, then from the Functions list select LocalDateTime
Select cell E2, then from the Source tree select the Actual Revenue column
- Select cell C4, then from the Functions list Ctrl+Click the SetRequiredFields function
Select cell F2 and enter Show Tab
- Select cell F4, then from the Function list Shift+Click the ShowTabs function to open the Function Wizard
  - Ignore the Friendly Name field
  - Click the Search Icon for the Tabs field and select Custom Close Opportunity Form > Summary
  - Click Generate
  - ShowTabs('Summary') is entered in the cell
Select cell G2 and enter Show Section
- Select cell G4, then from the Function list Shift+Click the ShowSections function to open the Function Wizard
  - Ignore the Friendly Name field
  - Click the Search Icon for the Sections field and select Custom Close Opportunity Form > Summary > Complete the details below to close this Opportunity
  - Click Generate
  - ShowSections('Summary.bulkedit') is entered in the cell
Save the Formula

Sheet - Won/Loss Change

Right-click on the sheet and select Insert > Insert Decision Table
Double click the sheet name and rename to Won/Loss Change
Select cell A2, then from the Functions list select GetFormTriggerEvent
- In cells A4 and A5 enter 'n52demo_wonlost' (the schema name of your custom field created above)
With a cell selected in column B right-click and select Insert > Insert Condition
Select cell B2, then from the Source tree select the Won/Lost column
- Select cell B4, then from the Source tree expand Won/Loss and select Lost
Select columns C to F, right-click and select Insert > Insert Action
Select cell C2, then from the Source tree select the Loss Reason column
- Select cell C4, then expand the cell editor by clicking the + icon in the top right of the editor
- From the Functions list Ctrl+Click the ShowFields function
- Press Enter
- From the Functions list Ctrl+Click the SetRequiredFields function
- Collapse the cell editor
- With cell C4 selected, right-click and select Cells > Toggle Word Wrap
- Expand the height of row 4 to show the both the functions in C4
- Select cell C5 and repeat above steps to add HideFields, SetNotRequiredFields and ClearFields functions
Select cell D2, then from the Source tree select the Actual Revenue column
- Select cell D4, then and enter 0
- Select cell D5, then from the Functions list Ctrl+Click the ClearFields function
Select cell E2, then from the Source tree select the Actual Revenue column
- Select cell E4, then from the Functions list Ctrl+Click the DisableFields function
- Select cell E5, then from the Functions list Ctrl+Click the EnableFields function
Select cell F2 and enter Default Action
- Select cell F6 and enter 'NoOp' (Note: the reason why we have a NoOp specified here is that for ClientSide Formulas with multiple sheets there needs to be a final action that is always returned for the Formula to execute correctly)
Save the Formula

Publish Formula

When binding a ClientSide Formula to Form events, the Formula needs to be Published. Select Commands > Publish Formula

Formula - Quick Button Rules

This Formula controls the Opportunity Close rules initiated by the Quick Button. It has two sheets; Create Opportunity Close Record and Close Form. To create the Formula:

Open the North52 App
Navigate to Business Process Activities > Formulas
Create a new formula, setting the following values in the Formula Guide:
- Source Entity set to Opportunity
- Set Formula Type to ClientSide - Calculation
- Select the Decision Table editor
Change the Name of the formula to Opportunity - Modal Demo Close Opportunity Quick Button
In the Form header enter Sav in the Short Code field (this is to match the short code entered in the Quick Button web resource parameters above)
Click Save

Sheet - Create Opportunity Close Record

Double click the sheet name and rename to Create Opportunity Close Record
Right-click on the sheet and select Set Sheet Options > Use Create Record
Select cell A2, then from the Source tree select the Won/Lost column
- Select cell A4, then from the Source tree expand Won/Loss and select Won
- Select cell A5, then from the Source tree expand Won/Loss and select Lost
Select cell B2, enter Close Opportunity
- Select cell B4, then from the Functions list select WinOpportunity
  - Delete the placeholder text 'opportunity_guid' including quotes and leave the cursor positioned in its place
  - From Source select Bulk Edit Guids
  - Delete the placeholder text 'status' including quotes, and replace with the number 3 (this corresponds to the Won status)
  - Delete the placeholder text 'closedate' including quotes and leave the cursor positioned in its place
  - From Source select Actual Close Date
  - Delete the placeholder text description leaving the quotes, as we are not updating the Opportunity Close record description for Won opportunities
  - Delete the placeholder text 'actualrevenue' including quotes and leave the cursor positioned in its place
  - From Source select Actual Revenue
- Select cell B5, then from the Functions list select LoseOpportunity
  - Delete the placeholder text 'opportunity_guid' including quotes and leave the cursor positioned in its place
  - From Source select Bulk Edit Guids
  - Delete the placeholder text 'status' including quotes, and replace with the number 5 (this corresponds to the Out-Sold status)
  - Delete the placeholder text 'closedate' including quotes and leave the cursor positioned in its place
  - From Source select Actual Close Date
  - Delete the placeholder text 'description' including quotes and leave the cursor positioned in its place
  - From Source select Loss Reason
  - Delete the placeholder text 'actualrevenue' including quotes and replace with 0, as no revenue is obtained when the Opportunity is lost
Click Save

Sheet - Close Form

This sheet simply closes the modal window once the previous sheet has executed.

Right-click on the sheet and select Insert > Insert Decision Table
Right-click on the sheet and select Set Sheet Options > Use ClientSide
Select cell B2, enter Close Modal Form
Select cell B4, then from the Functions list select CloseUI
Click Save

Testing

Open the App where you added the command button and navigate to the Opportunities main grid. Select an open Opportunity record and click the Custom Close Won/Loss ribbon button (you may need to refresh your browser several times for the published changes to show).