Bypass Custom Business Logic

There are times when you want to be able to perform data operations without having custom business logic applied. For example, if you are going to import a lot of records which you know already conform to the data consistency logic for your business. You want this operation to be done as quickly as possible, so the additional time spent processing custom logic for each request is something you want to avoid.

One option is to locate and disable the custom plug-ins that contain the business logic. But this means that the logic will be disabled for all users while those plug-ins are disabled. It also means that you have to take care to only disable the right plug-ins and remember to re-enable them when you are done.

The option described here allows you to disable custom synchronous plug-ins for specific requests sent by an application configured to use this option.

For these kinds of situations, you have the option to disable custom business logic which would normally be applied. There are two requirements:

• You must send the requests using the BypassCustomPluginExecution option.
• The user sending the requests must have the prvBypassCustomPlugins privilege. By default, only users with the system administrator security role have this privilege.

Note

The prvBypassCustomPlugins is not available to be assigned in the UI at this time. You can add a privilege to a security role using the API. More information: Adding the prvBypassCustomPlugins privilege to another role

What does this do?

This solution targets the custom synchronous business logic that has been applied for your organization. When you send requests that bypass custom business logic, all synchronous plug-ins and real-time workflows are disabled except:

• Plug-ins which are part of the core Microsoft Dataverse system or part of a solution where Microsoft is the publisher.
• Workflows included in a solution where Microsoft is the publisher.

System plug-ins define the core behaviors for specific entities. Without these plug-ins you would encounter data inconsistencies that may not be easily fixed.

Solutions shipped by Microsoft that use Dataverse such as Microsoft Dynamics 365 Customer Service, or Dynamics 365 Sales also include critical business logic that cannot be bypassed with this option.

Important

You may have purchased and installed solutions from other Independent Software Vendors (ISVs) which include their own business logic. The synchronous logic applied by these solutions will be bypassed. You should check with these ISVs before you use this option to understand what impact there may be if you use this option with data that their solutions use.

How do I use the BypassCustomPluginExecution option?

You can use this option with either the Web API or the Organization service.

Using Web API

To apply this option using the Web API, pass MSCRM.BypassCustomPluginExecution : true as a header in the request.

Example request:

The following Web API request will create a new account record without custom business logic applied:

POST https://yourorg.api.crm.dynamics.com/api/data/v9.1/accounts HTTP/1.1
MSCRM.BypassCustomPluginExecution: true
Authorization: Bearer [REDACTED]
Content-Type: application/json
Accept: */*

{
  "name":"Test Account"
}

Using the Organization Service

There are two ways to use this with the Organization Service.

Set the CrmServiceClient.BypassPluginExecution property

The following example sets the CrmServiceClient.BypassPluginExecution Property when creating a new account record:

var svc = new CrmServiceClient(conn);

svc.BypassPluginExecution = true;

var account = new Entity("account")
{
    Attributes = {
        { "name", "Test Account" }
    }
};

svc.Create(account);

Because this setting is applied to the service, it will remain set for all requests sent using the service until it is set to false.

Set the value as an optional parameter

The following example sets the optional BypassCustomPluginExecution parameter when creating a new account record using the CreateRequest class.

var svc = new CrmServiceClient(conn);

var account = new Entity("account")
{
    Attributes = {
        { "name", "Test Account" }
    }
};

var createRequest = new CreateRequest
{
    Target = account
};
createRequest.Parameters.Add("BypassCustomPluginExecution", true);

svc.Execute(createRequest);

This optional parameter must be applied to each request individually. You cannot use this with the 7 other IOrganizationService methods, such as Create, Update, or Delete. You can only use the Execute method using one of the classes that are derived from the OrganizationRequest class, such as CreateRequest, UpdateRequest, or DeleteRequest.

You can use this method for data operations you initiate in your plug-ins.

Adding the prvBypassCustomPlugins privilege to another role

Because the prvBypassCustomPlugins privilege is not available in the UI to set for different security roles, if you need to grant this privilege to another security role you must use the API. For example, you may want to grant this privilege to a user with the system customizer security role.

The prvBypassCustomPlugins privilege has the id 148a9eaf-d0c4-4196-9852-c3a38e35f6a1 in every organization.

Using Web API

Associate the prvBypassCustomPlugins privilege to the security role using the AddPrivilegesRole Action.

Request

POST [Organization URI]/api/data/v9.1/roles(<id of role>)/Microsoft.Dynamics.CRM.AddPrivilegesRole HTTP/1.1
Content-Type: application/json   
Accept: application/json   
OData-MaxVersion: 4.0   
OData-Version: 4.0 

{
  "Privileges": [
    {
      "PrivilegeId": "148a9eaf-d0c4-4196-9852-c3a38e35f6a1",
      "Depth": "3"
    }
  ]
}

You must set the RolePrivilege.Depth property to PrivilegeDepth.Global (3) because this is a global privilege.

Response

HTTP/1.1 204 No Content  
OData-Version: 4.0  

Using the Organization Service

Associate the prvBypassCustomPlugins privilege to the security role using AddPrivilegesRoleRequest.

var request = new AddPrivilegesRoleRequest
{
    RoleId = new Guid("<id of role>"),
    Privileges = new[]{
        new RolePrivilege{
            PrivilegeId = new Guid("148a9eaf-d0c4-4196-9852-c3a38e35f6a1"),
            Depth = PrivilegeDepth.Global
        }
    }
};
svc.Execute(request);

Frequently asked questions (FAQ)

Does this bypass plug-ins for data operations by Microsoft plug-ins?

No. If a synchronous plug-in or real-time workflow in a Microsoft solution performs operations on other records, the logic for those operations are not bypassed. Only those synchronous plugins or real-time workflows that apply to the specific operation will be bypassed.

Can I use this option for data operations I perform within a plug-in?

Yes, But only when the plug-in is running in the context of a user who has the prvByPassPlugins privilege. For the Organization Service, set the optional BypassCustomPluginExecution parameter on the class derived from OrganizationRequest Class. You cannot use the CrmServiceClient in a plug-in.

What about asychronous plug-in steps, asynchronous workflows and flows?

Asynchronous logic is not bypassed. Asynchronous logic doesn't significantly contribute to the cost of processing the records, therefore it is not by passed by this parameter.

See also

Web API: Compose HTTP requests and handle errors
Passing optional parameters with a request