Runbook: Testing Automations Safely

Last updated: March 9, 2026

Purpose

This runbook describes how to test new or modified automations in Howard County's permitting system without impacting live applications. It covers creating test records, verifying automation execution, handling known platform issues, and cleaning up after testing.

Never test automations directly against production permit records. Always use dedicated test records with clearly identifiable names and addresses.

Prerequisites

Before testing an automation:

You have access to Automation Builder (Admin role or Automation Manager permission)
A test permit record exists (or you can create one) for your target permit type
You understand the trigger conditions you intend to test
The automation is saved and published (toggle ON to activate)
You have access to the Run History panel in Automation Builder

Understanding Trigger Types

GovAssist automations use different triggers that fire under different conditions:

Trigger Type	When It Fires	Use Case
`on_record_creation`	When a new record is created via UI form	Simple "on create" workflows
`when_record_matches_condition`	When record is created OR updated AND matches conditions	Most routing automations (recommended)
`on_record_updation`	When any field on the record changes	Status-change reactions
`when_form_is_submitted`	When a specific form is submitted	Form-specific workflows

API vs UI: Records created or updated via the Entity Manager REST API do not fire automation triggers. Only UI form submissions trigger automations. Always test by submitting forms in the GovAssist UI.

Testing Workflow

Step 1: Create a Test Record

Choose a test naming convention

Use a consistent prefix so test records are easily identifiable:

Address: 999 TEST ST or 123 AUTOMATION TEST DR
Applicant name: Test Applicant - [Your Name]
Notes: Add [TEST] or [QA] prefix to any notes

Submit via UI form

Navigate to the appropriate form (e.g., Building Permit application) and submit with test data. The submission must go through the UI form. Direct API calls will not trigger automations.

Note the Record ID

After submission, copy the Record ID from the URL or record detail page. You'll need this to verify automation execution.

Step 2: Verify Automation Executed

Open Automation Builder

Navigate to Automation Builder from the main navigation.

Select your automation

Find and click on the automation you're testing.

Open Run History

Click the History icon (clock) in the top-right to open the sidebar. Select the Run history tab.

Find your test execution

Look for a run matching your test record's timestamp. Run History shows:

Status: COMPLETED, RUNNING, or FAILED
Record ID: The record that triggered the automation
Timestamp: When the execution started
Node details: Expand to see each action's result

Verify expected results

Check that:

✅ Trigger conditions evaluated correctly
✅ Expected actions completed (e.g., child records created, fields updated)
✅ No unexpected errors in node execution

Step 3: Verify Dedup Guard (Self-Deactivating Pattern)

Most HoCo automations use a dedup guard pattern to prevent duplicate actions. After testing:

Edit the test record

Make a minor change to the test permit record (e.g., update a comment field) and save.

Check Run History again

The automation should NOT fire a second time. If when_record_matches_condition trigger was used with a dedup guard condition, subsequent edits should not create duplicate child records.

If testing re-triggering

To test the automation firing again, you must reset the dedup guard field:

Open the test permit record
Find the status field used as the dedup guard (e.g., Acceptance Status)
Clear it (set to empty/none)
Save the record
The next matching update should re-trigger the automation

Resetting dedup guards on production records can cause duplicate workflows. Only do this on test records.

Testing FORK/JOIN Automations

FORK automations create multiple child records simultaneously (e.g., 6 Review Tasks from one Building Permit). Special considerations apply:

Verify All Child Records Created

After triggering a FORK automation:

Check that all expected child records exist (e.g., 6 Review Tasks for "New SFD")
Verify each child record has the correct parent association
Verify each child has the appropriate status/review type set

Allow Time for Completion

FORK automations may take 5-30 seconds to complete all branches. If you check immediately after triggering, some branches may still be running.

Check Association Integrity

Verify parent associations are intact on all child records. If associations are missing, this indicates a platform issue. Report to the development team.

Testing Email Actions

Automations with send_email actions require extra caution:

There is no "Test Mode" for email actions. When an automation fires, emails are sent to real recipients. Always verify email addresses before activating automations with email actions.

Safe Email Testing Approaches

Approach	How	Risk Level
Internal recipients only	Use test records with internal email addresses only	Low
Deactivate email step	Temporarily remove or disable the Send Email node	Low
QA inbox	Create records with `qa-automations@howardcountymd.gov` as the applicant email	Low
Live test	Test with a real permit involving a real applicant	High: only after all other testing passes

Verify Email Content

After an automation sends an email:

Check the QA inbox (if using QA addresses)
Verify subject line renders correctly (no raw merge fields like {{permit_number}})
Verify body content and links are correct
Verify attachments (if any) are included

Known Issues & Workarounds

⚠️ Issue: UI Save May Break API-Created Automations

Symptom: An automation created via API stops triggering after being opened and saved in the GovAssist UI.

Workaround:

Avoid editing API-created automations in the UI
If you must edit, verify the automation still triggers after saving
If broken, the automation may need to be recreated via API

Status: Under investigation by development team.

⚠️ Issue: Dedup Guard Field Must Be Non-Null

Symptom: Automation's update_record action crashes with error: 'NoneType' object has no attribute 'get'

Cause: The status field being updated has validations: null in its entity configuration.

Workaround: Ensure all status dropdown fields used in update_record actions have proper validations set at the entity level. Report to development team if you encounter this.

⚠️ Issue: `watching_fields` Not Enforced

Symptom: on_record_updation trigger fires on every update, not just when the watched field changes.

Cause: Platform does not currently enforce the watching_fields configuration.

Workaround: Use when_record_matches_condition triggers with explicit conditions instead of on_record_updation with watching_fields.

Cleanup After Testing

After successful testing:

Document results

Record what was tested, results observed, and any issues found. Add a comment to the ClickUp task or relevant documentation.

Clean up test records

Either:

Delete test permit records and their child records (Review Tasks, etc.)
Or mark them clearly as [TEST - DO NOT USE] in a notes field

Reset for future tests

If keeping test records for future testing, reset their status fields to the baseline state so they can be reused.

Rollback Procedure

If an automation causes unexpected results after activation:

Deactivate immediately

In Automation Builder, toggle the automation OFF. This stops any new executions but does not undo completed actions.

Identify affected records

Check Run History, filter by the automation and the date of activation. Note all records that were processed.

Manually correct

For each affected record:

Revert incorrect status changes
Delete incorrectly created child records
Send correction notifications if needed
Document each correction in the permit's internal notes

Fix and retest

Edit the automation to correct the issue. Follow the testing workflow above before reactivating.

Checklist: Before Going Live

Test record created with clear naming convention
Automation triggered successfully (Run History shows COMPLETED)
Expected actions verified (child records, status updates)
Dedup guard verified (no duplicates on re-edit)
Email recipients verified (internal/QA addresses only in test)
Automation named descriptively (e.g., 1 Res Bldg - Create Acceptance)
Automation description filled in
Run History reviewed for any warnings
Another admin has reviewed the automation logic
Test records cleaned up or clearly marked