MLP CMS User Guide

00 Quick Start

New to MLP CMS? This is the recommended end-to-end path for a brand-new user — follow these steps in order to get from first login to a fully tracked project.

1. Log in and register a passkey.
2. Set up Cost Codes and the Price List.
3. Create your first Project.
4. Create a Budget Proposal, approve it, and link it to the project.
5. Raise Change Orders as scope changes.
6. Bill the owner with Pay Applications (G702/G703).
7. Run QMS inspections and Daily Safety checks in the field.
8. Track everything on the Dashboard.

01 Getting Started

MLP CMS supports two authentication methods: passkeys (biometric/hardware key, recommended) and password. Both are available from the login screen.

Logging In with a Password

1. Navigate to the MLP CMS URL in your browser.
2. Enter your email address and password in the login form.
3. Click Sign In. You will be taken to the Dashboard.

Logging In with a Passkey

1. On the login screen, click Sign in with Passkey.
2. Your browser will prompt for biometric verification (Face ID, Touch ID, Windows Hello, or a hardware security key).
3. Authenticate — you are logged in immediately, no password required.

Session Restore

If your session expires while you are working, MLP CMS automatically redirects you to the login screen. After you re-authenticate, the system returns you to the exact page you were on — no need to navigate back manually.

First-Time Setup Checklist

• Confirm your profile name and email in System Settings.
• Register a passkey for faster future logins.
• Ask your administrator to assign you the correct role.
• Set up Cost Codes and the Price List before creating projects.

02 Dashboard

The Dashboard is the home screen of MLP CMS. It provides a high-level financial and operational snapshot across all active projects.

Financial Dashboard

The financial dashboard displays portfolio-wide stats including total contracted value, total billed to date, net cash position, and outstanding retainage. Cards update in real time as Pay Applications are approved.

Project Dashboard

Selecting a project from the sidebar opens that project's dashboard, showing budget vs. actuals, CO summary, PA progress, and open items counts for RFIs, Submittals, and Punch List.

Activity Log

The Activity Log records every create, edit, and status-change action performed in the system. Each entry shows the user, timestamp, module, record affected, and a description of the change. Use the Clear Log button (admin only) to archive old entries. The log is append-only — individual entries cannot be deleted.

Stats Cards

Stats cards on the dashboard surface key metrics at a glance:

• Active Projects — projects in Active or In Progress status
• Open RFIs — RFIs awaiting response
• Pending COs — Change Orders submitted but not yet approved
• Overdue Punch Items — punch items past their due date

03 Projects

Projects are the top-level container for all CMS data. Every record — COs, PAs, RFIs, Submittals — belongs to a project.

Creating a Project

1. Click Projects in the sidebar, then + New Project.
2. Enter the project name, project number, owner, and start/end dates.
3. Set the initial contract value (this can be updated when Budget Proposals are approved).
4. Click Save. The project appears in the project list.

Editing a Project

Open the project, click the Edit button in the top-right corner, adjust any fields, and click Save. All changes are recorded in the Activity Log.

Setting the Budget

The project budget is set by linking an approved Budget Proposal. Navigate to the project's Budget tab and click Link Budget Proposal. Once linked, the project budget reflects the approved BP total.

Project Status Lifecycle

04 Budget Proposals

Budget Proposals (BPs) define the initial scope and cost breakdown for a project before work begins. An approved BP becomes the project baseline budget.

Creating a Budget Proposal

1. Navigate to Budget Proposals in the sidebar and click + New BP.
2. Select the associated project and enter a description and proposal date.
3. Add line items — each line item requires a Cost Code, description, quantity, unit, and unit price.
4. Save the BP as a Draft.

Line Items

Each line item pulls from the Cost Code list and optionally from the Price List for unit prices. The BP total auto-calculates as you add or edit lines.

Approving a Budget Proposal

1. Open the BP and review all line items.
2. Click Submit for Approval to move it to Pending.
3. An authorized approver clicks Approve. Status changes to Approved.
4. Link the approved BP to the project under the project's Budget tab.

Linking to a Project

Only one approved BP can be active per project at a time. Linking an approved BP sets the project's budget baseline. Subsequent cost changes are captured through Change Orders.

05 Cost Codes

Cost Codes organize project costs by category (e.g., 03000 – Concrete, 05000 – Metals). They are used as line item classifications in Budget Proposals, Change Orders, and Pay Applications.

Managing Cost Codes

1. Navigate to Cost Codes in the sidebar.
2. Click + New Cost Code.
3. Enter the code number, description, and cost category.
4. Click Save.

Cost Codes can be edited at any time. Deleting a Cost Code that is in use on existing records is prevented — archive it instead using the Deactivate toggle.

Using Cost Codes in Line Items

When adding a line item to a BP or CO, select a Cost Code from the dropdown. This links the cost to the correct budget category and enables category-level roll-up reporting.

06 Price List

The Price List is a catalog of unit prices for commonly used materials, equipment, and labor. Referencing the Price List in line items ensures consistent pricing across the project.

Managing Unit Prices

1. Navigate to Price List in the sidebar.
2. Click + New Price Item.
3. Enter item name, unit of measure, unit price, and optional notes.
4. Click Save.

Using Price List Items in COs and BPs

When adding a line item, click the price lookup icon to select an item from the Price List. The unit price auto-fills; you can override it if the project-specific price differs. The Price List item is recorded as a reference but the override value is what gets saved to the record.

07 Change Orders

Change Orders (COs) document scope changes that affect the contract value after the baseline budget is set. Every approved CO increases or decreases the project's total contract amount.

Creating a Change Order

1. Navigate to the project and open the Change Orders tab, or click Change Orders in the sidebar.
2. Click + New CO.
3. Enter the CO number, title, description, and date.
4. Add line items with Cost Codes, quantities, and unit prices.
5. Save as Draft.

Submitting and Approving

1. Click Submit for Approval. Status changes to Pending.
2. An approver reviews and clicks Approve or Reject.
3. Approved COs become available for inclusion in the next Pay Application.
4. Rejected COs return to Draft for revision.

PDF Export

Open an approved CO and click Export PDF to generate a formatted change order document suitable for owner submission.

CO Locking

CO Status Lifecycle

08 Pay Applications

Pay Applications (PAs) are billing documents in AIA G702/G703 format. Each PA represents one billing period and rolls up all approved Change Orders into a cumulative contract value.

Creating a Pay Application

1. Navigate to Pay Applications in the sidebar and click + New PA.
2. Select the project and billing period (application number, period from/to dates).
3. The system auto-populates G703 line items from all approved COs not yet captured in a previous PA.
4. Enter percent complete for each line item under Completed Work.
5. Enter stored materials amounts if applicable.
6. Review the G702 summary (contract sum, net change by COs, contract sum to date).
7. Save and submit.

Retainage

MLP CMS supports split-rate retainage:

• Completed Work Retainage % — percentage withheld from work performed (typically 10%, reducing to 5% at substantial completion).
• Stored Materials Retainage % — percentage withheld from stored materials on site (can differ from completed work rate).

Both rates are set per PA and apply to all line items on that PA. The system calculates retainage amounts automatically.

PA Chain Math — Less Previous Certificates

The G702 form tracks cumulative progress. The field Less Previous Certificates for Payment automatically carries forward the approved total from the previous PA in the sequence. You do not enter this manually — the system calculates it from the PA chain. This ensures each draw request correctly reflects only the current period's earned value.

PDF Export — G702/G703

1. Open the PA.
2. Click Export PDF.
3. The system generates a properly formatted AIA G702 cover sheet and G703 continuation sheet.
4. Download or email the PDF directly from the export dialog.

8a Project Budget

The Project Budget module provides a live, Procore-aligned view of all financial activity on a project — from the original baseline through committed costs, cost incurred, and forecast to complete. Access it by selecting a project and clicking the Budget tab.

Budget Overview Tab

The Overview tab is the primary budget management view. It presents a 10-column table where each row is a budget line item (cost code / scope area):

A Grand Totals row at the bottom of the table summarizes each column across all lines. A color-coded progress bar beneath the summary cards indicates budget consumption: green below 75%, amber at 75–90%, red above 90%.

Summary Cards

Four KPI cards appear above the table:

• Original Budget — baseline contract value
• Current Est Budget — budget adjusted for all approved changes
• Cost Incurred — actual spend to date
• Budget Remaining — Current Est Budget minus Cost Incurred

Lock Budget

Click Lock Budget to freeze the budget baseline for the current period. Locking prevents further edits to the Original Budget column and signals a formal budget sign-off. A locked budget can be unlocked by a project administrator.

Export CSV

Click Export CSV to download the full 10-column budget table as a spreadsheet. The export includes all line items and the Grand Totals row, formatted for import into Excel or other cost management tools.

Budget Changes Tab

Budget Changes capture revisions to the project budget after the baseline is set. Unlike Change Orders (which track owner-facing contract changes), Budget Changes track internal cost reallocations, contingency draws, and value engineering savings.

Creating a Budget Change

1. Open the Project Budget and click the Budget Changes tab.
2. Click + New Change.
3. Select the change type, affected budget line, and enter the amount (positive or negative).
4. Add a description and supporting notes.
5. Save as Draft.

Budget Change Types

Budget Change Workflow

Approved Budget Changes immediately update the Approved Changes column in the Budget Overview table. Rejected changes return to Draft for revision. Voided changes are removed from all calculations.

Snapshots Tab

Snapshots capture a complete point-in-time record of all budget column values. Use them to preserve baselines before a major scope change, compare budget health across phases, or satisfy audit requirements.

Creating a Snapshot

1. Click the Snapshots tab.
2. Click + New Snapshot.
3. Enter a name (e.g., "Pre-CO #4 baseline") and optional notes.
4. Click Capture. The system records all 10 column values for every budget line at the current moment.

Comparing Snapshots

Select any two snapshots and click Compare. A side-by-side variance modal shows the delta for each column and each line — positive variance (budget grew) in green, negative variance (budget shrank) in red. Snapshots are immutable after creation.

Forecast to Complete Tab

The Forecast to Complete tab projects final cost outcomes based on current progress. For each budget line item, enter the estimated percent complete to see the system calculate EAC, ETC, and variance.

The Totals row at the bottom aggregates EAC, ETC, and Variance across all lines, giving a project-level forecast health summary. EAC values are persisted back to each line item when saved.

09 RFIs

Requests for Information (RFIs) are formal questions submitted to the design team or owner when clarification is needed on contract documents.

Creating an RFI

1. Navigate to RFIs in the sidebar and click + New RFI.
2. Select the project, enter a subject, question text, and required-by date.
3. Assign the RFI to the appropriate respondent.
4. Click Submit.

Responding to an RFI

The assigned respondent opens the RFI and enters their response in the Official Response field, then clicks Respond. The submitter is notified and the RFI status updates to Responded.

Closing an RFI

After reviewing the response, the originator clicks Close RFI to mark it resolved. Closed RFIs are read-only but remain searchable.

RFI Status Workflow

10 Submittals

Submittals track shop drawings, product data, samples, and other contractor-furnished documents that require design team review before fabrication or installation.

Creating a Submittal

1. Navigate to Submittals and click + New Submittal.
2. Select the project, spec section, submittal type, and description.
3. Set the required-by date and assign the reviewer.
4. Attach the submittal document and click Submit.

Review Cycle

The reviewer opens the submittal, reviews the attached documents, selects a review action, and enters comments. Available review actions:

• Approved — no revisions required; work may proceed.
• Approved as Noted — minor comments; work may proceed subject to corrections.
• Revise and Resubmit — significant issues; corrected submittal required.
• Rejected — submittal does not comply; new submittal required.

Revision Tracking

Each resubmission creates a new revision number (Rev 01, Rev 02, etc.) while preserving the full history. The submittal log shows all revisions and their review outcomes.

11 Punch List

The Punch List tracks deficiencies and incomplete work items identified during inspections or walkthroughs near project completion.

Creating Punch Items

1. Navigate to Punch List and click + New Item.
2. Enter the item description, location, responsible party, and due date.
3. Attach photos if available.
4. Click Save.

Assigning and Resolving Items

Assign punch items to the appropriate subcontractor or foreman. The assignee updates the status to In Progress when work begins and Resolved when complete. The project manager can verify and mark items Closed.

Filtering

Use the filter bar to view items by status, assignee, location, or due date. Use the Export button to generate a punch list report in PDF format.

Punch Item Status

12 Meeting Minutes

Meeting Minutes capture decisions, agenda items, and action items from project meetings — OAC meetings, coordination meetings, and safety meetings.

Creating a Meeting

1. Navigate to Meeting Minutes and click + New Meeting.
2. Enter the meeting type, date, location, and attendees.
3. Add agenda items in the order they will be discussed.
4. Save as a draft to fill in during or after the meeting.

Agenda and Action Items

Within each agenda item, record discussion notes and assign action items. Each action item has an owner, due date, and status. Action items carry forward to the next meeting's open items list if not yet resolved.

Distributing Minutes

1. After the meeting, finalize the minutes and click Distribute.
2. Select recipients from the attendee list or enter additional emails.
3. The system generates a formatted PDF and emails it to all recipients.
4. Minutes are locked after distribution.

13 Gantt Chart

The Gantt Chart provides a visual timeline of project tasks, milestones, and dependencies.

Viewing the Project Timeline

Navigate to Gantt in the sidebar to see the current project's timeline. Tasks are displayed as horizontal bars scaled to the project calendar. Drag the timeline to scroll through time periods, or use the zoom controls to switch between day/week/month views.

Milestones on the Gantt

Milestones (see Section 14) appear as diamond markers on the Gantt. Hover over a milestone to see its description and target date.

Task Dependencies

Dependency lines connect tasks that must finish before the next can start (Finish-to-Start). If a predecessor task slips, the Gantt highlights dependent tasks in amber to indicate potential schedule impact.

14 Milestones

Milestones mark key project events — permit approval, foundation pour, substantial completion, final inspection — that have no duration but must be tracked against the schedule.

Creating a Milestone

1. Navigate to Milestones and click + New Milestone.
2. Enter the milestone name, target date, and description.
3. Link to the appropriate project.
4. Click Save.

Tracking Completion

When a milestone is reached, open it and click Mark Complete. Enter the actual completion date and any notes. Completed milestones show a green checkmark on the Gantt chart and in the project dashboard milestone panel.

Milestone Status

15 QMS Inspections

The Quality Management System (QMS) module tracks non-conformances, daily quality control checklists, and formal inspection records.

Non-Conformance Reports (NCRs)

1. Navigate to QMS → NCRs and click + New NCR.
2. Describe the non-conforming condition, location, and affected specification section.
3. Assign a corrective action responsible party and due date.
4. Attach photos or supporting documents.
5. Submit the NCR. The assignee is notified to take corrective action.
6. After correction, the QC manager verifies and closes the NCR.

Daily QC Checklists

Daily checklists provide a structured quality verification routine for work-in-place. Navigate to QMS → Daily Checklists and select today's checklist template. Check off each inspection item, enter observations, and submit. All checklist submissions are date-stamped and tied to the project record.

Inspection Records

Formal inspection records (structural, mechanical, electrical, etc.) are logged under QMS → Inspections. Each record captures the inspection type, inspector name, date, result (pass/fail/conditional), and any required follow-up actions.

16 Daily Safety

The Safety module supports daily safety reporting, Job Hazard Analyses, and OSHA recordkeeping requirements.

Daily Safety Reports

1. Navigate to Safety → Daily Reports and click + New Report.
2. Enter the date, weather conditions, crew size, and superintendent name.
3. Document any safety observations, near-misses, or incidents.
4. Note any toolbox talks or safety briefings conducted.
5. Click Submit to finalize the daily report.

Job Hazard Analysis (JHA)

JHAs break down hazardous tasks into steps and identify controls for each hazard. Navigate to Safety → JHAs to create or review JHAs. A JHA must be reviewed and signed by all workers performing the task before work begins. The system records acknowledgment timestamps.

OSHA 300A Log

Work-related injuries and illnesses are recorded under Safety → OSHA Log. The system auto-populates the OSHA 300A summary from individual incident entries. At year-end, export the 300A summary for posting and regulatory reporting.

17 Reports

MLP CMS provides a library of pre-built reports covering financial, operational, and compliance data across all modules.

Available Reports

Generating a PDF Report

1. Navigate to Reports in the sidebar.
2. Select the desired report from the list.
3. Set filter parameters (project, date range, status).
4. Click Generate PDF. The report opens in a preview panel.
5. Download or print from the preview toolbar.

Export Options

Most reports support export as PDF or CSV. The CSV export is suitable for import into Excel or other financial analysis tools.

18 System Settings

System Settings are accessible from the sidebar (gear icon at the bottom) and require administrator privileges. Settings changes are recorded in the Activity Log.

Company Settings

Set your company name, logo, address, and contact information. These values appear on all generated PDFs and email correspondence.

User Management

Administrators can invite new users, assign roles, and deactivate accounts. Available roles typically include:

• Administrator — full access including system settings
• Project Manager — create and manage all project records, approve COs and PAs
• Field User — create RFIs, daily reports, punch items; cannot approve financial records
• Read-Only — view all records; no create/edit access

Passkey Management

Users can register multiple passkeys (e.g., laptop Face ID and a hardware security key). Under Settings → Passkeys, click + Register Passkey and follow the browser prompt. Existing passkeys can be named and removed from this panel.

Performance & Admin Settings

Advanced settings include database maintenance options, session timeout duration, and feature toggles. These settings should only be modified by technical administrators.

Recycle Bin

Deleted records are held in the Recycle Bin for 30 days before permanent deletion. Administrators can restore items from the Recycle Bin. Purging items from the Recycle Bin is permanent and cannot be undone.

19 Offline Mode

MLP CMS is offline-first. You can continue working without an internet connection — all changes save locally and sync automatically when connectivity is restored.

How Offline Mode Works

1. Your device loses connectivity (WiFi drops, cellular dead zone, airplane mode).
2. An amber offline banner appears at the top of the screen showing the number of changes queued locally.
3. Continue working normally — create records, fill forms, update statuses. Everything saves to the local queue.
4. When connectivity is restored, the banner changes and the system automatically syncs all queued changes to the server.
5. If the same field was changed by two different users during the offline period, a conflict resolution modal appears (see below).

Conflict Resolution

A 3-way merge is performed when changes sync. If two users edited the same field while both were offline, the conflict resolution modal shows:

• Your version — what you entered offline
• Server version — what the other user saved
• Original value — what the field said before either edit

For each conflicting field, click the version you want to keep, then click Resolve. Non-conflicting fields are merged automatically — you only need to decide on the conflicting ones.

20 Notifications & Toasts

MLP CMS uses toast notifications to provide immediate feedback on every action. Toasts appear in the bottom-right corner of the screen and auto-dismiss after a few seconds.

Toast Types

409 Duplicate Detection

When you attempt to save a record that conflicts with an existing record (e.g., duplicate CO number, duplicate RFI number), the system returns a 409 Conflict response and shows a red toast: "A record with this identifier already exists." Change the conflicting field and save again.

In-App Notifications

The bell icon in the header shows unread notifications for assignments, approvals, and @mentions. Click the bell to open the notification panel. Mark items as read individually or use Mark All Read.

21 Troubleshooting

Most issues in MLP CMS have simple solutions. If you cannot resolve an issue using this guide, use the Report an Issue button in the sidebar or email cms@mlpsolutionsgroup.com.

Session Expired

Symptom: You are redirected to the login screen mid-work.
Resolution: Log in again. MLP CMS will automatically return you to the page you were on before the session expired — your unsaved form data may not be preserved, but your navigation position is restored.

Offline Banner Won't Clear

Symptom: The amber offline banner remains after reconnecting.
Resolution: Check your internet connection. If connected, wait 30 seconds for the auto-sync to complete. If it persists, refresh the page — your queued changes are stored locally and will re-attempt sync on reload.

409 Conflict Errors

Symptom: Red toast saying "A record with this identifier already exists."
Resolution: Change the duplicate field value (e.g., CO number, RFI number) to a unique value and save again.

Conflict Resolution Modal Appears

This modal appears when two users edited the same record while offline. Select the correct value for each conflicting field and click Resolve.

PDF Not Generating

Symptom: Clicking "Export PDF" produces no output or an error.
Resolution:

• Ensure you are connected to the internet (PDF generation happens server-side).
• Verify the record is in a completed/approved state — draft records cannot be exported.
• Check that your browser is not blocking pop-ups (PDFs open in a new tab).
• Try a different browser. If the issue persists, contact support.

Unable to Edit a CO

Symptom: A Change Order is read-only and shows a lock icon.
Resolution: The CO is locked because it has been included in a Pay Application. Locked COs cannot be edited. Contact your project administrator if a correction is required.

Contacting Support

Click Report an Issue in the sidebar to open a pre-filled support request, or email cms@mlpsolutionsgroup.com directly. Include the project name, module, and a description of what you were doing when the issue occurred.

22 Release Notes

v3.1.6 — Current Release

• Mobile Financial Tables — wide financial tables now display as stacked, labeled cards on phones, including the Pay Application G703 Schedule of Values and Change Order line items.
• Frozen Gantt Task Column — the Gantt task-name column now stays frozen while you scroll the timeline sideways.
• Server-Enforced Idle Logout — sessions time out server-side after inactivity and return you automatically to the page you were on after re-login.
• Pay Application Stepper — a readable, scrollable Pay Application workflow stepper.
• Mobile Polish — general alignment and scroll improvements across all modules on small screens.

v0.10.0 — Prior Release

• Offline-First Sync — full offline support with local change queue; amber banner shows pending sync count.
• 3-Way Merge Conflict Resolution — structured conflict resolution modal when two offline users edit the same field; preserves your work and the server version for comparison.
• Session Restore — after session expiry and re-login, users are returned automatically to the page they were on.
• User Guide — this comprehensive in-app user guide (all 22 sections).
• Logo Consistency — unified logo treatment across sidebar, header, PDFs, and login screen.
• QuickBooks Online Integration — admin-level sync of Vendors, Cost Codes, Pay Applications, and Vendor Invoices to QBO via OAuth 2.0; one-click or bulk sync from System Settings.

v0.9.x — Prior Releases

• QMS Module — NCR tracking, daily QC checklists, and formal inspection records.
• Daily Safety Module — daily safety reports, JHA management, OSHA 300A log.
• G702/G703 PDF Export — AIA-formatted pay application PDF generation with full G703 continuation sheet.
• CO Locking — Change Orders automatically lock when included in a Pay Application to prevent retroactive edits.
• Optimistic Locking — version-based conflict detection prevents silent overwrites when multiple users edit the same record concurrently.
• Activity Log — append-only audit trail for all create/edit/status-change actions with user attribution.
• Passkey Gate on System Settings — re-authentication required to access admin settings, even within an active session.
• Navigation Performance Label — performance indicator in sidebar navigation for administrators.

23 QuickBooks Online Integration

The QuickBooks Online (QBO) integration lets administrators push key financial records from MLP CMS directly into QuickBooks Online — eliminating double-entry and keeping your accounting system in sync.

Prerequisites

• Administrator role in MLP CMS
• An active QuickBooks Online account (any tier: Simple Start, Essentials, Plus, or Advanced)
• An Intuit Developer app with a Client ID and Client Secret

Step 1 — Create an Intuit Developer App

1. Go to developer.intuit.com and sign in with your QuickBooks credentials.
2. Click Create an app → select QuickBooks Online and Payments.
3. Under Keys & OAuth, add the Redirect URI exactly as: http://localhost:3000/api/qbo/callback
4. Copy the Client ID and Client Secret — you will need them in the next step.

Step 2 — Add Credentials to the Server

1. On the server machine, open the .env file in the application root directory.
2. Add or update these two lines:
   QBO_CLIENT_ID=<your-client-id>
QBO_CLIENT_SECRET=<your-client-secret>
3. Restart the application: pm2 restart mlp-cms

Step 3 — Connect to QuickBooks Online

1. In MLP CMS, click the gear icon in the sidebar to open System Settings and complete the passkey prompt.
2. Scroll to the QuickBooks Online Integration panel.
3. Click Connect to QuickBooks Online. You will be redirected to Intuit's authorization page.
4. Sign in with your QBO account credentials and click Authorize.
5. You are returned to MLP CMS. The panel now displays Connected along with your QBO company name.

Syncing Data

Once connected, the QBO panel provides sync controls for four record types:

Each sync button shows the last sync timestamp and record count after completion. To push all four types at once, click Sync Everything Now.

Disconnecting

To revoke access, click Disconnect in the QBO panel. This removes the stored OAuth tokens from the server. Your QuickBooks data is not affected — only the connection is removed. You can reconnect at any time by repeating Step 3.

Important Notes

• One-way sync: Data flows from MLP CMS → QuickBooks only. Changes made directly in QuickBooks are not pulled back into MLP CMS.
• Duplicate prevention: Syncs use find-or-create logic. Records that already exist in QBO (matched by name or number) are skipped — no duplicates are created.
• Automatic token refresh: QBO access tokens expire after 1 hour. The system refreshes them automatically using the stored refresh token, which is valid for 100 days. No manual action is required unless you see an authentication error.
• Authentication errors: If a sync fails with an auth error, click Disconnect and reconnect to re-authorize. This is typically needed if the refresh token has expired (after 100 days of no syncs) or if the QBO app credentials were rotated.
• Sandbox vs Production: The integration defaults to QBO production. If you need to test against a QBO sandbox account, contact your system administrator to set QBO_ENVIRONMENT=sandbox in the server .env.