AFE Approval/Review Paths

This release introduces a new out-of-the-box way to define approval rules in Execute called AFE Approval Paths, and the same for system review called AFE Review Paths.

What are they?

Paths are a new option for modeling approval/review rules in Execute.

This feature introduces two new document types (“AFE Approval Path” and “AFE Review Path”) that can be used to define different paths of individuals an AFE can flow through for approval and review.

For the remainder of this document, we’ll talk about Approval Paths but, for the most part, Review Paths are the same (except they don’t have $ limits).

Here is a sample Approval Path that defines a three-approver approval path for completion AFEs.

Next, an Approval Path is selected for an AFE (using the AFE’s new APPROVAL_PATH field). This selection can be entirely manual (which may be a great low-setup-effort option), “smart-manual” (using list filters to limit selection to valid approval paths that the user can then choose from - i.e. here are the three options for drilling AFEs), or “full-auto” (using a list filter setup to always identify a single Approval Path for each AFE with no user interaction needed).

When releasing the AFE for approval, Execute will look at the Approval Path linked to the AFE and add those approvers to the AFE.

A couple of key notes, however…

• Approval Paths specify individuals and not positions. This makes building the rules far easier for those of you who think in these terms. Execute does require positions, however, so we automagically create them as required.
• These are meant to be a simpler option, not a replacement for Blockly. While they have a bunch of great functionality (maximum approval authority, tiers, and exclude-if-over-max), they can’t do everything that the more powerful Blockly rules can.

Why are they?

Our current approval rules are great, but there are a few aspects of them that are problematic for some customers.

1. They are complex. Some companies struggle with describing their approval rules as “individual positions with a blockly-based should-I-approve-this-AFE rule”.
2. Many companies think of approvals as “Bob is authorized to approve up to $2M”, which is difficult to model in Execute’s Blockly-based rules where, instead, you need to add a rule to the person after Bob that says “Bob’s boss sees everything above $2M”.
3. Some companies really struggle to think in terms of approving positions. They think in terms of individual people.
4. Some companies have their approval rules defined in another system and want to leverage that. It is very difficult to automate the creation / management of the current Execute approval rules.

So…

Approval Paths give another option which will be easier to work with and maintain for some companies.

As a bonus. Because Approval Paths are simple “Documents” in Execute…

• You can report on them
• You can update them with Browse Edit mode
• You can import them / update them from Excel
• You can load them with Data Loaders
• You can load/update them automatically with Document Sync
• You can easily create/manage them with our APIs

How do I turn them on?

1. You should enable the APPROVAL_PATH field on the AFE and, somehow, provide a mechanism for it to be set.
   • (Easiest) Add the field to an AFE custom tab and have someone fill it in. If that’s too open, you can always use list filters to limit which Approval Paths can be picked based on attributes of the AFE (the default is filtering by AFE Type).
   • (Harder) Automate the selection. Make the APPROVAL_PATH editability Never Except Batch and ensure the Blockly List Filters are set up to always identify a single Approval Path for each AFE (Execute will then automagically attach it).
2. You need to give your admin user the “Manage AFE Approval Paths” privilege.
3. You need to add some Approval Path documents. (NOTE: the default setup filters approval paths by AFE Type, so make sure to create Approval Paths for each AFE Type)

FAQ

What AFE amount does this approve on? Gross? Net?

This feature honors our standard setting “Approval Amount Type” which allows you to select between approving on Gross, Net, or Net on Non-op.

Can I ensure that AFEs have at least one approver with sufficient authority?

You sure can using the new “Require Sufficient Approval Path” setting.

When set, the system will prevent the release of the AFE for approval if the Approval Path doesn’t have an approver with sufficient approval authority.

How can I limit which Approval Paths are selected?

The easy answer here is List Filters. By default we ship with a basic list filter that only shows Approval Paths where the Approval Path’s AFE Type matches that of the AFE (actually, we’re a bit fancier and allow for “wildcard” approval paths which show up for every AFE Type!).

Here is the default list filter rule on the AFE’s Approval Path field.

If you wanted to further segment your rules, perhaps based on AFE Area, you can add an Area list field to the Approval Path document (don’t forget to add an Area dropdown field to the Approval Path General custom tab), and then update your list filter like so:

How many approvers can I have in a path?

We’ve created 15 approver fields (meaning the max is 15), but we’ve only made the first seven fields active initially. If you need more than 7, you can just enable additional fields on the Approval Path document.

Does this support approving tiers? (Parallel Approvals)?

It sure does! The “Share Tier” fields mean that the approver shares the same approving tier as the user above. So this example here:

Would yield these approvers on an $1,500 AFE.

Does this mean that Blockly Approval Rules are going away?

Absolutely not. Blockly rules were created for a reason and are better at modeling certain types of approval rules. This new option is better for other types.

If there are no positions… how does out of office work?

There are positions, actually.

While approving positions are not part of the Approval Path rules we build, they are a requirement of Execute’s approval engine. To make this work, we automatically create positions for each approver. By default, these positions are named after the approver (i.e. user “Jimbo Jones” will automatically get a position created called “Jimbo Jones”).

If you’d like to see a more traditional position name on the AFE’s approval tab, you can add a new custom field CUSTOM/APPROVING_TITLE to the user and fill that in. From that point onward, the newly created position rules will be named like “{Approving Title} - Jimbo Jones”.

So, for out of office, our normal functionality applies. If “Blair Contracts” is out on vacation and delegates to “System Admin”, you’d see a record like this. You can clearly see who was supposed to approve it, and who actually did approve it.

How do I handle wildcard rules (“any area”)?

It depends, but if you are using list filters and/or release validation rules to restrict which Approval Paths are selected for an AFE, you can build that logic into the rule.

For example, a simple list filter like this would require that the AFE’s AFE Type match the Approval Path’s AFE Type (no wild cards).

But by adjusting it slightly, we can allow for an empty AFE Type on the Approval Path document to apply to AFEs of every type.

Can I use this and Blockly Position Rules?

You sure can! When releasing an AFE for approval, any approvers from the new-style Approval Paths are added first, followed by any approvers added by Blockly.

This allows you to add high-level approval rules (“President sees everything over $5M”) in Blockly and avoid adding them to every Approval Path… if you want… (of course, doing so makes reviewing the rules more difficult).

You may also choose to use Approval Paths in general, but use Blockly Position Rules for specific AFE Types that are too complex for Approval Paths.

Out of Office Delegation

A frequently requested feature is now available: users can delegate their own review or approval when they’re away—without needing to go through a system administrator.

To enable this functionality, simply toggle the new setting:

Once enabled, users will see a new “Out of Office” option under their user menu (top right):

From there, users will be guided through a simple delegation wizard, similar to the one currently used by administrators.

Note: This feature is best suited for environments where users are trusted to choose appropriate delegates. At this time, there is no rule system in place to validate that the selected delegate has the necessary approval or review authority.

Improved Quick Add Experience

In Execute, list fields typically include a + icon that lets users quickly create and select a new record of that type.

Historically, the Quick Add pop-up form wasn’t exactly elegant—it displayed all fields on the new record in alphabetical order, which wasn’t always helpful.

In this release, Quick Add now defaults to using the first (default) tab defined for that document type. It will only fall back to the alphabetical view if no custom tabs are available.

So now, adding a Pad from your Well looks a whole lot cleaner:

And if I’d like further control, you can create a special “Quick Add” custom tab and really dial it in!

In many places throughout Execute, information from linked documents can now be included without requiring you to build calculated fields, etc. The examples below are primarily around Wells, Jobs and Pads but the functionality is available across any for any record type in Execute.

Browse Reports (User Facing)

Using our new column picker, everyone can now build reports that include/reference data from related documents.

Here is a quick example showing how to include Well and Pad-level fields on a Job report.

We always strive to minimize non-admin/end-user-facing changes to avoid the need to retrain users. In this case, while there is a visible change for the end-user, we hope the change is small and obvious enough that it won’t cause any confusion.

Custom Tabs

Administrators can also include fields from related documents when building custom tabs. For example, a Job custom tab can include fields from the linked Well or Pad for reference.

Note that currently, these referenced fields are NOT editable (i.e. you can’t edit a Well field from the Job), but we’re working on that!

Workflow Tasks

Administrators can include fields from related documents on workflow tasks. For example, a Job-level workflow task can include fields from the Job, the Job’s Well, and the Job’s Well’s Pad! Unlikely Custom Tabs, these fields are all editable (assuming the user has the appropriate permissions).

Custom Business Rules (Blockly)

And, finally, you can do this when building custom business rules using Blockly too!

Execute used to offer similar functionality for specific references using our “Reference Fields” dropdowns. These fields have been replaced by the new (more capable) functionality, and any existing rules using the old Reference Fields should have been automatically updated to the new structure*.

Note: The old Reference Fields did allow building some references which we consider problematic because their behaviour was unpredictable. We have removed support for these problematic relationship types. Existing rules will continue to work as they did before, but it will no longer be possible to create new rules of these types.

The following relationships are no longer supported.

1. Project > Well
2. Project > Site
3. Site > Well
4. Well > Job
5. Site > Job

For clarity, the way to read an entry like “Well > Job” in the above list is that it is not valid for a Well-level report, workflow task, report, etc., to refer to a Job-level field. The reason is that a Well often contains more than one Job, and as soon as more than one Job is referenced, it is impossible to show a single value for a linked Job-level field. Previously, we allowed rules to be built like this, but they would silently stop working as soon as more than one Job was linked.

Execute’s new Document Fetch APIs provide a streamlined way to bulk extract documents from Execute.

• A single streamlined API call vs. the Login > Run Report > Logout call for the current APIs.
• Returns ALL data for request documents in a nice friendly machine readable JSON form.
• Supports including calculated field values in the returned data (popular request from User Voice).
• Easily filtering to return only documents modified since a provided date (makes it much easier to keep a remove warehouse up-to-date).

Note: These APIs require the Execute Advanced Data Export (OData) module license.

More information can be found in our New Postman-based API documentation.

When configuring email reminders and notifications, administrators can now…

• Allow users to opt-out of receiving the notification/reminder by setting the Allow Opt-Out field on the notification/reminder to “Yes” (by default, users are not able to opt-out of reminders/notifications that they are included in)
• Allow users to opt-in to receiving the notification/reminder by adding the new notify subscribers block to the reminder’s Recipients rule. i.e.

Users are then able to adjust their email preferences from the new “Email Preferences” menu item under their name in the top-right of the Execute screen.

If you’ve ever found yourself looking at a report in Execute’s browse screen and thought to yourself, ‘Gosh, that ain’t right. I need to update that!’, only to be slightly deterred by the prospect of actually opening the Well, AFE, Job, etc. to make the change… Have we got a thing for you!

Users can now update individual values or entire columns right from the browse screens throughout Execute!

From the browse screen, users can now click the toolbar’s pencil icon to enable bulk edit mode. This puts a pencil in each editable cell in your browse report which will allow updating the cell without leaving the report. In addition, the new “Bulk Update” option under the column dropdown allows a user to update the entire column (respecting any filters you have, of course).

This new functionality respects the user’s edit permissions and will only allow updates to data they could have changed normally.

Here is a quick demo:

This release includes support for Peloton’s new 2.0 APIs (affecting Peloton SaaS customers).

Peloton has announced their plans to deprecate their existing APIs (used by previous versions of Execute’s integration with Peloton SaaS) by the end of February.

Customers who wish to use/continue to use this integration must:

1. Contact Peloton support and request written permission to enable this integration (cc’ing Execute Support). Peloton requires customers obtain written permission prior to integrating with third parties.
2. Upgrade Execute to this version or later.
3. Work with Execute Support to update their configuration to use the new integration.

With this update, Execute now includes support for integrating with the following document management systems:

• Quorum’s DynamicDocs
• Microsoft’s SharePoint

Execute now supports multiple pluggable “AttachmentStores” which can selectively take over the storage of attachments.

• Each attachment store can decide which document(s) (AFE, Well, …) it should store attachments for.
• Execute supports pushing and maintaining additional meta-data for each attachment to help searching/sorting/categorization/etc. in the document management system.

This gives a great deal of flexibility. For example, you can use SharePoint for “approved” AFE attachments, DynamicDocs for Well-level attachments, and the built-in storage for everything else.

Plugins for these integrations are found under plugins_available\integration\product_integrations\document_management.

Execute’s Data Warehousing feature has received many updates:

SQL Warehouse

1. We have removed the NORMAL and MATERIALIZED options for the creation of helper views since they were not-performant with larger datasets. We added a new option TABLES_AUTO (the new default, and our recommendation for most cases) which will similarly ensure that the helper tables are kept current automatically.
2. We have added support for breaking very large documents (typically only seen with Schedules) into smaller chunks. To enable this, the EXECUTE_DOCUMENTS table has a new chunk column. If you are querying EXECUTE_DOCUMENTS directly, you may need to adjust your queries to handle this correctly (When querying normal fields, filter to chunk=0. When querying child tables, include data from all chunks). If you are querying our automatically created helper tables, this work has been done for you.
3. To avoid issues where restarting Execute could take a very long time, Execute will no longer wait for a sync to finish on shutdown but, instead, keep a highwater mark of successfully sync’d records. After restart, and on the next automated sync, Execute will publish any records modified since that stored highwater mark.
4. Fixed behavior when Deleting and Undeleting records.
5. To avoid excessive replication of data, the EXECUTE_DOCUMENTS_LATEST table no longer includes the data from the latest records. Queries relying on this table will need to join on EXECUTE_DOCUMENTS.

Snowflake

1. We have added support for breaking very large documents (typically only seen with Schedules) into smaller chunks. To enable this, the EXECUTE_DOCUMENTS table has a new chunk column. If you are querying EXECUTE_DOCUMENTS directly, you may need to adjust your queries to handle this correctly. If you are querying our automatically created helper tables, this work has been done for you.
2. To avoid issues where restarting Execute could take a very long time, Execute will no longer wait for a sync to finish on shutdown but, instead, keep a highwater mark of successfully sync’d records. After restart, and on the next automated sync, Execute will publish any records modified since that stored highwater mark.
3. Fixed behavior when Deleting and Undeleting records.

Mandatory Manual Upgrade Step

Because of the changes made in this update, administrators must manually perform the following steps after upgrading Execute.

1. Replace your SQL Warehouse or Snowflake plugin with the latest version from plugins_available
2. Verify that the Create Views setting is set appropriately (for SQL Server, we strongly recommend TABLES_AUTO)
3. Remove all Execute created objects in Execute’s Data Warehouse schema (EXECUTE_DOCUMENTS, AFE, PROCESS_EXECUTE_DOCUMENTS, ...).
4. Run the Schema Publisher synchronization task.
5. Run the Document Publisher synchronization task.

Execute will now correctly prevent passwords from being used in environments configured to use Single Sign-on. This change has the potential to prevent users from accessing these SSO environments if they were relying on a username and password instead of the SSO mechanism.

This affects environments…

1. using OKTA or OIDC for SSO
2. using our legacy Windows login mechanism where the Authentication Type setting is set to WINDOWS

This means that:

1. Users will not be able to login with a user-specified password in these environments.

• Login screen
• APIs
• OData

2. Users will not be able to set a password. The password changing feature will be hidden from the user’s profile.
3. Administrators will not be able to set a user’s password from the user management screen.

Any integrations using Execute’s API or OData should transition to using Execute’s safer API Key mechanism.

If you require the use of user-specified passwords in your SSO environment (NOT RECOMMENDED), you can override this new behavior by setting the new Allow User Passwords When Federated setting.

When creating a new Notification or Reminder, administrators can now use the new “Workflow Task” document type to build custom notifications for workflow tasks which much greater control than was previously available.

These new notification types allow building more complex rules like:

To help get you started, we’ve created a new sample notifications for the Job (RTx) module:

Note: There is currently a known issue that makes it impossible to build notifications when a task activated/reactivated and assigned to a user. We are aware of this and working on a fix in a coming release.

Previously, Execute’s Advanced Workflows allowed administrators to reference fields (either as task-fields or in Blockly rules) from child documents. In practice, these references would rarely work (since the behaviour becomes ambiguous as soon as a parent record has multiple children of the same type) and this functionality has been removed.

Specifically, we have removed:

1. The ability for a Project-level workflow to reference fields on linked Wells or Sites
2. The ability for a Site-level workflow to reference fields on linked Wells or Jobs
3. The ability for a Well-level workflow to reference fields on linked Jobs

As a safety check, Execute 265 and higher will check for these invalid references and, if encountered, will fail to start and the server log will contain a message like this:

2024-05-06 11:17:01.613 [ERR] Exception: System.ApplicationException: Upgrade incomplete. Precondition failed for upgrade of database to version 30: There are 2 task paths that must be addressed. Please contact Execute Support.

If this happens, revert to Execute 21.1.264 and contact Execute Support.