[No QA] Add Sage Intacct troubleshooting docs (New Expensify)#84818
[No QA] Add Sage Intacct troubleshooting docs (New Expensify)#84818stephanieelliott merged 1 commit intomainfrom
Conversation
HelpDot Documentation ReviewOverall AssessmentThis PR adds 42 new Markdown documentation files covering Sage Intacct troubleshooting error codes for New Expensify. The files are organized into five subcategories: Authentication-and-Login-errors, Connection-errors, Export-Errors, Sync-Errors, and a Sage-Intacct-FAQ. The documentation is well-structured, consistent, and clearly written. Each article follows a uniform pattern: error description, root causes, resolution steps, and FAQ. There are several structural and organizational issues worth addressing, but the overall quality of the writing and technical guidance is strong. Scores Summary
Key FindingsStructural Issues
Formatting Issues
Positive Aspects
Content Concerns
Recommendations
Files Reviewed
Note: This review assesses only the proposed changes (all new file additions). No inline comments were posted as the issues are systemic patterns affecting all files rather than isolated line-level concerns. |
github-actions
bot
changed the title
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| --- | ||
|
|
||
| # How to Fix the INT245 Sync Error |
There was a problem hiding this comment.
Heading hierarchy violation (systemic -- affects ~38 of 42 files): # How to Fix uses an H1 heading, but H1 (#) should be reserved for the article title only. All subsequent section headings should use ## (H2) or lower. This same issue occurs in nearly every file in this PR. The two files that do it correctly are Authentication-and-Login-errors/INT122-Sync-Error.md and Authentication-and-Login-errors/INT176-Export-Error.md, which use ## How to Fix.
| # How to Fix the INT245 Sync Error | |
| ## How to Fix the INT245 Sync Error |
|
|
||
| --- | ||
|
|
||
| # How to Fix the INT009 Export Error |
There was a problem hiding this comment.
Heading hierarchy violation: # How to Fix should be ## How to Fix -- H1 is reserved for the article title. This applies to this file and all other Export-Errors files in this PR (INT012, INT028, INT035, INT043, INT054, INT073, INT083, INT084, INT088, INT149, INT176, INT194, INT205, INT225, INT304, INT446, INT459, INT480, INT503, INT592, INT664, INT680, INT771, INT860, INT907, INT993).
| # How to Fix the INT009 Export Error | |
| ## How to Fix the INT009 Export Error |
|
|
||
| --- | ||
|
|
||
| # How to Fix the INT068 Sync Error |
There was a problem hiding this comment.
Heading hierarchy violation: # How to Fix should be ## How to Fix -- H1 is reserved for the article title. This applies to this file and all other Sync-Errors files (INT122, INT245, INT402, INT498, INT576, INT907).
| # How to Fix the INT068 Sync Error | |
| ## How to Fix the INT068 Sync Error |
|
|
||
| --- | ||
|
|
||
| # Additional Troubleshooting for Closed Periods |
There was a problem hiding this comment.
Heading hierarchy violation: # Additional Troubleshooting should be ## Additional Troubleshooting for Closed Periods -- H1 is reserved for the article title only.
| # Additional Troubleshooting for Closed Periods | |
| ## Additional Troubleshooting for Closed Periods |
|
|
||
| --- | ||
|
|
||
| # How to Fix the INT245 Sync Error |
There was a problem hiding this comment.
Heading hierarchy violation: # How to Fix should be ## How to Fix -- H1 is reserved for the article title.
| # How to Fix the INT245 Sync Error | |
| ## How to Fix the INT245 Sync Error |
|
|
||
| --- | ||
|
|
||
| # How to Fix the INT498 Sync Error |
There was a problem hiding this comment.
Heading hierarchy violation: # How to Fix should be ## How to Fix -- H1 is reserved for the article title.
| # How to Fix the INT498 Sync Error | |
| ## How to Fix the INT498 Sync Error |
| @@ -0,0 +1,69 @@ | |||
| --- | |||
There was a problem hiding this comment.
Duplicate content issue: This file is byte-for-byte identical to Connection-errors/INT907-Error.md and Export-Errors/INT907-Error.md (all share git blob hash 483d7d248f3e7). The Sync-Errors/INT907-Error.md file is a slightly different version. Having the same article duplicated across 3-4 categories creates maintenance problems and confuses AI retrieval systems. Consider keeping INT907 in only one canonical location and linking to it from other categories, or differentiating the content to address category-specific guidance.
| @@ -0,0 +1,109 @@ | |||
| --- | |||
There was a problem hiding this comment.
Duplicate/near-duplicate content issue: This file is nearly identical to Authentication-and-Login-errors/INT245-Sync-Error.md and Sync-Errors/INT245-Sync-Error.md. The same INT245 error article exists in 3 different category folders with only minor wording differences. This creates confusion for both readers navigating the docs and for AI systems retrieving content. Consider placing this article in one canonical location (likely Sync-Errors/ since the error title says "Sync Error") and removing the duplicates.
| @@ -0,0 +1,79 @@ | |||
| --- | |||
There was a problem hiding this comment.
AI Readiness / duplicate content concern: INT176 is an "Export Error" but is placed in the Authentication-and-Login-errors/ category. A near-duplicate also exists at Export-Errors/INT176-Export-Error.md. This same issue applies to several other files:
INT122-Sync-Error.mdappears in bothAuthentication-and-Login-errors/andSync-Errors/INT498-Sync-Error.mdappears in bothAuthentication-and-Login-errors/andSync-Errors/INT245-Sync-Error.mdappears inAuthentication-and-Login-errors/,Connection-errors/, andSync-Errors/INT907-Error.mdappears in all four categories
Consider placing each error code in its primary category only. Having the same error in multiple folders creates confusion for search, AI retrieval, and ongoing maintenance.
|
|
||
| If you see the error: | ||
|
|
||
| INT122 Sync Error: Authentication error during sync. Please reenter Sage Intacct admin credentials and attempt sync again. |
There was a problem hiding this comment.
Readability / AI Readiness (systemic -- affects all 42 files): The error message text is displayed as a plain paragraph, making it visually indistinguishable from regular body text. Error messages should be formatted as a blockquote (>) or a code block to clearly separate them from instructional content. This improves scannability for readers and helps AI systems identify the exact error string.
For example:
> INT122 Sync Error: Authentication error during sync. Please reenter Sage Intacct admin credentials and attempt sync again.This applies to all error message blocks across every file in this PR.
| 4. Click **Configure**. | ||
| 5. Open the **Export** tab. | ||
| 6. In the **Date** field, select **Exported Date**. | ||
| 7. Click **Save**. |
There was a problem hiding this comment.
Expensify style compliance: Per Expensify documentation standards, the button at the end of a configuration flow should be "Confirm" instead of "Save." This applies to steps completing Workspace configuration changes. The same issue appears in several other files where Workspace configuration steps end with "Click Save" or "Tap Save" (e.g., INT194, INT225, INT245 Auth/Connection/Sync versions, INT498 Auth version, and others). Note: Steps performed inside Sage Intacct's own UI correctly use "Save" since that is Sage Intacct's button label.
| - The error appears in the **report comments section** | ||
| - Automatic export remains paused until the error is resolved | ||
|
|
||
| ### How to Resolve Automatic Export Failures |
There was a problem hiding this comment.
FAQ structure violation: Per Expensify documentation standards, FAQ answers should be in plain text without additional sub-headings. The ### How to Resolve Automatic Export Failures sub-heading under the FAQ question creates unnecessary nesting. Instead, incorporate these steps directly into the answer text, or use a numbered list without a sub-heading. The same applies to ### How to Resolve Manual Export Issues on line 37.
| --- | ||
| title: Sage Intacct FAQ | ||
| description: Learn why reports may fail to export to Sage Intacct, how to manually export reports, and how to disconnect the Sage Intacct integration. | ||
| keywords: Sage Intacct export FAQ, automatic export failure, manual export Sage Intacct, report not exporting, disconnect Sage Intacct integration |
There was a problem hiding this comment.
AI Readiness: The keywords field is missing "Workspace Admin" which is included in all other files in this PR. Adding the role term improves discoverability when AI systems filter by audience.
| keywords: Sage Intacct export FAQ, automatic export failure, manual export Sage Intacct, report not exporting, disconnect Sage Intacct integration | |
| keywords: Sage Intacct export FAQ, automatic export failure, manual export Sage Intacct, report not exporting, disconnect Sage Intacct integration, Workspace Admin |
|
|
||
| If you need to disconnect the integration: | ||
|
|
||
| 1. Go to **Workspace > [Workspace Name] > Accounting**. |
There was a problem hiding this comment.
Readability / consistency issue: The navigation path here uses Workspace > [Workspace Name] > Accounting which is inconsistent with the pattern used in all other files in this PR, which consistently use Settings > Workspaces > [Workspace Name] > Accounting or the web/mobile-specific instructions. This inconsistency could confuse readers.
| 1. Go to **Workspace > [Workspace Name] > Accounting**. | |
| 1. Go to **Settings > Workspaces > [Workspace Name] > Accounting**. |
|
|
||
| ## Enable and Map Billable Expenses in the Workspace | ||
|
|
||
| On web: |
There was a problem hiding this comment.
Readability / consistency issue: This file provides separate "On web" and "On mobile" instructions, but the vast majority of files in this PR (about 38 of 42) use only generic "Click" instructions without platform-specific separation. This creates inconsistency across the documentation set. Consider either: (a) adding web/mobile instructions to all files for consistency, or (b) removing the web/mobile split here and using the generic approach to match the other files. The same inconsistency applies to INT035, INT225, and Auth/INT498.
| - The user has the required module permissions. | ||
| 4. If the password was changed, update it in the Workspace connection settings. | ||
|
|
||
| Save any changes. |
There was a problem hiding this comment.
Readability issue: "Save any changes." appears as a standalone sentence outside the numbered list, which breaks the step flow and is easy to overlook. Consider incorporating it as a numbered step (e.g., 5. Click **Save**.) for better scannability and consistency with the formatting in other sections of this file.
| 4. Scroll to **Web Services Authorizations**. | ||
| 5. Add **expensify** as a **Sender ID**. | ||
|
|
||
| Important: |
There was a problem hiding this comment.
Readability issue: "Important:" as a standalone plain-text label is easy to miss and not a standard markdown callout. Consider using a blockquote or bold formatting to make it stand out, for example:
> **Important**: The Sender ID must be entered as **expensify** (all lowercase). Do not use uppercase letters or spaces.This consolidates the three bullet points below into a more scannable callout.
|
|
||
| ## Update Permissions for the xml_gateway User | ||
|
|
||
| ### If Using User-Based Permissions |
There was a problem hiding this comment.
Heading hierarchy / AI Readiness: This section has ### If Using User-Based Permissions and ### If Using Role-Based Permissions nested under ## Update Permissions. Combined with the # How to Fix issue (which should be ##), correcting the hierarchy would push these to H4 (####), which is too deep for good AI readability. Consider flattening the structure -- for example, make "Update Permissions for the xml_gateway User (User-Based)" and "Update Permissions for the xml_gateway User (Role-Based)" both ## level sections, eliminating the nesting layer.
|
|
||
| If you do not use Sage Intacct’s approval workflow, disable it. | ||
|
|
||
| ### Disable Expense Report Approval in Sage Intacct |
There was a problem hiding this comment.
Heading hierarchy / AI Readiness: The ### sub-headings here (line 44 and line 66) are nested under ## If You Are Not/Are Using... which is itself under # How to Fix (which should be ##). After fixing the root heading level, the hierarchy becomes ## > ### > #### which is too deep. Consider flattening -- for example, use ## Disable Expense Report Approval in Sage Intacct and ## Configure a Valid First Approver in Sage Intacct as direct H2 sections. This same cascading nesting pattern also appears in INT245 (Auth, Connection, and Sync versions).
|
|
||
| If you see the error: | ||
|
|
||
| INT664 Export Error: Sage Intacct couldn’t find a vendor record for the report submitter. Verify a vendor record exists and the vendor email exactly matches the submitter’s Expensify email exactly, including capitalization. |
There was a problem hiding this comment.
Readability issue: The word "exactly" appears twice in this error message text: "...exactly matches the submitter's Expensify email exactly, including capitalization." The second "exactly" is redundant. (Note: If this is the verbatim error message from Sage Intacct, the inline description on line 14 could clarify the wording instead.)
|
|
||
| The INT088 error typically occurs when: | ||
|
|
||
| - The **Cash Management** subledger is closed. |
There was a problem hiding this comment.
Readability (systemic -- affects all files): Horizontal rules (---) are used between every section in every file, creating visual clutter. Markdown headings already provide clear section separation. The horizontal rules between H2 sections are redundant and add noise rather than clarity. Consider removing them, or reserving --- only for major logical divisions (e.g., between the main content and the FAQ section). This pattern is consistent across all 42 files in this PR.
| 4. Click **Subscriptions**. | ||
| 5. Confirm the following permissions are enabled: | ||
|
|
||
| - **Administration:** All |
There was a problem hiding this comment.
Readability issue: The bullet list of permissions breaks the numbered list flow. After step 5, the bullets interrupt the sequence, and step 6 (line 58) resumes numbering. In some markdown renderers, this can cause step 6 to restart at "1." instead of continuing from "6." Consider indenting the bullet list under step 5, or converting the permissions to a sub-list within step 5 using proper indentation. This same pattern also appears in the INT245 variants (Auth, Connection, and Sync).
| ### How to Resolve Manual Export Issues | ||
|
|
||
| 1. If the report is in **Draft**, submit the report. | ||
| 2. If the report is **Outstanding**, have an approver approve it. |
There was a problem hiding this comment.
Terminology concern: "Outstanding" may not be a standard report status in New Expensify. Typical New Expensify report statuses include Processing (submitted, awaiting approval). Consider verifying this status name matches the current New Expensify UI, or replacing it with the correct status term.
|
|
||
| ## Why Am I Unable to Manually Export a Report to Sage Intacct? | ||
|
|
||
| Only reports in **Approved**, **Done**, or **Paid** status can be exported. |
There was a problem hiding this comment.
Terminology concern: "Done" is not a standard report status in New Expensify. Please verify the correct exportable statuses match the current New Expensify UI. Standard statuses that allow export are typically Approved and Paid (or Reimbursed).
- Root: Configure, Connect, Troubleshooting. - Troubleshooting: Auth, Connection, Export, Sync errors, FAQ. - Hub pages already exist on main. Part of Integration Errors Revamp (splitting PR #83106).
stephanieelliott
force-pushed
the
helpsite-sage-intacct-new-expensify
branch
from
60656d1 to
b341eda
Compare
|
@stephanieelliott looks like this was merged without a test passing. Please add a note explaining why this was done and remove the |
|
🚀 Deployed to staging by https://github.com/stephanieelliott in version: 9.3.36-0 🚀
|
|
🚀 Deployed to production by https://github.com/luacmartins in version: 9.3.36-10 🚀
|
3 participants
Master project issue https://github.com/Expensify/Expensify/issues/469226
Breaking main PR into smaller batches: #83106
Creates .MD files for Sage integration error messages (New Expensify)