|
| 1 | +--- |
| 2 | +title: "Bypass Custom Business Logic (Microsoft Dataverse) | Microsoft Docs" |
| 3 | +description: "Make data changes which bypass custom business logic" |
| 4 | +ms.custom: "" |
| 5 | +ms.date: 05/27/2021 |
| 6 | +ms.reviewer: "pehecke" |
| 7 | +ms.service: powerapps |
| 8 | +ms.topic: "article" |
| 9 | +author: "JimDaly" |
| 10 | +ms.author: "jdaly" |
| 11 | +manager: "ryjones" |
| 12 | +search.audienceType: |
| 13 | + - developer |
| 14 | +search.app: |
| 15 | + - PowerApps |
| 16 | + - D365CE |
| 17 | +--- |
| 18 | +# Bypass Custom Business Logic |
| 19 | + |
| 20 | +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. |
| 21 | + |
| 22 | +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. |
| 23 | + |
| 24 | +The option described here allows you to disable custom synchronous plug-ins for specific requests sent by an application configured to use this option. |
| 25 | + |
| 26 | +For these kinds of situations, you have the option to disable custom business logic which would normally be applied. There are two requirements: |
| 27 | + |
| 28 | +- You must send the requests using the `BypassCustomPluginExecution` option. |
| 29 | +- The user sending the requests must have the `prvBypassCustomPlugins` privilege. By default, only users with the system administrator security role have this privilege. |
| 30 | + |
| 31 | +> [!NOTE] |
| 32 | +> 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](#adding-the-prvbypasscustomplugins-privilege-to-another-role) |
| 33 | +
|
| 34 | +## What does this do? |
| 35 | + |
| 36 | +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: |
| 37 | + |
| 38 | +- Plug-ins which are part of the core Microsoft Dataverse system or part of a solution where Microsoft is the publisher. |
| 39 | +- Workflows included in a solution where Microsoft is the publisher. |
| 40 | + |
| 41 | +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. |
| 42 | + |
| 43 | +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. |
| 44 | + |
| 45 | +> [!IMPORTANT] |
| 46 | +> 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. |
| 47 | +
|
| 48 | +## How do I use the BypassCustomPluginExecution option? |
| 49 | + |
| 50 | +You can use this option with either the Web API or the Organization service. |
| 51 | + |
| 52 | +### Using the Web API |
| 53 | + |
| 54 | +To apply this option using the Web API, pass `MSCRM.BypassCustomPluginExecution : true` as a header in the request. |
| 55 | + |
| 56 | +**Example request:** |
| 57 | + |
| 58 | +The following Web API request will create a new account record without custom business logic applied: |
| 59 | + |
| 60 | +```http |
| 61 | +POST https://yourorg.api.crm.dynamics.com/api/data/v9.1/accounts HTTP/1.1 |
| 62 | +MSCRM.BypassCustomPluginExecution: true |
| 63 | +Authorization: Bearer [REDACTED] |
| 64 | +Content-Type: application/json |
| 65 | +Accept: */* |
| 66 | +
|
| 67 | +{ |
| 68 | + "name":"Test Account" |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | + |
| 73 | +### Using the Organization Service |
| 74 | + |
| 75 | +There are two ways to use this with the Organization Service. |
| 76 | + |
| 77 | +#### You can set CrmServiceClient.BypassPluginExecution Property to true |
| 78 | + |
| 79 | +The following example sets the [CrmServiceClient.BypassPluginExecution Property](/dotnet/api/microsoft.xrm.tooling.connector.crmserviceclient.bypasspluginexecution) when creating a new account record: |
| 80 | + |
| 81 | +```csharp |
| 82 | +var svc = new CrmServiceClient(conn); |
| 83 | + |
| 84 | +svc.BypassPluginExecution = true; |
| 85 | + |
| 86 | +var account = new Entity("account") |
| 87 | +{ |
| 88 | + Attributes = { |
| 89 | + { "name", "Test Account" } |
| 90 | + } |
| 91 | +}; |
| 92 | + |
| 93 | +svc.Create(account); |
| 94 | +``` |
| 95 | +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. |
| 96 | + |
| 97 | +#### You can set the value as an optional parameter with one of the Request classes |
| 98 | + |
| 99 | +The following example sets the optional `BypassCustomPluginExecution` parameter when creating a new account record: |
| 100 | + |
| 101 | +```csharp |
| 102 | +var svc = new CrmServiceClient(conn); |
| 103 | + |
| 104 | +var account = new Entity("account") |
| 105 | +{ |
| 106 | + Attributes = { |
| 107 | + { "name", "Test Account" } |
| 108 | + } |
| 109 | +}; |
| 110 | + |
| 111 | +var createRequest = new CreateRequest |
| 112 | +{ |
| 113 | + Target = account |
| 114 | +}; |
| 115 | +createRequest.Parameters.Add("BypassCustomPluginExecution", true); |
| 116 | + |
| 117 | +svc.Execute(createRequest); |
| 118 | +``` |
| 119 | +This optional parameter must be applied to each request individually. You cannot use this with the 7 other IOrganizationService Methods, such as Create, Update, Delete. You can only use the [Execute method](/dotnet/api/microsoft.xrm.sdk.iorganizationservice.execute) using one of the classes that are derived from the [OrganizationRequest Class](/dotnet/api/microsoft.xrm.sdk.organizationrequest). |
| 120 | + |
| 121 | +You can use this method for data operations you initiate in your plug-ins. |
| 122 | + |
| 123 | +## Adding the prvBypassCustomPlugins privilege to another role |
| 124 | + |
| 125 | +Because the `prvBypassCustomPlugins` 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. |
| 126 | + |
| 127 | +The `prvBypassCustomPlugins` privilege has the id `148a9eaf-d0c4-4196-9852-c3a38e35f6a1` in every organization. |
| 128 | + |
| 129 | +### Using Web API |
| 130 | + |
| 131 | +Associate the `prvBypassCustomPlugins` privilege to the security role using the `roleprivileges_association` collection-valued navigation property. |
| 132 | + |
| 133 | +**Request** |
| 134 | + |
| 135 | +```http |
| 136 | +POST [Organization URI]/api/data/v9.1/roles(<id of role>)/roleprivileges_association/$ref HTTP/1.1 |
| 137 | +Content-Type: application/json |
| 138 | +Accept: application/json |
| 139 | +OData-MaxVersion: 4.0 |
| 140 | +OData-Version: 4.0 |
| 141 | +
|
| 142 | +{ |
| 143 | +"@odata.id":"[Organization URI]/api/data/v9.1/privileges(148a9eaf-d0c4-4196-9852-c3a38e35f6a1)" |
| 144 | +} |
| 145 | +``` |
| 146 | + |
| 147 | +**Response** |
| 148 | + |
| 149 | +```http |
| 150 | +HTTP/1.1 204 No Content |
| 151 | +OData-Version: 4.0 |
| 152 | +``` |
| 153 | + |
| 154 | +More information: [Add a reference to a collection-valued navigation property](webapi/associate-disassociate-entities-using-web-api.md#add-a-reference-to-a-collection-valued-navigation-property). |
| 155 | + |
| 156 | +### Using the Organization Service |
| 157 | + |
| 158 | +Associate the `prvBypassCustomPlugins` privilege to the security role using the `roleprivileges_association` relationship. |
| 159 | + |
| 160 | + |
| 161 | +```csharp |
| 162 | +var roleId = new Guid(<id of role>); |
| 163 | +service.Associate( |
| 164 | + "role", |
| 165 | + roleId, |
| 166 | + new Relationship("roleprivileges_association"), |
| 167 | + new EntityReferenceCollection { |
| 168 | + { |
| 169 | + new EntityReference("privilege", new Guid("148a9eaf-d0c4-4196-9852-c3a38e35f6a1")) |
| 170 | + } |
| 171 | + } |
| 172 | +); |
| 173 | +``` |
| 174 | + |
| 175 | +More information: [Associate and disassociate entities using the Organization Service](org-service/entity-operations-associate-disassociate.md). |
| 176 | + |
| 177 | + |
| 178 | +## Frequently asked questions (FAQ) |
| 179 | + |
| 180 | +### Does this bypass plug-ins for data operations by Microsoft plug-ins? |
| 181 | + |
| 182 | +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. |
| 183 | + |
| 184 | +### Can I use this option for data operations I perform within a plug-in? |
| 185 | + |
| 186 | +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](/dotnet/api/microsoft.xrm.sdk.organizationrequest). You cannot use the CrmServiceClient in a plug-in. |
| 187 | + |
| 188 | +### What about asychronous plug-in steps, asynchronous workflows and flows? |
| 189 | + |
| 190 | +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. |
| 191 | + |
| 192 | +## See also |
| 193 | + |
| 194 | +[Web API: Compose HTTP requests and handle errors](webapi/compose-http-requests-handle-errors.md)<br /> |
| 195 | +[Passing optional parameters with a request](org-service/use-messages.md#passing-optional-parameters-with-a-request) |
| 196 | + |
0 commit comments