Dynamically Control Dynamics 365 Command Bar with JavaScript

Introduction to Dynamic Command Bar Visibility in Dynamics 365

The Command Bar in Dynamics 365 is a crucial element, providing users with immediate access to essential actions such as Create, Edit, Delete, Assign, Share, and custom commands. However, there are frequent scenarios where organizations need to dynamically control the visibility of these commands based on specific business logic. By leveraging JavaScript and modern Dynamics 365 APIs, developers can effectively manage command bar action visibility, leading to a more refined user experience and stricter enforcement of business rules.

This article will guide you through the process of hiding and showing Command Bar options dynamically within Dynamics 365 using JavaScript.

Why Hide or Show the Command Bar?

Customizing the command bar offers several key benefits for organizations:

• Restrict Unauthorized Actions: Ensure that only appropriate users can perform certain actions.
• Improve User Experience: Present users with relevant actions, reducing confusion.
• Reduce Interface Clutter: Hide commands that are not currently applicable, leading to a cleaner interface.
• Enforce Business Processes: Ensure actions are taken in the correct order and under the right conditions.
• Display Actions Conditionally: Make commands visible only when specific criteria are met.
• Simplify Navigation: Guide users by showing only the most pertinent options at any given time.

Prerequisites

Before you begin, ensure you have the following:

• A Dynamics 365 Environment.
• A System Customizer or System Administrator role.
• A JavaScript Web Resource.
• (Optional) Ribbon Workbench for advanced customization.
• A basic understanding of JavaScript.

Understanding Command Bar Customization

The Command Bar in Dynamics 365 is primarily controlled through a combination of:

• Ribbon Commands: Define the actions available.
• Enable Rules: Determine if a command is enabled or disabled.
• Display Rules: Determine if a command is visible or hidden.
• JavaScript Functions: Custom logic to drive the visibility and enablement of commands.

Using JavaScript, you can implement custom logic to dictate when a button should appear or remain hidden.

Step-by-Step Guide to Hiding/Showing Commands

Step 1: Create a JavaScript Web Resource

Navigate to your Dynamics 365 environment:

1. Go to Advanced Settings.
2. Select Customizations.
3. Choose Customize the System.
4. Create a new JavaScript Web Resource. A recommended naming convention is CRMONCE_CommandBar.js.
5. Upload and save your JavaScript file.

Step 2: Create a JavaScript Function

Add a JavaScript function to your web resource that will determine the visibility. This function typically receives an executionContext object.

Here's an example function that checks the record's status code:

function showHideCommandBar(executionContext) {
    var formContext = executionContext.getFormContext();
    var status = formContext.getAttribute("statuscode").getValue();

    // Example: Show command only if status is 'Active' (status code 1)
    if (status === 1) {
        return true; // Show the command
    } else {
        return false; // Hide the command
    }
}

This function evaluates the record's status and returns true to display the command or false to hide it.

Step 3: Add the Function to Ribbon Workbench (or use classic customization)

While Ribbon Workbench offers a more visual approach, you can also configure rules directly within the classic customization interface. If using Ribbon Workbench:

1. Open Ribbon Workbench and select your solution.
2. Choose the command button you wish to control.
3. Add a Custom Rule (or an Enable Rule/Display Rule that calls custom JavaScript).
4. Specify the Library (your JavaScript web resource name, e.g., CRMONCE_CommandBar.js) and the FunctionName (e.g., showHideCommandBar).
5. Save and publish your customizations.

Step 4: Configure Enable Rule or Display Rule

You'll need to create either an Enable Rule or a Display Rule that references your JavaScript function. A Display Rule is typically used for visibility.

Example Rule Configuration:

• Rule Name: e.g., ShowButtonWhenStatusActive
• Custom Rule Function:
• Library: CRMONCE_CommandBar.js
• Function Name: showHideCommandBar

The JavaScript function will return true to show the button and false to hide it.

Step 5: Publish Customizations

After configuring your rules and associating them with the command button:

1. Publish All Customizations in Dynamics 365.
2. Refresh your Dynamics 365 application.

The command bar button's visibility will now be controlled dynamically based on the logic defined in your JavaScript function.

Real-Time Example: Approve Request Button

Let's consider a common scenario with a custom button called Approve Request.

Business Requirement:

• Show the Approve Request button only when the record's status is 'Pending Approval'.
• Hide the button when the status is 'Approved'.

JavaScript Function:

function showApproveButton(executionContext) {
    var formContext = executionContext.getFormContext();
    var status = formContext.getAttribute("statuscode").getValue();

    // Assuming 'Pending Approval' has a status code of 100000001
    return status === 100000001;
}

With this function configured as a Display Rule, the Approve Request button will only become visible when the record is in the 'Pending Approval' state.

Alternative Approach: Using Display Rules and Enable Rules

While directly manipulating visibility with JavaScript is possible, Dynamics 365 recommends a more structured approach using built-in rule types:

• Display Rules: Control the visibility of a command.
• Enable Rules: Control whether a command is enabled or disabled.
• Custom Rule Functions: JavaScript functions called by Display or Enable rules.

Benefits of this structured approach:

• Better Performance: Rules can often be evaluated more efficiently.
• Supported Customization Approach: Aligns with Microsoft's recommended practices.
• Easier Maintenance: Separates UI logic from core business logic.
• Improved Scalability: Easier to manage complex rule sets.

Benefits of Dynamic Command Visibility

Implementing dynamic visibility for command bar elements offers significant advantages:

• Enhanced User Experience: Users only see actions relevant to their current context, reducing cognitive load.
• Better Security: Prevents users from attempting actions they are not authorized to perform or that are not applicable.
• Cleaner Interface: Eliminates unnecessary buttons and clutter, making the interface more intuitive.
• Improved Productivity: Users can focus on the available and relevant actions, streamlining workflows.
• Business Rule Enforcement: Commands appear only when business conditions are met, ensuring process adherence.

Best Practices

Follow these best practices when implementing dynamic command visibility:

• Use Enable Rules Whenever Possible: For simple conditional logic, leverage built-in Enable Rules before resorting to custom JavaScript.
• Keep Functions Lightweight: Avoid complex or long-running JavaScript logic within ribbon functions. Refrain from making direct API calls if possible.
• Use Meaningful Function Names: Name your JavaScript functions descriptively, such as showApproveButton(), hideCloseButton(), or showSubmitForReview().
• Test Across Forms: Verify that your dynamic rules function correctly on main forms, quick create forms, and within the Unified Interface.
• Publish After Changes: Always publish all customizations after making updates to ensure they take effect.

Common Use Cases

Dynamic command visibility is useful in various scenarios:

• Approval Processes: Show an 'Approve' or 'Reject' button based on the record's status.
• Record Ownership: Display commands only for the user who owns the record (e.g., 'Edit' or 'Delete').
• Security-Based Visibility: Show specific buttons only to users with certain security roles.
• Stage-Based Actions: Control command visibility according to the current stage in a Business Process Flow.
• Custom Business Logic: Display commands based on the values of specific fields on the form.

Conclusion

Hiding and showing Command Bar buttons dynamically in Dynamics 365 is a powerful technique for creating cleaner user interfaces, improving usability, and effectively enforcing business rules. By utilizing JavaScript in conjunction with Ribbon Workbench, Enable Rules, and Display Rules, developers can precisely control button visibility based on real-time record data and specific business requirements. This approach offers a flexible and user-friendly experience while adhering to Dynamics 365 customization best practices, ultimately leading to a more efficient and compliant application.