Runbook: Troubleshooting Automation Failures

Last updated: March 3, 2026 · Applies to: Howard County Permitting

---

How to Use This Runbook

Find the symptom that matches your situation in the Quick Diagnostic Table, then jump to that section for step-by-step diagnosis and resolution.

---

Quick Diagnostic Table

---

Section 1: Automation Not Firing

Symptom: A permit or license record was created (or a status field was updated), but no Review Task was automatically created.

Step 1: Confirm the automation is published and active

1. Open Automation Builder
2. Navigate to the folder for the permit type (e.g., Res Bldg - Sequential or Animal License)
3. Find the automation that should have fired
4. Check its status:
   • Active (green): Published and listening for triggers
   • Inactive (gray): Turned off — toggle it on, then re-test
   • Draft (yellow): Has unpublished changes — click Publish

Step 2: Check trigger conditions against your test record

Open the automation and compare each trigger condition to the actual record field values:

What the "is empty" guard means: The dedup guard checks that a status field has never been set. If the field already contains any value (even "Pending"), the automation considers the step already started and will not fire. This is by design — it prevents duplicate task creation.

Step 3: Verify the record was created through the UI form

Automations only fire when records are created or updated through the GovAssist UI form. They do not fire when records are created via:

• The Entity Manager REST API
• Direct database operations
• Data imports or bulk migrations

If you created the test record through the API, re-create it through the UI form and test again.

Step 4: Check for conflicting automations

If another automation updated the guard field before your automation could fire, the guard check will fail.

1. Search for other automations that reference the same entity and guard field
2. Check whether any of them set the guard field to a non-empty value before the target automation fires
3. If found, review trigger ordering and timing

Still Not Working?

If the automation is published, active, the trigger conditions match, the record was created via the UI, and the guard field is empty — escalate to the dev team with:

• Automation name and ID (from the Automation Builder URL)
• Test record ID
• Exact time the record was created or updated
• Screenshots of the trigger conditions and the record's field values

---

Section 2: Duplicate Review Tasks

Symptom: Two or more identical Review Tasks appeared for the same step (e.g., two "Acceptance" tasks for a single permit).

Cause A: Missing dedup guard condition

Every automation must have a trigger condition checking that a status field is empty. Without it, the trigger fires on every record update, not just the first time.

How to identify:

1. Open the automation in the Automation Builder
2. Look at the Trigger conditions
3. There should be a condition: "[Step Status] is empty" (e.g., "Acceptance Status is empty")
4. If this condition is missing, the automation fires on every update to the record

Fix: Add the dedup guard condition — "[Step Status] is empty"

Cause B: Guard field not set by the Update Record action

Even if the guard exists in the trigger, if the Update Record action doesn't set that same field to a value (e.g., "Pending"), the guard stays empty and the automation fires again on the next update.

How to identify:

1. Open the Update Record action (the one after Create Record)
2. Verify it sets the same field that the trigger checks:
   • Trigger checks: "Acceptance Status is empty"
   • Update Record must set: "Acceptance Status = Pending"

Fix: Add or correct the field update in the Update Record action.

Cause C: Update Record action is missing entirely

Some automations may have a Create Record action but no Update Record action to close the guard.

Fix: Add an Update Record action after Create Record that sets the guard field to "Pending".

Cause D: Legacy automations were accidentally reactivated

Howard County has legacy automations (e.g., Status Sync (origin), TEST - Status Sync - Zoning v2) that were deactivated during the migration. If reactivated, they can produce unexpected behavior.

Fix: Check the Status Syncing folder in Automation Builder. All automations in that folder should remain inactive.

---

Section 3: Chain Stall

Symptom: A review step was completed (e.g., Acceptance status set to "Approved"), but the next automation in the chain didn't fire (no Issuance Review Task was created).

Step 1: Verify the completed status matches the trigger exactly

The next automation triggers on a specific status value. If the actual value doesn't match, the trigger won't fire.

Fix: Open the next automation and check its trigger conditions. If necessary, expand accepted values to include "Approved with Conditions" and "Review Not Required".

Step 2: Check the dedup guard on the next automation

The next automation also has a guard condition. If that guard field already has a value from a previous run (e.g., a prior test), the automation won't fire again.

Fix: Clear the stale guard field on the test record (set to empty) and try again.

Step 3: Verify the upstream automation set Application Status correctly

Some downstream automations trigger on changes to Application Status. Confirm the upstream automation's Update Record action sets Application Status to the expected value.

Application Status progression:

Step 4: Walk the chain linkage

Trace the chain to ensure each automation's output triggers the next:

Automation 1 sets: Acceptance Status = Pending
  → User sets: Acceptance Status = Approved
    → Automation 2 triggers on: Acceptance Status = Approved
    → Automation 2 sets: Issuance Review Status = Pending
      → User sets: Issuance Review Status = Issued
        → Automation 3 triggers on: Issuance Review Status = Issued

A mismatch (e.g., Automation 2 sets "Issuance Status" but Automation 3 checks "Issuance Review Status") will break the chain.

---

Section 4: FORK Issues

Symptom: A FORK automation fired but created the wrong number of Review Tasks, or tasks are missing parent associations.

Too Few Review Tasks Created

1. Open the FORK automation and count the Create Record action nodes — each node creates exactly one Review Task
2. If the count is correct but fewer tasks appeared, one or more Create Record actions may have failed silently — check for Review Tasks with missing field values that may have been created out of sequence

Too Many Review Tasks Created

The FORK automation fired more than once. See Section 2: Duplicate Review Tasks.

Review Tasks Missing Parent Association

If you see this symptom after February 26, 2026:

1. Open each Review Task created by the FORK
2. Check the "Parent Building Permit" (or equivalent) association field
3. If the field is empty on some tasks, escalate to the dev team with the parent permit ID and the time the FORK fired

---

Section 5: JOIN Never Fires

Symptom: All parallel reviews are complete, but the JOIN automation didn't fire to create the next step.

Step 1: Verify ALL review status fields match JOIN conditions

The JOIN trigger requires every condition to be satisfied simultaneously.

1. Open the JOIN automation (e.g., Res Bldg - JOIN → Create Issuance)
2. List every status field condition in the trigger
3. Open the parent permit record and compare each field value to what the JOIN expects

Example check:

In this example, the JOIN won't fire because Electrical Review Status is still "Pending".

Step 2: Check the JOIN's dedup guard

The JOIN has its own guard (e.g., "Issuance Review Status is empty"). If this field already has a value, the JOIN won't fire even if all review conditions are met.

Step 3: Check for condition drift

The JOIN conditions must exactly match the departments in the corresponding FORK. A common cause of stuck JOINs:

• A department was removed from the FORK, but the JOIN still checks their status field — which never gets set, so the JOIN waits forever
• A department was added to the FORK, but the JOIN wasn't updated to check the new department's field

Fix: Audit the JOIN conditions against the FORK's Create Record nodes. See the Modifying Review Requirements runbook for the full procedure.

Step 4: Verify "Review Not Required" is included

For each department condition in the JOIN trigger, confirmed values should include all three:

• Approved
• Approved with Conditions
• Review Not Required

If "Review Not Required" is missing as an accepted value, a department that marks their task as Review Not Required will stall the entire JOIN.

---

Section 6: Wrong Permit Type Triggered

Symptom: An automation meant for one permit type fired on a different permit type.

Root Cause: Missing routing conditions

Every automation must include routing conditions that restrict it to the correct permit type. Without them, the automation fires on any record that matches the non-routing conditions (like "Acceptance Status is empty").

Required Routing Conditions

Trade Permits — require BOTH:

Without both conditions, a "Residential Electrical" automation could also fire on "Commercial Electrical" or "Residential Plumbing" records.

Building Permits — require at minimum:

Licenses:

Enforcement: No additional routing needed (single entity type).

Fix

1. Open the automation that fired incorrectly
2. Add the missing routing conditions
3. Save and Publish
4. Test by creating a record of the wrong type — the automation should not fire

---

Section 7: Email and Notification Issues

Symptom: A notification email was not sent, or was sent to the wrong recipient.

Email Not Sent

Email Sent to Wrong Recipient

The recipient is typically pulled from an association field on the triggering record (e.g., "Applicant" → Constituent record with an email address).

1. Open the triggering record
2. Check the association field used for the email recipient
3. Open the linked Constituent record and verify the email address

If the email address is wrong, update it on the Constituent record. The automation will use the corrected address on the next run.

---

Section 8: Incorrect Review Task Data

Symptom: A Review Task was created but has wrong or missing values.

Wrong or Missing Name

The Review Task Name should follow: [Review Step] - [Record Number] (e.g., "Acceptance - BP-2026-00142").

If the name is blank or shows a raw field reference:

1. Open the automation's Create Record action
2. Check the Name field configuration
3. It should use a dynamic text binding referencing the parent record's Record Number
4. Verify the binding points to the correct field and that dynamic mode is enabled

Missing Reviewer

If the Reviewer field is blank on created Review Tasks:

1. Open the Create Record action
2. Check the Reviewer field

Wrong Review Type

If the Review Type dropdown shows the wrong department:

1. Open the Create Record action
2. Check the Review Type dropdown value — verify it matches the intended department (e.g., "Zoning" not "Building Plan Review")

Missing Due Date

Due dates are calculated relative to creation date. If missing:

1. Open the Create Record action
2. Check the Due Date field — it should be set to a relative date (e.g., "Today + 5 days")
3. Verify the "Days Allowed" field is also populated

---

General Debugging Checklist

Use this when you're not sure where to start:

• Is the automation published and active?
• Do the trigger conditions match the test record field-by-field?
• Was the record created/updated through the UI form (not the API)?
• Is the dedup guard field empty on the record?
• Are there other automations that might interfere with the guard field?
• Is the entity correct (Building Permit vs. Trade Permit vs. License vs. Enforcement)?
• Are all routing conditions present (Trade Type + Category, or Building Permit Type)?
• For JOINs: Are ALL review status fields in a completed state?
• Were any legacy automations accidentally reactivated (Status Syncing folder)?

---

When to Escalate

Escalate to the development team if:

• The automation is published, active, conditions match, record was UI-created, and it still doesn't fire
• An automation that was previously working suddenly stops (no config changes made)
• You see unexpected errors or behavior in the Automation Builder UI
• Review Tasks are created with missing association data (possible platform-level issue)

When escalating, provide:

1. Automation name and ID
2. Test record ID
3. Exact time of the test
4. Screenshots of the trigger conditions and the record's field values
5. What you expected vs. what actually happened

---

Appendix A: Known Resolved Platform Issues

These issues have been fixed, but are documented in case similar symptoms reappear:

---

Appendix B: Automation Folder Map

Use this to find the right automation when troubleshooting:

Inventory reflects configuration as of February 27, 2026. See the HoCo Automation Inventory for the full per-permit-type listing.