Configuration Guide: Request Additional Fee Workflow

---

Overview

This guide provides step-by-step instructions for configuring the Request Additional Fee workflow. This feature allows staff members to request additional payments from citizens on existing permit/license applications. When staff updates the fee amount, an automated email is sent to the applicant with a secure link to complete payment.

Workflow Summary

---

Prerequisites

Before configuring this workflow, ensure you have:

• Admin access to Entity Manager
• Admin access to Automation Builder
• Admin access to Form Builder
• A configured Payment Provider (Govolution, Stripe, or PayPal)
• The target entity (permit/license type) already exists

---

Configuration Steps

Step 1: Add Additional Fee Fields to Entity

First, add the required fields to the permit/license entity where staff will enter the additional fee.

1.1 Navigate to Entity Configuration

1. Open Entity Manager
2. Select the target entity (e.g., "Building Permits", "Business Licenses")
3. Go to Configure Entity -> Fields

1.2 Add Additional Fee Amount Field

Create a currency/number field for the fee amount:

Configuration Details:

• Enable "Allow decimal" for currency precision
• Set currency symbol to "$"
• Consider adding min/max validation if needed

1.3 Add Fee Description/Note Field (Optional)

Create a text field for staff to explain the fee:

1.4 Add Fee Request Status Field (Optional)

For tracking the payment status:

1.5 Save Entity Configuration

1. Review all new fields
2. Click Save to update the entity
3. Fields are now available on entity records (all entity fields display by default on record detail views)

---

Step 2: Create Payment Form for Citizens

Create a dedicated form that citizens will use to pay the additional fee.

2.1 Navigate to Form Builder

1. Open Entity Manager
2. Select the same entity as Step 1
3. Go to Forms tab
4. Click Create New Form

2.2 Configure Form Basic Settings

2.3 Add Form Fields

Add the following entity fields to the form so applicants can see what they're paying for:

Note: Form fields display the current values from the entity record. If you want applicants to only view (not edit) certain fields, do not include them in the form - they will see the payment amount in the Payment Field component which pulls from the entity.

2.4 Add Payment Field

Add the Payment Field to the form:

2.5 Configure Payment Field

In the Payment Field configuration:

1. Amount Configuration:

   • Select "Use field value" for dynamic amount
   • Map to additional_fee_amount field
   • This ensures the payment amount matches what staff entered

2. Payment Provider Settings:

   • Select the appropriate provider (Govolution/Stripe/PayPal)
   • Ensure provider is configured in system settings

3. Success/Cancel URLs:

   • Success URL: Will return to form with payment confirmation
   • Cancel URL: Will return to form to retry

2.6 Save and Publish Form

1. Click Save to save the form configuration
2. Click Publish to make the form available

2.7 Get Citizen Portal Link

The Citizen Portal link is automatically generated and accessible via the Share Form button:

1. While viewing the form as an admin, click "Share Form" button
2. A dialog appears with two link options:
   • Public Form Link - Direct link to the public form
   • Citizen Form Link - Link for the Citizen Portal
3. Click "Copy" next to the Citizen Form Link
4. This URL will be used in the automation email template

The Share Form dialog provides both "Open" and "Copy" buttons for easy access to the form links.

---

Step 3: Create Email Notification Automation

Set up an automation that triggers when staff updates the additional fee amount.

3.1 Navigate to Automation Builder

1. Open Automation Builder
2. Click Create New Automation

3.2 Configure Automation Basic Settings

3.3 Configure Trigger

Trigger Type: Record Updated

Trigger Configuration:

Trigger: When record is updated
Entity: Building Permits (or your entity)
Conditions:
  - Field "additional_fee_amount" has changed
  - AND "additional_fee_amount" is not null/empty
  - AND "additional_fee_amount" > 0

This ensures the automation only fires when:

• Staff enters a new fee amount
• Staff updates an existing fee amount
• The amount is a valid positive number

3.4 Configure Email Action

Action Type: Send Email

Email Configuration:

To (Recipient):

• Use field reference: {{record.applicant_email}} or {{record.primary_contact_email}}
• Or: {{record.contact.email}} (depending on your entity structure)

Subject:

Action Required: Additional Fee for {{record.record_number}}

Email Body:

The email body uses a rich text editor (Quill Editor) which supports formatted text. Compose your message using the editor's formatting tools:

Sample Email Content:

Additional Fee Required

Dear {{record.applicant_name}},

An additional fee has been requested for your application:

Record Number: {{record.record_number}}
Property Address: {{record.property_address}}
Additional Fee Amount: ${{record.additional_fee_amount}}
Reason: {{record.additional_fee_description}}

To complete your payment, please click the link below:

[Paste the Citizen Form Link from Step 2.7 here, appending ?record_id={{record._id}}]

Example: https://permits.howardcountymd.gov/citizen/form/abc123?record_id={{record._id}}

You will be asked to log in to the Citizen Portal to complete your payment securely.

If you have questions about this fee, please contact the permitting office at (410) 555-0100.

Department of Inspections, Licenses, and Permits

Note: Use the rich text editor's formatting tools (bold, links, etc.) to format your email. The editor supports inserting links - highlight text and use the link tool to create clickable payment links.

Template Variables:

3.5 Optional: Add Update Record Action

After sending the email, update the fee status:

Action Type: Update Record

3.6 Save and Test Automation

1. Click Save to save the automation
2. Set status to Test Mode initially
3. Test with a sample record (see Testing section below)
4. Once verified, set status to Active

---

Step 4: Configure Views (Optional)

Entity fields display on record detail views by default. Use views to control which fields are visible in different contexts.

4.1 Configure Staff View

By default, all entity fields (including the new additional fee fields) appear on record detail views. If you want to organize or hide certain fields:

1. Open Entity Manager -> Select entity
2. Go to Views tab
3. Select or create a staff view
4. Fields can be removed from specific views if needed
5. Consider grouping fee-related fields together for easier access

4.2 Configure Public/Applicant View

To control what applicants see when viewing their permit record:

1. Go to Views tab
2. Select or create a public/applicant view
3. Remove fields that should not be visible to applicants
4. Keep additional_fee_status visible so applicants can see payment status

Note: Field visibility is controlled through views, not at the individual field level. Create different views for different user roles/contexts.

---

Staff Workflow

How Staff Requests Additional Fee

1. Open the permit/license record in Entity Manager
2. Locate the additional fee fields (displayed with other entity fields)
3. Enter the fee amount in "Additional Fee Amount" field
4. Enter description (optional but recommended) explaining why the fee is needed
5. Save the record
6. Automation triggers:
   • Email is sent to the applicant
   • Status is set to "Pending"
7. Monitor payment status on the record

Staff Best Practices

1. Always include a description - Helps applicant understand the fee
2. Double-check the amount - Automation sends immediately on save
3. Notify applicant verbally if possible - Phone call for large amounts
4. Monitor pending fees - Use a filtered view to track unpaid fees

---

Applicant Experience

What the Applicant Sees

1. Receives email notification with fee details
2. Clicks payment link in email
3. Redirected to Citizen Portal login page
4. Logs in with their credentials
5. Redirected to payment form showing:
   • Record information
   • Fee amount and description
   • Pay Now button
6. Clicks Pay Now -> Redirected to payment provider
7. Completes payment on payment provider page
8. Returns to portal with confirmation
9. Payment recorded on their permit record

Payment Form Display

The applicant sees:

+-----------------------------------------------------+
| Additional Fee Payment                              |
+-----------------------------------------------------+
|                                                     |
| Record Number: BLD-2025-001234                      |
| Property: 123 Main Street, Columbia, MD             |
|                                                     |
| -------------------------------------------------   |
|                                                     |
| Additional Fee Amount: $150.00                      |
|                                                     |
| Reason: Re-inspection fee for failed                |
|         electrical inspection on 01/15/2025         |
|                                                     |
| -------------------------------------------------   |
|                                                     |
| Payment                                             |
| +---------------------------------------------------+
| | Total Amount Due: $150.00        [Pay Now]       |
| +---------------------------------------------------+
|                                                     |
+-----------------------------------------------------+

---

Testing the Configuration

Test Checklist

Before going live, verify:

• Additional fee fields are created on the entity
• Fields appear on staff record detail view
• Payment form is created and published
• Share Form provides the Citizen Form Link
• Payment field uses dynamic amount from entity field
• Automation triggers when fee amount is entered
• Email is sent with correct content and link
• Link redirects to portal login
• After login, redirects to payment form
• Payment processes correctly
• Payment status updates on record

Step-by-Step Test

1. Create a test permit record with your email as applicant
2. As staff, enter an additional fee amount (e.g., $25.00)
3. Add a description (e.g., "Test fee")
4. Save the record
5. Check your email for notification
6. Click the payment link
7. Verify redirect to login, then to payment form
8. Complete payment using test payment credentials
9. Verify payment is recorded on the record

Test Payment Credentials

Use your payment provider's test/sandbox credentials:

Stripe Test Card:

• Card: 4242 4242 4242 4242
• Exp: Any future date
• CVC: Any 3 digits

PayPal Sandbox:

• Use sandbox buyer account

Govolution Sandbox:

• Use test merchant credentials

---

Troubleshooting

Automation Not Triggering

Check:

1. Automation is set to "Active" (not "Test" or "Inactive")
2. Trigger conditions match exactly
3. Field name in trigger matches entity field ID
4. No additional filters blocking the trigger

Email Not Sent

Check:

1. Recipient email field reference is correct
2. Email service is configured
3. Check automation run history for errors
4. Verify email template variables are correct

Payment Link Not Working

Check:

1. Citizen Form Link from Share Form is correct
2. Record ID parameter is appended correctly (?record_id={{record._id}})
3. Form is published and accessible
4. Applicant has appropriate access

Payment Amount Wrong

Check:

1. Payment field is configured to use field value
2. Field mapping points to additional_fee_amount
3. Amount is being saved correctly on entity

Applicant Can't See Fee Information

Check:

1. Fields are included in the payment form
2. Form sections are not hidden
3. Public view includes the relevant fields

---

Advanced Configuration

Multiple Fee Types

For different fee types (re-inspection, expedited review, etc.):

1. Add a "Fee Type" dropdown field
2. Configure dropdown options
3. Include fee type in email template
4. Consider separate automations per fee type

Fee Approval Workflow

For fees requiring supervisor approval before sending:

1. Add "Fee Approved" checkbox field
2. Modify automation trigger:
   • Trigger when fee_approved = true
   • AND additional_fee_amount > 0
3. Staff enters fee -> Supervisor approves -> Email sent

Reminder Emails

To send reminders for unpaid fees:

1. Create scheduled automation
2. Trigger: Daily at specific time
3. Condition: additional_fee_status = "Pending" AND fee date > 3 days old
4. Action: Send reminder email

---

Related Documentation

• Fee Definitions & Payment Methods - Fee configuration
• Automation Builder - Automation setup

---

Technical Reference

Entity Field IDs

Automation Action Keys

Payment Field Configuration

{
  type: 'payment',
  label: 'Pay Additional Fee',
  amount_source: 'field',
  amount_field: 'additional_fee_amount',
  payment_provider: 'govolution' | 'stripe' | 'paypal',
  show_pay_button: true,
  show_fee_breakdown: false
}

Share Form Component

The Share Form popup (ShareFormPopup.tsx) provides:

• Public Form Link - Direct link with Copy and Open buttons
• Citizen Form Link - Citizen Portal link with Copy button

URL Format for Payment Form

Use the Citizen Form Link from Share Form, appending the record ID:

{CITIZEN_FORM_LINK}?record_id={{record._id}}

---

For additional configuration assistance, contact the GovAssist support team.