Execute form rule with parameters from JavaScript

Overview

A question was raised in the community, whether it would be possible to pass parameters to form rules from JavaScript. While it’s true that the Designer Studio doesn’t offer a UI for this, it’s not impossible, we just need a workaround. :)

This form rule has parameters, and the values are passed via JavaScript

Implementation

Overview

It’s the same as always, we need:

• One global form rule
• Two global business rules
• An HTML field

Ok, these rules don’t need to be global, but these are reusable across processes. If you want, you can create these as process rules.

Global form rule

You can download the JS for this form rule from the repository and paste it to the new form rule. Don’t forget to switch the type to JavaScript mode.

Rule name: ExecuteFormRuleWithParameters
Edit mode: JavaScript mode
Description: 
This allows the execution of a form rule with parameters. You need to pass the integer ids to this function.

// parameterValues is an array of objects with the following structure:
//[
// { id: 109, value: 'test' },
// { id: 109, value: 'test' }
//]

The global form rule.

Global business rules

You will have noticed that the function in the form rule expects ids for the form rule and the parameters. We have three different options on how to pass these:

1. Hard code these
2. Create constants and update the dev/test/prod values after transporting the process
3. Get the integer id from the database using its GUID

If you have access to the SQL server I would always go for option 3. In case of a multi-tenant WEBCONAPPS environment we would have to fall back to option 2 and you won’t need the global business rules. The reason for this is that we need to get the data from tables which can’t be accessed with the <Current BPS database> connection.

If you haven’t run into this issue, you may need to create a new MSSQL connection so that you can access the required tables with a different user.

MSSQL connection for elevated database access.

What’s left is to create two simple business rules to which the GUID will be passed

Rule name: GetBusinessRuleIdFromGuid
Parameter: BusinessRuleGUID

SELECT [BRD_ID] ,[BRD_Name]
FROM [dbo].[WFBusinessRuleDefinitions]
where BRD_GUID = '{BRP:55}'

GetBusinessRuleIdFromGuid definition

Rule name: GetBusinessRuleParameterIdFromGuid
Parameter: ParameterGUID

select BRP_ID, BRP_Name
FROM  WFBusinessRuleParameters 
where BRP_GUID = '{BRP:111}'

GetBusinessRuleParameterIdFromGuid definition

Usage

Get the GUIDs

While we can get the GUID for the form rule, there’s no such option for the parameter.

The GUID of the form rule.

But that’s not a problem, here’s a little SQL query to get these:

select BRD_Name, BRD_ID, BRD_GUID,  BRP_Name,BRP_ID, BRP_Guid 
FROM [dbo].[WFBusinessRuleDefinitions] left join WFBusinessRuleParameters on BRD_ID = BRP_RuleID
where BRD_ID = 1453

The result of the SQL query

HTML field

In this example a text with the passed parameter values will be displayed, when the user clicks a button and you will need to amend this for your case. You will always need to:

1. Execute global form rule
   The InvokeRule will load the global form rule, so that the function dkr.executeFormRuleWithParameterValues will be available
2. For each parameter you need to pass a new object { id: xyz, value: GetPairName(G_CURUSER)},
3. Get the ids for the business rule and parameters The business rules will be used to get the integer ids of the GUIDs, these can be assigned using a right click.

HTML field definition.

Result of the HTML field.

Here’s the example I used.

<script>
InvokeRule(#{BRUX:1454:ID}#);
buttonClick = function (){
    let formRuleId = #{BRD:743:<xps><ps><p id="#BRP:55#" v="9b44254e-9c80-49ff-8017-d3684727c5a8" /></ps></xps>}#;
    let parameters = [
        { id: #{BRD:1455:<xps><ps><p id="#BRP:111#" v="06c94f52-ed86-46e5-b8c6-a65430c61133" /></ps></xps>}#, value:  GetPairName(G_CURUSER)},
        { id: #{BRD:1455:<xps><ps><p id="#BRP:111#" v="5472afba-1ccf-455a-97cb-877b1b814990" /></ps></xps>}#, value: G_BROWSER_LANGUAGE }
    ];
    result = dkr.executeFormRuleWithParameterValues(formRuleId,parameters);
    alert(result);
}
</script>
<button onclick="buttonClick()">Execute form rule</button>

Hints

Broken integrity check / usages tab

Since we need to get the integer ids of the form rule and parameter ourselves, the basic integrity checks are no longer working. If you remove a parameter from the form rule, you will not be warned. The same is true for the usages tab.

Therefore, document where these parameters are used and create constants instead of passing the GUID as a string as in this simplified example.

Elevated database access connection

Make sure that you configure the values for dev/test/production environments. If the business rule cannot be executed in an HTML field, the form cannot be rendered and will throw an error.

This error occurs, if the business rule execution fails in an HTML field.

From form rule mode to JavaScript

A form rule with edit mode Form rule is just a graphical representation which generates JavaScript in the background. You can view this with the Show button.

The generated JavaScript of the form rule.

This is always my starting point to use some form rule function for which I don’t know the JavaScript equivalent.

In this case the most important lines are:

...
UxRule_FormRuleWithParameter_1453(
  ...
   { 'param_109' : 'test', 'param_110' : 'test', });

From here it was just a small step, to create the functions.

Download

You can download the sources here.