Custom Business Rules

Extending Aucerna Execute with Custom Business Rules

Overview

Aucerna Execute includes a graphical rule building tool based on Google’s Blockly. This tool configures and extends Aucerna Execute’s behaviour and allows changes that go well beyond what was configurable in earlier versions. The main systems in Aucerna Execute that rely on this tool for configuration are:

  • Email Reminders and Email Notifications
  • Quick Search Cards
  • Custom Document Headers
  • Document Archiving
  • Document Display Identifiers (one-line summary of a document)
  • Custom Document Validation Rules
  • AFE & RTD Approval and System Review Rules (Position Rules)
  • AFE & RTD Number Generation
  • Custom Document Permissions (create, edit, delete, visibility)
Although Aucerna Execute’s graphical rule building tool is based on Google’s Blockly project, it differs in some key ways (specifically the blocks available, and how variables and loops are handled). Because of this, online documentation for Blockly, while a useful resource, isn’t directly applicable to configuring Aucerna Execute.

Rule Building Basics

All rules built in Aucerna Execute share common facets such as how to read information from the document (AFE, RTD), how to read information about the current user, and how to make decisions on that data. This section applies to building any type of rule within Aucerna Execute.

Click image to expand or minimize. 

All of Aucerna Execute’s graphical rules contain similar components.

  • Rules are composed of blocks. Blocks can do things like read a piece of data from an AFE, compare data, convert a number to text and make decisions.
  • Blocks are found in the Block Toolbox on the left side of the editor. Blocks are organized into categories to make them easier to find.
  • At the top of the editor are one or more lists that let you read data from the current document (AFE, RTD, etc.) and also from the user involved in the rule (usually the user performing the action). Some rules have additional lists.

The Begin/End Block

When building rules, it is important to note that the entire rule must be contained within the purple begin/end block.

On save, any blocks not within the begin/end block will be removed.

In the following diagram, block 1 will be used/saved and block 2 will be discarded upon save.

Click image to expand or minimize. 

Data Types

Aucerna Execute’s rule building tools support working with data in several different data types. It’s important to be aware of these because it affects which operations can be performed on the data, and which blocks are compatible.

The data type for a block can typically be inferred from its color. Blocks are typically the same color as their data type. For example: Boolean (yes/no) fields are always purple and blocks that operate on boolean fields are also typically purple.

Type Description Block
Integer Integer fields represent numeric values with no decimal places (1, 100, 202, etc.)
Decimal Decimal fields represent numbers with decimals such as dollar amounts and working interests. (1.23, 1000.1, 0.01, etc.)
Boolean (Yes/No) Boolean fields represent a Yes (True) or No (False) state.
Date A date field represents a date and time. Dates in Aucerna Execute are always stored in UTC but can be converted to the user’s preferred timezone when displayed.
Text Text data consists of an arbitrary number of letters, numbers and other symbols (ex: the AFE’s description)
Null Null is a special kind of value that means there is no value. You’ll encounter it when a field is empty.

Reading Data

At the top of each rule configuration screen are one or more dropdown lists that let you select fields from the documents relevant to the rule, and turn them into blocks you can use in your rules:

The above example is from an AFE Position Rule which is processed when an AFE is released for approval. The “AFE” list lets you select data from the AFE being released, while the “Current User” list lets you read information about the user releasing the AFE.

Simple Fields

From the field selector list you can select from most of the top-level fields on a document (there is some support for information in child tables but we’ll ignore that for now).

When you select a simple field (text field, date, numbers, yes/no), and click “Add Field To Rule”, Aucerna Execute will add a new block to your diagram like this:

You can then use that new block in your rules. Here is an example that grants permission if the AFE description is less than 100 characters long.

Document (Dropdown List) fields

Reading document reference (dropdown list) fields is a bit more complex depending on what you are trying to do.

  • Testing to see if list field is specific value
  • Reading a piece of associated data from the linked document

Document Equality Blocks

Document Equality blocks give a robust way of testing a list field for a specific value.

For example, if we are working with the AFE Type field and want to add a condition to our rule that only applies to Drilling AFEs, we could choose the AFE Type field in the field dropdown, then choose “equals” in the middle dropdown list, and then select “DRILLING” in the final list.

Adding this to the rule creates a block like the following:

The above block behaves as a boolean field, returning “Yes” if the AFE’s AFE Type is equal to “DRILLING”.

Behind the scenes what this actually does is match on the Document ID for the “DRILLING” AFE Type. This means that even if “DRILLING” is later renamed to “Drilling & Completion”, any rules using this block will continue to work.

Building rules using the above document equality blocks can be dangerous, if the rule is intended to be manually copied between environments, because the underlying rule references the DocumentID which is not guaranteed to be consistent between environments (i.e. if you manually add a new AFE Type “Completion” to your PROD and TEST environments they will have different DocumentIDs and any rules using the document equality block for that value will fail if copied to the other environment.).

Document Fields

This is for reading the value of a field on a document list field - for example, retrieving the AFE owner’s email address - where the data belongs only to a document referred to by the AFE.

Select the list field in the first dropdown, then “get value” from the second list, and then select the field you would like to get the value of.

This will insert a new block like the following, that you can then use in your rules.

There is a special “Document Display Identifier” option in the field dropdown that will return, as text, the “display identifier” for the selected document. The display identifier is a configurable single-line summary for a document and usually the best choice when you are including a list field value in an error message or email.

Simplifying Rules

Sometimes rules will apply to a large number of list values. Rules like this can quickly become impossible to maintain.

For example:

Lets say we are building an AFE approval rule and we want our approver to approve all the drilling AFE types.

AFE Type
DRILLING
DRILLING AND COMPLETION
PRE-LIM DRILLING

We could build that rule like this:

Unfortunately, the above rule is already getting unwieldy and there are only three AFE Types in the above list. Imagine if there were twenty!

We could rewrite the rule this way to make it a bit easier to read.

Even the above, however, can get very long, very cumbersome, and very difficult to maintain if the list of drilling types changes, or is repeated in multiple rules.

An alternative is to add information to each AFE Type that we can use to classify the AFE Types.

We could add a new custom field to the AFE Type document called “Is Drilling Type” and then fill that in for our AFE Types (Update Multiple makes this easy, or it could be brought across in a sync process).

Once we have our AFE Types tagged with this additional “Is Drilling Type” value we can then build our rules against the value of “Is Drilling Type” field on the AFE’s AFE Type like this:

The above is not only simpler to write but, in the long term, much more maintainable.

Note that, because the “Is Drilling Type” field can have a null value, it must be converted from an optional boolean to a non-optional boolean by defining what value an empty state should take. To do this we use the “convert null to false” or “convert null to true” blocks.

Making Decisions

On the greatest strengths of the Aucerna Execute graphical rule building system is the ability to build conditional code (if-statements), allowing the behaviour you configure to vary depending on data on the AFE/RTD/etc, or the user performing the action.

The primary decision making block is the “if” block, below:

In its simplest form, the “if” block takes a condition (1) and an expression to run (2) if that condition is true. The condition must be a boolean value.

By clicking the gear in the upper corner of the block you can configure it to support multiple conditions and an else clause.

  1. A basic “if” block. It takes a single condition, and a single expression to evaluate if that condition is met.
  2. An “if-else” block. It take a single condition, and two expressions. The first (then) expression is run if the condition is met, and the second (else) expression is run if the condition is not met.
  3. An “if-elseif-else” block. It’s similar to the “if-else” block but can have any number of additional “if” conditions in the middle. It only evaluates the “else” part if none of the other conditions are met.

The above rule is part of an AFE Approval Position Rule. It is an “if-else” type block. In English, it would read like this:

If the AFE Type is DRILLING then include this position in the list of approvers, otherwise do not include it in the list of approvers.

The condition “AFE : AFE Type = DRILLING” is a boolean value that will be Yes (True) for AFEs with DRILLING for their AFE Type. If the condition is true, the “Include Position” block will be evaluated which adds the position to the list of approval positions. If the condition is not true, the “Do Not Include Position” block will be evaluated.

There are lots of “logic” blocks to allow building more complex rules. The “not” block, for example can be used to invert boolean values (change a Yes to a No, and a No to a Yes).

So the following two rules are equivalent.

The “and” block (which can also be reconfigured as an “or” block”) allows you to combine two boolean values into a single boolean value.

The following rule, for example, will add the approval position if the AFE Type is both DRILLING and COMPLETION.

The above is clearly ridiculous because an AFE Type can not be both DRILLING and COMPLETION. It’s one or the other.

What we want in this case is to reconfigure the “and” block to be an “or” block, so that the rule reads like this:

This rule makes sense. The approval position is included if the AFE Type is DRILLING or if the AFE Type is COMPLETION.

Comparing Text

Often it is useful to build rules that compare text data and return a boolean (yes/no) result. Blocks for this purpose can be found under “Text Compare” in the block toolbox.

The above block returns true (yes) result if the AFE Type’s OtherValue1 field equals “DR”. The “Exact: No” at the end means that the comparison is case insensitive (the default behaviour).

The above block returns a true (yes) result if the AFE’s Description field is empty.

The above block returns a true (yes) result if the AFE Number contains “08DR”.

You can compare two different text fields using comparison blocks such as in the following example. This is an AFE validation rule that checks that the AFE Number contains the numbering prefix for the AFE Type (useful for catching AFEs where their AFE Type was changed after the AFE Number was generated, so the AFE Number no longer matches the AFE Type).

The “Text Create” and “Text Edit” categories contain additional blocks that support further processing on text such as finding text length, getting the first N or last N characters, trimming spaces, joining two text blocks together, etc.

Comparing Numbers

Aucerna Execute includes a number of blocks for working with numbers. Most of these are found in the “Math” category in the block toolbox.

The most basic block is the numeric equality block which looks like:

It can be used to compare some data against a constant value. The following example compares the AFE’s Total Gross Estimate against the constant 0. The expression below will return a boolean yes/true if the Total Gross Estimate is zero.

It’s often more useful to perform range checks on numbers by changing the operator in the dropdown in the center of the numeric equality block. The following block returns a boolean yes/true if the AFE’s Total Gross Estimate is greater than, or equal to, one million.

You can even use the “and” block to combine two equality blocks and verify that a number falls within a certain range. The following example returns a boolean yes/true if the Total Gross Estimate is greater than, or equal to, five hundred thousand and less than, or equal to, one million.

Total Gross Estimate Result
$100,000.00 No/False
$499,999.99 No/False
$500,000.00 Yes/True
$750,000.00 Yes/True
$1,000,000.00 Yes/True
$1,000,000.01 False/No

Because range checks are so common, there is a special “is in range” block for making those types of comparisons easy. The following example is identical to the example above but much easier to create and read.

Of course, comparisons are not limited to constant numeric values. The following example returns a boolean yes/true if the Total Gross Estimate and Approved Gross Estimate are identical.

The above example could be turned into something quite useful with the addition of the “math” block which supports basic operations like addition, subtraction, multiplication and division.

We could decide that supplements can use a reduced approval path unless their estimate is 10% over the previous approved estimate. A rule like the following could be used to do this.

Here is a complete position rule for a user who approves all Drilling AFEs in the area “ADAMS” except for supplements where the supplement’s Total Gross Estimate has not exceeded the previous Approved Gross Estimate by 10% or more.

Click image to expand or minimize. 

Note the use of “Note” blocks in the above example. These are found in the “Diagnostics” category in the block toolbox. They have no effect on the evaluation of the rule but are, instead, a helpful way of embedding comments to yourself or anyone else who will be maintaining that rule in the future.

Comparing Dates

Just like with the numeric blocks, Aucerna Execute has a built-in collection of blocks for working with dates. These can be found in the “Date” folder in the block toolbox.

The most basic block is the date equality block which can compare two dates.

To compare with a constant date you can use the “date” block and provide a date in the format “yyyy-mm-dd”.

This example returns a boolean yes/true if the creation date is on or before January 1, 2015.

Just like with numbers we have range operators for dates. This block returns a boolean yes/true if a date falls within two provided dates.

The following example returns a boolean yes/true if the AFE’s creation date is within 2014.

There is also a “current date” block that will always be today’s date allowing you to build more dynamic rules.

Often it’s useful to be able to build rules based on the number of dates between two dates. For this we have the “days between” block.

Using the “days between” block we can find the number of days between two dates and use those in our comparisons. For example, below we find the days between the AFE’s creation date and today.

We can then use this in a more complete rule where we look for AFEs created at at least 60 days ago.

The “days between” block always returns a positive number of fractional days between two dates. If you need to determine if one date is before another you must use the equality block.

Common Types of Rules

There are currently two main types of rules in Aucerna Execute.

  1. Rules that make a decision:
    • is this AFE valid?
    • does the user have permission?
    • should the user approve this AFE?
  2. Rules that generate output
    • what should this email subject look like?
    • what should the RTD header look like?

Although all rules configured using Aucerna Execute’s graphical rule building tool have a lot in common (see above), there are a few differences. Those are outlined in the section below.

Decision Making Rules

Most rules in Aucerna Execute are decision making rules.

  • AFE / RTD Approval Rules
  • AFE System Review Rules
  • RTD Discipline Completion Rules (Validation)
  • AFE Route/Release Validation Rules
  • Custom Document Permission Rules
  • Document Archive Rule

While the individual blocks vary with the type of rules, the basic concept is the same. These types of rules are making a yes/no decision. Should the user approve this AFE? Should they be allowed to edit this RTD?

For example,

the following block is used in permission type rules to grant access to perform an operation:

while the following block is used in approval type rules to include the position in the approval path:

Approval and System Review Rules

Approval and System Review rules are attached to a Position and decide whether that position is required in the approval or review path.

These types of rules use “Include Position” and “Do Not Include Position” blocks (in the “Result” folder in the block toolbox) to decide whether a position should be included or not.

A position is included in the approval / review path if its evaluation invokes the “Include Position” block.

A position is excluded from the approval / review path if its evaluation invokes the “Do Not Include Position” block.

If neither of the above blocks are invoked, the position is not included in the approval / review path.

The following is a very basic position rule that would include the position on every Drilling AFE.

Validation Rules

With Validation Rules, the document is considered valid if the rule runs and does not yield any errors. Validation rules are able to inspect the document and raise one more more errors or warnings using the “error” and “warning” blocks in the “Messages” category of the block toolbox. Both the “warning” and “error” blocks take a message as a parameter allowing you to give the reason for the validation failure to the user.

Warnings are potential problems that are shown to the user. However, the user is allowed to ignore them and continue with the original operation.

Errors are problems that must be resolved before the original operation can continue.

The following is a basic validation rule that could be used on AFE Route or Release to require the Budget Manager field be filled in. The user (or an admin) will be unable to proceed until this error is resolved (by selecting a budget manager).

You can also generate messages using information on the document being validated. The following example will raise a warning if the external justification is less than 50 characters (we should really have a decent justification right?) and the message will include the justification they provided as part of the warning.

Validation rules can also retrieve information about the user performing the action that is being validated. This is useful for allowing administrative exemptions. The following example includes the user’s first name to make them feel extra guilty about their terse external justification (please don’t actually do this).

Click image to expand or minimize. 

The above expression uses the “concatenate text” block to join text and produce the following warning:

Permission Rules

Permission type rules simply need to decide whether a user can take an action or not. They are used to fine-tune permissions for who can see or edit documents. They use the “Grant Permission” and “Deny Permission” blocks found in the “Output” folder of the block toolbox.

The “Grant Permission” block will grant the user permission to perform the action.

While the “Deny Permissions” block will prevent the user from performing the action. Note that permissions “fail safe” and, unless explicitly granted using the “Grant Permission” block, will deny the action.

Permission type rules usually also depend on the action’s user. This example denies access to view preliminary drilling AFEs to anyone except an admin with “Edit AFE” (users directly involved in the workflow such as the owner, reviewers, and approvers are always implicitly permitted to view/edit AFEs they are involved in!).

Document Archive Rules

Aucerna Execute uses the custom rule builder to decide which documents should be archived and excluded from default searches (see Archiving Documents).

The endpoints of these rules are always one of 2 blocks:

  • The “Archive Document” block
  • The “Do Not Archive Document” block

Aucerna Execute runs the archive rule against each document of that type in the system to determine if it’s archived.

The following example will treat Closed AFEs, and those created more than a year ago as archived.

Text Building Rules

Some rules in Aucerna Execute generate text. Common examples include:

  • Document Display Identifier Rule — builds a single-line description for a document by formatting relevant data.
  • Email Notification Subject & Body
  • AFE and RTD Number Generation

The basic block for building text is, unsurprisingly, the “add text” block (found in the toolbox’s “Result” category).

The following very basic rule returns just the AFE Number. This isn’t very interesting.

Other blocks can be brought in for more complex rules:

The above example shows:

  • For Drilling AFEs: Primary UWI and Well Name
  • For all other types: AFE Description

If you have multiple “add text” blocks the results will get merged together. The following two blocks behave the same and both produce “Hello, World!”.

Table Building Rules

In some cases, Aucerna Execute uses the graphical rule builder to generate tabular output such as:

  • Custom document header
  • Quick Search Cards
  • Common Email Footer

While the formatting is slightly different, the behaviour is the same in each of these cases.

  • A rule contains one or more rows
  • A row contains one or more cells
    • cells can be “label” cells or “content” cells
    • cell text can be aligned left, right or centred
    • cells can span multiple columns
  • Cells contain text, links and badges

The following example is a very basic table that demonstrates basic usage of a table.

  • This table has a single row
  • The first cell (column) is a “label” (1) cell that contains the field name of the “AFE Type” field (3)
  • The second cell (column) is a “content” (2) cell that contains the display identifier for the selected AFE Type (4).

The above rule yields a very basic table:

The “Field Name of” block is a special block you can create in the field dropdown at the top of the rule editor. Click the dropdown arrow on the “Add Field to Rule” button. The “Field Name of” block will return the current field name of the associated field which can be useful when building rules so that if a field name is updated in the future, the rules depending on them don’t also need to change.

The following is a more complex multi-line table with four columns.

Click image to expand or minimize.

  • This table has two rows
  • The first row (1) has four cells (two labels and two content cells)
  • When including numbers or dates in tables it’s important to convert them to text using a “convert” block (2)
  • The second row only has two columns. This is because the description is often very wide so we’ve made it span three columns (3). This makes four total cells / column in that row.
  • The number of columns/cells in each row in a single table should always be the same

Other block types can be included for more interesting outputs. The following example makes a conditional table row using an “if” block:

  • The first row in this table has two cells:
    • Label “AFE #” (2) - here we’ve used a constant value instead of reading the field label so we can abbreviate it
    • The AFE Number
  • The second row is wrapped in an “if” block (1) and is only included on Drilling AFEs
    • Drilling AFEs have a two row table, showing the Primary UWI as the second row
    • Non-Drilling AFEs only have the single row with the AFE Number