Use this reference for the fields on the engagement creation form, the tabs and columns in the engagements list, and the information shown on an engagement record.
Engagement Details Reference
Engagement Details is the starting point for creating an individual engagement or a batch. These settings determine the clients and contacts included, the staff associated with the letter, payment-method requirements, the letter template, and engagement dates. An engagement also includes clients, an engagement letter, contacts, and optional scopes of service.
Client details
Defaults come from the practice management system and the firm's implementation settings. Check the selected contacts before proceeding.
| Field | Purpose and default | Requirements and behavior |
|---|---|---|
| Primary Client | Client whose details populate the engagement. Search for and select the client when creating an individual engagement. | For a batch, this field appears on each draft's details page after the batch is generated. After the details are first saved, the primary client can only be changed to another client in the same client group. Batch-generated drafts are already saved when their individual details become available. For engagements created through renewal, the primary client cannot be changed. |
| Primary Contact | Defaults to one contact based on the selected client, practice management system contact classifications, and the firm's implementation settings. For example, the firm may use an Engagement Contact or Primary Contact classification. | Must have an email address to proceed. A different contact can be selected during creation or drafting. Available contacts include those associated with the primary client and other clients in the same client group. If clients outside that group are added on the main engagement draft screen, their contacts also become available for selection. |
| Billing Contact | Defaults according to the firm's implementation settings: either a contact associated with the primary client, based on a practice management system category or type, or the same person as the primary contact. | Can be changed and must have an email address to proceed. The billing contact completes any payment-method tasks assigned through Payment Prompt Settings. A multi-client engagement can have multiple billing contacts. |
Payment Prompt Settings
These settings control whether the billing contact is prompted to save a payment method. Saving a payment method and successfully collecting a prepayment are separate events.
| Setting | Billing contact experience | Effect on execution and reminders |
|---|---|---|
| Optional Payment Method | The billing contact may save a method, choose Set up later, or skip the payment step entirely. If they are not a signer, they are directed to review the letter and then see the payment prompt. | Payment setup does not block execution. Once all required signatures are complete, the engagement becomes Executed whether or not the billing contact enters a method. |
| Required Payment Method | The billing contact must review the engagement letter in the Client Portal and save a valid payment method. | After all signatures are complete, the engagement stays in Sent until the billing contact saves a method. A successful charge is not required unless the firm uses synchronized prepayment processing. |
| No Prompt for Payment Method | No contact is prompted for payment-method information. If the billing contact is different from the primary contact, the billing contact receives nothing under this setting. | Signatures are enough for execution; there is no payment-method setup requirement. |
By default, Aiwyn marks the engagement Executed after signatures and any required payment-method setup, then charges a configured prepayment. If the charge fails, the engagement remains Executed; the failure is logged and failure notifications are sent. If enable_sync_engagement_prepayment is enabled, the engagement stays in Sent until Stripe confirms payment. A firm-side Execute action bypasses these payment checks.
Firm details
The client's partner and manager are preselected from practice management system data.
| Field | Role | Notifications and behavior |
|---|---|---|
| Engagement Partner | The author of the engagement letter. Defaults to the client's designated partner and can be changed to any other active staff member. | Receives an email when the letter is signed and fully executed, with the signed engagement PDF attached. View Engagement opens the client's engagement in the Firm Portal. |
| Engagement Manager | The sender of the engagement letter. The manager's email address is used as the sender of the email to client contacts. | Receives an email when the letter is signed and fully executed, with the signed engagement PDF attached. View Engagement opens the client's engagement in the Firm Portal. |
| Engagement Collaborators | One or more additional staff members selected from the staff list. | Receive an email when the letter is signed and fully executed, with the signed engagement PDF attached. |
Letter and engagement settings
| Field | Purpose and default | Requirements and behavior |
|---|---|---|
| Letter Template | Template used to generate the engagement letter or letters in a batch. | Must be selected before proceeding. Choose the intended template from the list of letter templates for either an individual engagement or a batch. |
| Fiscal Year | Required year for the engagement; defaults to the current year. | Can be changed to a past or future year within the available four-year range. The selected year is available as a letter placeholder and determines which jobs are available on the next screen. It can also combine with the client's fiscal-year-end month and day from the practice management system to populate full-date placeholders. |
| Engagement Name | Name displayed throughout the Client and Firm Portals. | Can be changed for an individual letter or letter batch while editing details. A system-wide default naming structure can be configured in Engagement Settings, including variables such as Client Name. |
| Engagement Start Date | Required start-date choice. Defaults to On Acceptance, meaning the date the engagement is fully executed. | Alternatively, select a specific date in the past or future. Start Date placeholders populate only when a specific date is selected; they do not populate when On Acceptance is selected. Use a defined date if the template requires those placeholders. |
| Renewal Date | Optional date used for renewal reminders. | Includes the engagement in monthly renewal-reminder emails to engagement partners and managers when renewal is due within the next 90 days or is already overdue. A renewal date is not required to renew an engagement. |
Editing and saved-record restrictions
- Engagement details remain accessible and editable until the engagement is fully executed.
- Saving details for the first time restricts primary-client changes to clients within the same client group. This restriction already applies to individual drafts generated from a batch.
- The primary client cannot be changed on an engagement created through renewal.
Engagement list tabs
Users must have the View the Engagements module permission to access the main Engagements page and view the All Engagements tab.
| Tab | Returns |
|---|---|
| All Engagements | Engagements visible to the current user, regardless of ownership |
| My Engagements | Engagements where the current user is the assigned partner or manager |
| Assigned to Me | Engagements assigned to the current user for review, approval, or sending |
A record can appear in more than one tab.
Engagements homepage column reference
The main Engagements tab (the homepage) organizes columns into four top-level sections: Engagement Status, Client Details, Letter Details, and Firm Details.
Each section can be collapsed or expanded, and the sections themselves can be reordered. Within a section, each column can be moved or hidden. Section order, collapsed/expanded states, and column visibility and order preferences persist for each user. The Actions column is fixed and always remains visible.
Engagement Status
| Column | Description |
|---|---|
| Status | Current status of the engagement: Sent, Draft, Executed, Under Revision, Canceled, or Archived. |
| Assignee | The firm staff member assigned to the engagement. |
| Delivery | Green check mark if the engagement letter was delivered. If delivered manually, a Manual flag is also shown. |
| Payment Setup | Circle that fills with a green check mark when payment has been set up. Remains an empty circle if payment was not set up or a payment method was not requested. |
| Signatures | Green check mark when signatures have been collected. |
| Executed | Green check mark when the engagement has been executed. |
| DMS Upload | Green check mark when the letter has been uploaded to the Document Management System (DMS). |
| Executed Date | Blank until the engagement is executed; populated with the execution date once executed. |
Client Details
| Column | Description |
|---|---|
| Client Name | Name of the client. |
| Client Group | Client group the client belongs to. |
| Firm Office | Firm office associated with the client. |
| Client Number | Client's identifying number. |
| Additional Clients | Count of additional clients on the engagement (a number only, not client names). |
| Primary Contact | Name of the primary contact. |
| Secondary Contact | Name of the secondary contact. |
| Billing Contact | Name of the billing contact. |
| Fiscal Year End | Fiscal year end selected for the letter. |
Letter Details
| Column | Description |
|---|---|
| Letter Template | The letter template used for the engagement. |
| Batch ID | Batch ID number. |
| Projects | Number of projects added to the engagement. |
| Minimum Price | Low end of pricing when the project's price type is Hourly, if set. |
| Maximum Price | High end of pricing when the project's price type is Hourly, if set. When the project's price type is Fixed Fee, this column shows the overall fixed-fee amount. |
| Payment Method | The payment method prompt setting: Required, Optional, or Not Prompted. |
| Start Date | Either On Acceptance or the specific start date chosen. |
| Renewal Date | The renewal date chosen, if one was given. |
| Renewed | Indicates whether the engagement has been renewed. |
| Prior Engagement | Lists the prior engagement if this engagement is a renewal. |
Firm Details
| Column | Description |
|---|---|
| Partner | Partner on the engagement. |
| Manager | Manager on the engagement. |
| Created By | User who created the engagement. |
| Created At | Date/time the engagement was created. |
| Updated By | User who last updated the engagement. |
| Updated At | Date/time the engagement was last updated. |
| Reviewer | User who reviewed the engagement. |
| Reviewed On | Date the engagement was reviewed. |
| Approver | User who approved the engagement. |
| Approved On | Date the engagement was approved. |
| Sender | User who sent the engagement. |
| Sent On | Date the engagement was sent. |
Actions (fixed column)
| Column | Description |
|---|---|
| Actions | Three-dot menu (⋯) for each engagement. Options may include Send to Client, Download Document, Cancel, Archive, and Delete. Available options depend on the engagement's current status. |
Engagement record
| Area | Contains |
|---|---|
| Status badge | Current engagement status |
| Letter content | Generated engagement letter |
| Highlight dynamic content (dynamic letter templates) | Toggle in the letter editor. On, it highlights merged placeholders and outlines each dynamic block with a thick blue left border and a dynamic icon; off, it shows the flat letter as the client sees it. |
| Flatten / Edit on a block (dynamic letter templates) | Flatten turns the block into editable flat text on this letter only. Edit changes the block in the template and on every letter using it, and is shown only to users with template permissions. |
| Activity timeline | Dated engagement events such as creation, sending, opening, and signing |
| Client signature | Signature and timestamp after execution |
| Download | Control for downloading the executed PDF |
| Action controls | Available actions such as Send, Resend, Cancel/Void, and Renew |
Archive action and list visibility
Executed engagements can be archived from the main Engagements page using the three-dot menu in the Actions column and selecting Archive. The status changes to Archived, and the engagement can be restored at any time.
To hide archived engagements from the list, open the Engagement Status column filter, deselect Archived, and select Apply. This filter stays in place until you reset your filters.