Integrations Error Revamp: Create NetSuite integration troubleshooting docs#84201
Integrations Error Revamp: Create NetSuite integration troubleshooting docs#84201stephanieelliott wants to merge 2 commits intomainfrom
Conversation
HelpDot Documentation ReviewOverall AssessmentThis PR adds 174 new Markdown files (87 for Expensify Classic, 87 for New Expensify) documenting NetSuite integration error codes across five subcategories: Authentication-and-Login-errors, Connection-errors, Export-Errors, Sync-Errors, and a NetSuite-FAQ.md. The documentation is well-structured, follows a consistent template, and provides genuinely useful troubleshooting guidance for Workspace Admins. The scope and effort here are substantial. Below are areas of strength and areas that would benefit from revision. Scores Summary
Key FindingsDuplicate Files Across Categories (Critical) Multiple error codes appear in more than one subcategory within the same product. For example, under Expensify Classic:
The same pattern repeats in New Expensify. While the content between duplicates is slightly adapted (Classic uses Settings-based nav, New Expensify uses tab-based nav with web/mobile instructions), having the same error code documented in three separate category folders creates maintenance risk and potential confusion. A single canonical location per error code per product is recommended, with redirects or cross-references if needed. This accounts for roughly 36+ files that may be duplicates. Heading Hierarchy Violation (Important) Every file starts with Example from every file: Error Messages Not Formatted as Distinct Elements Error messages are presented as plain paragraphs: For both readability and AI parsing, these should use blockquotes or code blocks: Positive Aspects
Minor Issues
Recommendations
Files Reviewed
Total: 174 new files (~17,400 lines of additions) Note: Due to the scale of this PR (174 files), inline comments were not posted. The patterns identified above apply uniformly across all files and are best addressed through bulk find-and-replace operations. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
...ic/connections/netsuite/Troubleshooting/Authentication-and-Login-errors/NS0109-Sync-Error.md
Show resolved
Hide resolved
| - Location | ||
| - Class | ||
| 9. Uncheck both: | ||
| - **Show** |
There was a problem hiding this comment.
AI Readiness / Heading level violation: This # (H1) heading should be ## (H2). Only the article title at the top should use H1. All body section headings must use H2 or lower.
This same issue appears in multiple files across the PR -- there are at least 17 occurrences of # How to Fix... used as body section headings, plus # Additional Steps..., # General Fix..., and # Why the NS0885.... All of these should be changed to ##.
Affected files include NS0005, NS0056, NS0295, NS0510, NS0521, NS0581, NS0831, NS0885, NS0196 (both classic and new-expensify versions where applicable).
| - **Show** | |
| ## How to Fix NS0005 for Vendor Bill Exports |
.../expensify-classic/connections/netsuite/Troubleshooting/Export-Errors/NS0005-Export-Error.md
Show resolved
Hide resolved
|
|
||
| --- | ||
|
|
||
| # Why Is My Report Not Automatically Exporting to NetSuite? |
There was a problem hiding this comment.
AI Readiness / Heading level violation: FAQ questions should use ## (H2) subheadings, not # (H1). Only the page title ("# NetSuite FAQ" on line 8) should use H1. All 11 FAQ questions in this file use # and need to be changed to ##. Their sub-sections (currently ##) should become ###.
This is a structural issue that affects AI parsing and document hierarchy. The classic version of this FAQ file (expensify-classic/...NetSuite-FAQ.md) correctly uses ## for questions -- this new-expensify version should follow the same pattern.
| # Why Is My Report Not Automatically Exporting to NetSuite? | |
| ## Why Is My Report Not Automatically Exporting to NetSuite? |
docs/articles/expensify-classic/connections/netsuite/Troubleshooting/NetSuite-FAQ.md
Outdated
Show resolved
Hide resolved
| | Classes | View | | ||
| | Currency | View | | ||
| | Custom Record Entries | View | | ||
| | Customers | View | |
There was a problem hiding this comment.
AI Readiness / Heading level violation: Avoid using #### (H4) headings. HelpDot articles should use # and ## only (with ### being acceptable for sub-steps). Using #### creates too-deep nesting that degrades AI readability and scannability. Consider restructuring this as a bold label or a ### heading instead.
This also applies to the #### Setup Permissions heading on line 95.
| | Customers | View | | |
| ### List Permissions |
|
|
||
| If you see the error: | ||
|
|
||
| NS0029: Unable to export this report due to an error. |
There was a problem hiding this comment.
Readability violation: Error messages should be formatted distinctly from surrounding prose to improve scannability. Consider using a blockquote (>) or code block so readers can quickly identify the exact error text. This pattern is used across all 97 files and would benefit from consistent formatting.
For example:
| NS0029: Unable to export this report due to an error. | |
| > NS0029: Unable to export this report due to an error. |
| This means there is a connection issue between Expensify and NetSuite preventing the report from exporting. | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
Readability / Markdown formatting note: Horizontal rules (---) are used heavily throughout these files (1,252 instances across 97 files) as section dividers between every heading. In well-structured markdown, headings themselves serve as visual section breaks. The excessive use of --- adds visual clutter without improving navigation, especially for AI parsers and screen readers.
Consider removing the --- dividers between sections. They are only needed between the YAML frontmatter and content, or to indicate a major thematic shift (not between every heading).
| 2. Go to **Customization > Forms > Transaction Forms**. | ||
| 3. Click **Edit** next to the vendor bill form marked as preferred. | ||
| 4. Go to **Screen Fields > Main**. | ||
| 5. Locate **Department**, **Location**, and **Class**. |
There was a problem hiding this comment.
Expensify style violation: In Expensify, use "Confirm" instead of "Save" at the end of flows. This line says Click **Save** but should say Click **Confirm**.
Note: When referencing NetSuite's own UI (e.g., saving a form inside NetSuite), "Save" is appropriate. But this applies to the Expensify-side instructions throughout the new-expensify files as well.
| 5. Locate **Department**, **Location**, and **Class**. | |
| 7. Click **Confirm**. |
|
|
||
| ## Option One: Update the Expensify Connect Bundle | ||
|
|
||
| 1. Log in to **NetSuite** as an Administrator. |
There was a problem hiding this comment.
AI Readiness / Heading level violation: This # (H1) should be ## (H2). Only the article title should use H1.
| 1. Log in to **NetSuite** as an Administrator. | |
| ## How to Fix the NS0510 Export Error |
|
|
||
| --- | ||
|
|
||
| # Additional Steps for Non-OneWorld Users |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # Additional Steps for Non-OneWorld Users should be ## Additional Steps for Non-OneWorld Users. Only the article title should use H1.
| # Additional Steps for Non-OneWorld Users | |
| ## Additional Steps for Non-OneWorld Users |
|
|
||
| # Why the NS0885 Export Error Happens in NetSuite | ||
|
|
||
| The NS0885 error occurs when: |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # Why the NS0885 Export Error Happens in NetSuite should be ##. Only the article title should use H1. This file has three H1 headings in the body (lines 22, 34, and 95) that all need to be changed to H2.
| The NS0885 error occurs when: | |
| ## Why the NS0885 Export Error Happens in NetSuite |
|
|
||
| --- | ||
|
|
||
| # Fix the NS0885 Export Error for Reimbursable Exports |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # Fix the NS0885 Export Error for Reimbursable Exports should be ##. Only the article title should use H1. This file has two H1 body headings (this line and the non-reimbursable section) that need to change to H2.
| # Fix the NS0885 Export Error for Reimbursable Exports | |
| ## Fix the NS0885 Export Error for Reimbursable Exports |
|
|
||
| --- | ||
|
|
||
| # How to Fix the NS0521 Sync Error in OneWorld Accounts |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # How to Fix... should be ## How to Fix.... Only the article title should use H1. This applies to both OneWorld (this line) and Non-OneWorld (line 74) fix headings.
| # How to Fix the NS0521 Sync Error in OneWorld Accounts | |
| ## How to Fix the NS0521 Sync Error in OneWorld Accounts |
|
|
||
| --- | ||
|
|
||
| # Why Is My Report Exporting as Accounting Approved Instead of Paid in Full? |
There was a problem hiding this comment.
Readability violation / Duplicate content: This question ("Why Is My Report Exporting as Accounting Approved Instead of Paid in Full?") is a duplicate of the question on line 89 ("Why Are Reports Exporting as 'Accounting Approved' Instead of 'Paid in Full'?"). The answer on line 193 even says "Follow the steps above under the Accounting Approved vs Paid in Full section," confirming this is redundant.
Remove this duplicate section entirely to avoid confusion and improve scannability.
| --- | ||
|
|
||
| # General Fix for Most NS0056 Errors | ||
|
|
There was a problem hiding this comment.
AI Readiness / Heading level violation: # General Fix for Most NS0056 Errors should be ##. Only the article title should use H1.
Additionally, the ### Step One: and ### Step Two: headings directly under this # create an inconsistent hierarchy (jumping from H1 to H3, skipping H2). If this heading becomes ##, then the steps should use ### which would then be correct.
| ## General Fix for Most NS0056 Errors |
|
|
||
| --- | ||
|
|
||
| # Additional Fixes by Element |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # Additional Fixes by Element should be ##.
| # Additional Fixes by Element | |
| ## Additional Fixes by Element |
|
|
||
| --- | ||
|
|
||
| # Additional Fixes by Element |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # Additional Fixes by Element should be ##. Only the article title should use H1.
| # Additional Fixes by Element | |
| ## Additional Fixes by Element |
|
|
||
| --- | ||
|
|
||
| ## Confirm the NetSuite Credentials |
There was a problem hiding this comment.
AI Readiness / Heading hierarchy issue: "Confirm the NetSuite Credentials", "Generate a New NetSuite Access Token", "Refresh the NetSuite Connection", and "Contact Concierge" are all sub-steps of "## How to Fix the NS0109 Sync Error" (line 38), but they use the same ## heading level. This creates a flat structure where AI parsers cannot determine these are child steps of the fix section.
These should be ### (H3) headings to maintain proper hierarchy under the ## How to Fix parent heading. This pattern appears in many of the new-expensify Sync-Error and Connection-Error files, which use flat ## for everything instead of proper ## > ### nesting.
Compare with the expensify-classic version of the same file, which correctly uses ### Step One:, ### Step Two:, ### Step Three: under ## How to Fix.
| ## Confirm the NetSuite Credentials | |
| ### Confirm the NetSuite Credentials |
|
|
||
| --- | ||
|
|
||
| # Additional Steps for Expensify Card Journal Entries |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # Additional Steps for Expensify Card Journal Entries should be ##. Only the article title should use H1.
| # Additional Steps for Expensify Card Journal Entries | |
| ## Additional Steps for Expensify Card Journal Entries |
|
|
||
| --- | ||
|
|
||
| # How to Fix the NS0196 Sync Error |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # How to Fix the NS0196 Sync Error should be ##. Only the article title should use H1.
| # How to Fix the NS0196 Sync Error | |
| ## How to Fix the NS0196 Sync Error |
|
|
||
| --- | ||
|
|
||
| # How to Fix NS0295 for Vendor Bill Exports |
There was a problem hiding this comment.
AI Readiness / Heading level violation: Both # How to Fix NS0295 for Vendor Bill Exports (this line) and # How to Fix NS0295 for Journal Entry or Expense Report Exports (line 61) should be ##. Only the article title should use H1.
| # How to Fix NS0295 for Vendor Bill Exports | |
| ## How to Fix NS0295 for Vendor Bill Exports |
| internalScope: Audience is Workspace Admins using the NetSuite integration. Covers fixing the NS0521 sync error caused by subsidiary permission configuration in OneWorld and Non-OneWorld accounts. Does not cover other NetSuite error codes. | ||
| --- | ||
|
|
||
| # NS0521 Sync Error in NetSuite Integration |
There was a problem hiding this comment.
Readability / Naming inconsistency: This file is named NS0521-Sync-Error.md but is located in the Export-Errors/ folder. This is confusing and could cause misclassification. Consider either:
- Moving this file to the
Sync-Errors/folder (where another NS0521-Sync-Error.md already exists), or - Renaming it to match the Export-Errors category if this is a distinct article about NS0521 in an export context
Additionally, this file has H1 body headings on lines 30 and 56 (# How to Fix NS0521 for OneWorld Accounts and # How to Fix NS0521 for Non-OneWorld Accounts) that should be ##.
| internalScope: Audience is Workspace Admins using the NetSuite integration. Covers resolving the NS0521 sync error caused by subsidiary permission configuration issues in OneWorld and Non-OneWorld NetSuite accounts. Does not cover token formatting or general login errors. | ||
| --- | ||
|
|
||
| # NS0521 Sync Error in NetSuite Integration |
There was a problem hiding this comment.
Readability / Naming inconsistency: Same issue as the classic version -- this file is named NS0521-Sync-Error.md but located in the Export-Errors/ directory. A Sync-Error file should not live under Export-Errors. Consider moving it to Sync-Errors/ or renaming it if this covers a distinct export-related context.
|
|
||
| --- | ||
|
|
||
| # How to Fix NS0581 for Invoice Exports |
There was a problem hiding this comment.
AI Readiness / Heading level violation: Both # How to Fix NS0581 for Invoice Exports (this line) and # How to Fix NS0581 for Expense Report Exports (line 63) should be ##. Only the article title should use H1.
| # How to Fix NS0581 for Invoice Exports | |
| ## How to Fix NS0581 for Invoice Exports |
|
|
||
| --- | ||
|
|
||
| # How to Fix the NS0831 Export Error |
There was a problem hiding this comment.
AI Readiness / Heading level violation: # How to Fix the NS0831 Export Error should be ##. Only the article title should use H1.
| # How to Fix the NS0831 Export Error | |
| ## How to Fix the NS0831 Export Error |
|
|
||
| --- | ||
|
|
||
| ## Confirm the Role Assigned to the NetSuite Access Token |
There was a problem hiding this comment.
AI Readiness / Heading hierarchy issue: This ## heading (and the following fix-step headings: "Assign the Expensify Integration Role", "Review Global Permissions", "Sync the Workspace") are sub-steps of ## How to Fix the NS0565 Sync Error on line 37. They should use ### to reflect the parent-child relationship.
This flat ## pattern for fix sub-steps is systemic across most new-expensify Sync-Error and Connection-Error files (NS0109, NS0123, NS0318, NS0384, NS0565, NS0739, NS0942, etc.). Compare with the expensify-classic versions, which correctly use ### Step One:, ### Step Two:, etc. under ## How to Fix.
| ## Confirm the Role Assigned to the NetSuite Access Token | |
| ### Confirm the Role Assigned to the NetSuite Access Token |
…ooting/NetSuite-FAQ.md Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
| 6. Open the **Advanced** tab. | ||
| 7. Locate the **Sync Reimbursed Reports** setting. | ||
| 8. Select a valid **Accounts Payable** account from the dropdown. | ||
| 9. Click **Save**. |
There was a problem hiding this comment.
Expensify style violation: Use "Confirm" instead of "Save" when the action completes a flow in Expensify. This instruction is part of the Expensify Workspace settings flow (selecting an A/P account), so the button label should be "Confirm."
This same issue applies to line 63 in this file. See also the broader note on the NS0109 Authentication file -- this pattern affects hundreds of instances across the PR.
| 9. Click **Save**. | |
| 9. Click **Confirm**. |
| 3. Click **Company Cards**. | ||
| 4. Click **Edit Export** for the affected card. | ||
| 5. Confirm the correct NetSuite account is selected. | ||
| 6. Click **Save**. |
There was a problem hiding this comment.
Expensify style violation: Use "Confirm" instead of "Save" when completing Expensify UI flows. This line is in an Expensify Domain settings context.
This also applies to lines 210 and 217 in this file (NetSuite OneWorld/Non-OneWorld payable account flows -- though those are in NetSuite's own UI where "Save" may be correct).
| 6. Click **Save**. | |
| 6. Click **Confirm**. |
1 participant
Master project issue https://github.com/Expensify/Expensify/issues/469226
Breaking main PR into smaller batches: #83106
Creates .MD files for NetSuite integration error messages