New capabilities to bypass custom business logic (preview)
[This article is pre-release documentation and is subject to change.]
Preview features aren’t meant for production use and may have restricted functionality. These features are available before an official release so that customers can get early access and provide feedback.
There are two new ways for client developers to bypass custom business logic. Please try these new optional parameters and let us know your thoughts. For issues with these preview features, such as errors received, use the Help + support experience and include the following information: Problem Type- Dataverse Web API and SDK.
When to bypass custom business logic
There are times when you want to be able to perform data operations without having custom business logic applied. These scenarios typically involve bulk data operations where large numbers of records are being created, updated, or deleted.
Without a way to tell Dataverse not to invoke the business logic, you need to locate and disable the custom plug-ins and workflows that contain the business logic. Disabling plug-ins and workflows means that the logic is disabled for all users while those plug-ins and workflows are disabled. It also means that you have to take care to only disable the right plug-ins and workflows and remember to re-enable them when you're done.
Note
The existing BypassCustomPluginExecution
optional parameter is limited because you can only bypass synchronous business logic. These new options provide more flexibility. The BypassCustomPluginExecution
optional parameter will remain supported. When these new capabilities become generally available, they will be our recommended method.
Power Automate flows are not bypassed using these optional parameters.Learn how to bypass Power Automate flows
New optional parameters
The two new optional parameters you can use to bypass custom business logic are introduced in the following table.
Optional parameter | Description |
---|---|
BypassBusinessLogicExecution |
Pass the CustomSync , CustomAsync , or CustomSync,CustomAsync values to this optional parameter to bypass synchronous logic, asynchronous logic or, both. |
BypassBusinessLogicExecutionStepIds |
Pass a comma separated list of plug-in step registrations to bypass only the specified plug-in steps. |
BypassBusinessLogicExecution
The BypassBusinessLogicExecution
optional parameter works similarly to the BypassCustomPluginExecution
optional parameter except that you can choose whether to bypass synchronous logic, asynchronous logic or, both.
This optional parameter targets the custom business logic applied for your organization. When you send requests that bypass custom business logic, all custom plug-ins and workflows are disabled except:
- Plug-ins that 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 might 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 can't 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 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.
The following table describes when to use the parameter values with BypassBusinessLogicExecution
.
Parameter | Description |
---|---|
CustomSync |
Bypass only synchronous custom logic. The compute time necessary for synchronous logic accrues to the total time required to perform each data operation. Use this option to reduce the amount of time required to complete operations in bulk. |
CustomAsync |
Bypass only asynchronous custom logic, excluding Power Automate Flows. Dataverse applies asynchronous logic after an operation completes. When a large number of operations trigger asynchronous logic, Dataverse requires more resources to process the custom logic and this resource consumption can impact performance. Use this option to avoid general performance issues that might occur when large numbers of operations trigger asynchronous logic. |
CustomSync,CustomAsync |
Bypass both synchronous and asynchronous custom logic, excluding Power Automate Flows. |
Requirements to use the BypassBusinessLogicExecution optional parameter
- You must send the requests using the
BypassBusinessLogicExecution
optional parameter. - The user sending the requests must have the
prvBypassCustomBusinessLogic
privilege. By default, only users with the system administrator security role have this privilege. Learn how to add the theprvBypassCustomBusinessLogic
privilege to another role
How do I use the BypassBusinessLogicExecution optional parameter?
You can use this option with either the SDK for .NET or the Web API.
The following example sets the BypassBusinessLogicExecution
optional parameter for both synchronous and asynchronous custom logic when creating a new account record using the SDK for .NET CreateRequest class.
static void DemonstrateBypassBusinessLogicExecution(IOrganizationService service)
{
Entity account = new("account");
account["name"] = "Sample Account";
CreateRequest request = new()
{
Target = account
};
request.Parameters.Add("BypassBusinessLogicExecution", "CustomSync,CustomAsync");
service.Execute(request);
}
BypassBusinessLogicExecutionStepIds
Use the BypassBusinessLogicExecutionStepIds
optional parameter to bypass specified registered plug-in steps instead of all synchronous and asynchronous custom logic. Pass the GUID values of the registered plug-in step registrations with this parameter. If the step ID passed doesn't run in the given request, it's ignored.
How do I use the BypassBusinessLogicExecutionStepIds option?
You can use this option with either the SDK for .NET or the Web API.
The following example sets the optional BypassBusinessLogicExecutionStepIds
parameter when creating a new account record using the CreateRequest class.
static void DemonstrateBypassBusinessLogicExecutionStepIds(IOrganizationService service)
{
Entity account = new("account");
account["name"] = "Sample Account";
CreateRequest request = new()
{
Target = account
};
request.Parameters.Add("BypassBusinessLogicExecutionStepIds", "45e0c603-0d0b-466e-a286-d7fc1cda8361,d5370603-e4b9-4b92-b765-5966492a4fd7");
service.Execute(request);
}
Identify the steps you want to bypass
There are a couple of ways to locate the GUID values of the plug-in step registration.
Use the Plug-in registration tool
From the View menu, select Display by Entity.
Select the entity and message
Select the step.
In the detail pane, the Properties tab shows the StepId. Copy the value from there.
Learn more about the Plug-in registration tool
Query your environment with Web API
Use a query like the following to retrieve the set plug-in step registrations for a given table and message. The following example specifies the account
table, using the table logical name. Create
is the name of the message. Replace these values with the table and message you need.
Request
GET [Organization URI]/api/data/v9.2/sdkmessagefilters?$select=sdkmessagefilterid
&$filter=primaryobjecttypecode eq 'account'
and sdkmessageid/name eq 'Create'
&$expand=sdkmessagefilterid_sdkmessageprocessingstep($select=name;
$filter=statecode eq 0
and customizationlevel eq 1
and iscustomizable/Value eq true)
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0
Response
In the response, look for the sdkmessageprocessingstepid
values. Use the name
value to identify the plug-in that you want to bypass.
In this case, there's only one: 4ab978b0-1d77-ec11-8d21-000d3a554d57
{
"@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sdkmessagefilters(sdkmessagefilterid,sdkmessagefilterid_sdkmessageprocessingstep(name))",
"value": [
{
"@odata.etag": "W/\"31434372\"",
"sdkmessagefilterid": "c2c5bb1b-ea3e-db11-86a7-000a3a5473e8",
"sdkmessagefilterid_sdkmessageprocessingstep": [
{
"@odata.etag": "W/\"115803276\"",
"name": "BasicPlugin.FollowupPlugin: Create of account",
"_sdkmessagefilterid_value": "c2c5bb1b-ea3e-db11-86a7-000a3a5473e8",
"sdkmessageprocessingstepid": "4ab978b0-1d77-ec11-8d21-000d3a554d57"
}
],
"sdkmessagefilterid_sdkmessageprocessingstep@odata.nextLink": "[Organization URI]/api/data/v9.2/sdkmessagefilters(c2c5bb1b-ea3e-db11-86a7-000a3a5473e8)/sdkmessagefilterid_sdkmessageprocessingstep?$select=name&$filter=statecode%20eq%200%20and%20customizationlevel%20eq%201%20and%20iscustomizable/Value%20eq%20true"
}
]
}
Learn more about querying data using Web API
Query your environment with FetchXml
Use a query like the following to retrieve the set plug-in step registrations for a given table and message. The following example specifies 1
to represent the account
table, using the table object type code.
Note
For tables where the object type code is over 10000
, the value will not be the same in every environment because this value is assigned an incrementing value when the table is created.
If you know the logical name of the table, you can get the object type code using a Web API request. This request returns the value 1
, the object type code for the account
table.
GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')/ObjectTypeCode/$value
Create
is the name of the message. Replace these values with the table and message you need.
Use this FetchXml query to return step.sdkmessageprocessingstepid
values you can use with the BypassBusinessLogicExecutionStepIds
optional parameter.
<fetch>
<entity name='sdkmessagefilter'>
<filter>
<condition attribute='primaryobjecttypecode'
operator='eq'
value='1' />
</filter>
<link-entity name='sdkmessage'
from='sdkmessageid'
to='sdkmessageid'
link-type='inner'
alias='message'>
<filter>
<condition attribute='name'
operator='eq'
value='Create' />
</filter>
</link-entity>
<link-entity name='sdkmessageprocessingstep'
from='sdkmessagefilterid'
to='sdkmessagefilterid'
link-type='inner'
alias='step'>
<attribute name='name' />
<filter>
<condition attribute='statecode'
operator='eq'
value='0' />
<condition attribute='customizationlevel'
operator='eq'
value='1' />
<condition attribute='iscustomizable'
operator='eq'
value='1' />
</filter>
</link-entity>
</entity>
</fetch>
Learn more about retrieving data using FetchXml
Limit to the number of steps
To ensure that the parameter size isn't too large, the default limit on the number of steps you can pass is three. The limit is controlled using data in the Organization table OrgDbOrgSettings column. Use the OrgDBOrgSettings tool for Microsoft Dynamics CRM or OrgDbOrgSettings app to change the BypassBusinessLogicExecutionStepIdsLimit
value.
The maximum recommended size for this limit is 10 steps.
Adding the prvBypassCustomBusinessLogic
privilege to another role
The optional parameters described in this article require security roles that are only added to the system administrator security role. This privilege isn't available in the security role designer to add to other security roles. If you need to grant this privilege to another security role, you must use the API. For example, you might want to grant this privilege to a user with the system customizer security role.
To add the privilege to another security role, you need the ID of the privilege. The ID for the prvBypassCustomBusinessLogic
privilege is 0ea552b0-a491-4470-9a1b-82068deccf66
. This ID value is the same for all Dataverse environments.
Associate the prvBypassCustomBusinessLogic
privilege to a security role using AddPrivilegesRoleRequest.
static void AddprvBypassCustomPluginsToRole(IOrganizationService service, Guid roleId)
{
var request = new AddPrivilegesRoleRequest
{
RoleId = roleId,
Privileges = new[]{
new RolePrivilege{
PrivilegeId = new Guid("0ea552b0-a491-4470-9a1b-82068deccf66"),
Depth = PrivilegeDepth.Global
}
}
};
service.Execute(request);
}
Frequently asked questions for bypassing custom business logic (FAQ)
Following are frequently asked questions about using the optional parameters described in this article to bypass custom business logic.
Do these optional parameters work for data operations by Microsoft plug-ins and workflows?
No. If a plug-in or workflow in a Microsoft solution performs operations on other records, the logic for those operations aren't bypassed. Only those plugins or workflows that apply to the specific operation are bypassed.
Can I use these optional parameters 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 necessary privilege. For plug-ins, set the optional parameter on the class derived from OrganizationRequest Class.
See also
Web API: Compose HTTP requests and handle errors
Use optional parameters
Bypass Synchronous Logic
Bypass Power Automate Flows
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for