[No QA] Add New Expensify NetSuite troubleshooting docs - #84305
[No QA] Add New Expensify NetSuite troubleshooting docs#84305stephanieelliott wants to merge 2 commits into
Conversation
- Authentication-and-Login-errors: 9 articles - Connection-errors: 7 articles - Export-Errors: 57 articles (incl. NS0521-Sync-Error in Export-Errors) - Sync-Errors: 16 articles - NetSuite-FAQ.md Part of Integration Errors Revamp (splitting PR #83106). Made-with: Cursor
HelpDot Documentation ReviewOverall AssessmentThis PR adds 87 new NetSuite troubleshooting documentation files covering authentication errors, connection errors, export errors, sync errors, and a general FAQ. The articles follow a remarkably consistent template and are well-structured for a Workspace Admin audience. The writing is clear and actionable. However, there are several systematic issues -- most notably a significant number of duplicate/near-duplicate files across categories, a heading hierarchy violation in the FAQ sections, and error messages displayed as plain text rather than visually distinguished blocks. Scores Summary
Key FindingsCritical: Extensive File Duplication Across Categories 10 error codes have duplicate or near-duplicate files placed in multiple category folders. This is the most significant issue in the PR:
The duplicated files are either identical or contain only minor phrasing differences (e.g., "system overload" vs. "overloading accounts", "people" vs. "members"). This creates maintenance burden and AI retrieval confusion. Each error code should live in one canonical location, with cross-references from other categories if needed. Heading Hierarchy Violation All 86 individual error articles use Additionally, the NS0885-Export-Error.md file uses H1 headings for section breaks within the article body ( The NS0521-Sync-Error.md in Sync-Errors similarly uses H1 for section titles ( Error Messages Not Visually Distinguished Error messages are displayed as plain paragraph text. For example: These would benefit from blockquote formatting ( Positive Aspects
NetSuite-FAQ.md Style Inconsistencies The NetSuite-FAQ.md file deviates from the patterns used in the individual error articles:
Recommendations
Files Reviewed
Total: 87 files, of which approximately 24 are duplicates of content found elsewhere in this PR. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
|
|
||
| --- | ||
|
|
||
| # Why Is My Report Not Automatically Exporting to NetSuite? |
There was a problem hiding this comment.
Heading level violation (AI Readiness): FAQ questions should use ## (H2) subheadings, not # (H1). Per HelpDot standards, # FAQ is the section heading, and individual questions beneath it should be ##. This applies to all FAQ questions in this file (lines 12, 30, 42, 57, 72, 82, 120, 143, 166, 183, 194).
| # Why Is My Report Not Automatically Exporting to NetSuite? | |
| ## Why Is My Report Not Automatically Exporting to NetSuite? |
| 4. A Workspace Admin can manually export the report once fixed. | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
Heading level violation: This FAQ question uses # (H1) but should be ## (H2) per HelpDot FAQ structure rules.
| ## Why Am I Unable to Manually Export a Report to NetSuite? |
| If the report is in **Draft**, selecting Export may load an empty screen. | ||
|
|
||
| ## How to Resolve Manual Export Issues | ||
|
|
There was a problem hiding this comment.
Heading level violation: This FAQ question uses # (H1) but should be ## (H2).
| ## How Do I Disconnect the NetSuite Connection? |
| 2. Select your Workspace. | ||
| 3. Select **Accounting**. | ||
| 4. Click the **three-dot icon** next to the NetSuite connection. | ||
| 5. Click **Disconnect**. |
There was a problem hiding this comment.
Heading level violation: This FAQ question uses # (H1) but should be ## (H2). The subsection "How to Fix Field Permission Errors" should then be ###.
| 5. Click **Disconnect**. | |
| ## Why Am I Seeing "You Do Not Have Permissions to Set a Value for Element..." Errors? |
|
|
||
| 1. In NetSuite, go to **Customization > Forms > Transaction Forms**. | ||
| 2. Edit the preferred export form. | ||
| 3. Locate the field mentioned in the error. |
There was a problem hiding this comment.
Heading level violation: Same pattern -- # should be ## for FAQ questions.
| 3. Locate the field mentioned in the error. | |
| ## What If I've Made All Changes and Still See the Error? |
| # What If I’ve Made All Changes and Still See the Error? | ||
|
|
||
| If errors persist: | ||
|
|
There was a problem hiding this comment.
Heading level violation: Same pattern -- # should be ##.
| ## Why Are Reports Exporting as "Accounting Approved" Instead of "Paid in Full"? |
| - The **A/P Approval Account** matches the account used for bill payments. | ||
|
|
||
| To verify the A/P account: | ||
|
|
There was a problem hiding this comment.
Heading level violation: Same pattern -- # should be ##.
| ## Why Are Reports Exporting as Pending Approval? |
|
|
||
| ## For Expense Reports | ||
|
|
||
| 1. Go to **Setup > Company > Enable Features**. |
There was a problem hiding this comment.
Heading level violation: Same pattern -- # should be ##.
| 1. Go to **Setup > Company > Enable Features**. | |
| ## "Invite Employees & Set Approval Workflow" Is Enabled -- Why Aren't NetSuite Approvers Updating? |
| 4. Click the **three-dot icon**. | ||
| 5. Click **Sync now**. | ||
| 6. Re-import the employee and approver. | ||
|
|
There was a problem hiding this comment.
Heading level violation: Same pattern -- # should be ##.
| ## How to Change the Default Payable Account for Reimbursable Expenses in NetSuite |
| 4. Click **Save**. | ||
|
|
||
| ## For Non-OneWorld Accounts | ||
|
|
There was a problem hiding this comment.
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 82 ("Why Are Reports Exporting as 'Accounting Approved' Instead of 'Paid in Full'?"). Consider removing this duplicate section entirely, or merging the two into one comprehensive answer.
|
|
||
| This may happen due to: | ||
|
|
||
| - Missing classifications on the Bill Payment form |
There was a problem hiding this comment.
Heading level violation: Same pattern -- # should be ##.
| - Missing classifications on the Bill Payment form | |
| ## Why Is My Report Not Exporting Automatically Even After Fixing Errors? |
| internalScope: Audience is Workspace Admins and Domain Admins using the NetSuite integration. Covers common NetSuite export issues, approval settings, and connection troubleshooting. Does not cover individual NetSuite error codes. | ||
| --- | ||
|
|
||
| # NetSuite FAQ |
There was a problem hiding this comment.
FAQ structure violation: This file is structured as a FAQ but does not begin with a # FAQ heading followed by ## question subheadings. Per HelpDot standards, a FAQ page should use # FAQ as the top-level heading (or as the article title), and all questions should be ## subheadings. Currently, the title is "NetSuite FAQ" but the questions below all use # (H1) instead of ## (H2), creating multiple competing H1 headings in the document. Please restructure so the article title is the only H1, and all FAQ questions are H2.
| --- | ||
|
|
||
| # How to Fix the NS0521 Sync Error in OneWorld Accounts | ||
|
|
There was a problem hiding this comment.
Heading level violation (AI Readiness): Section headings within the article body should use ## (H2), not # (H1). The article already has an H1 title on line 8. Using additional H1 headings here and on line 62 breaks the document hierarchy and confuses both readers and AI systems parsing the structure.
This same issue also applies to line 62 (# How to Fix the NS0521 Sync Error in Non-OneWorld Accounts).
| ## How to Fix the NS0521 Sync Error in OneWorld Accounts |
| 4. Click the three-dot menu next to the NetSuite connection. | ||
| 5. Click **Sync Now**. | ||
|
|
||
| On mobile: |
There was a problem hiding this comment.
Heading level violation: This should be ## (H2), not # (H1). Only the article title and # FAQ should be H1.
| On mobile: | |
| ## How to Fix the NS0521 Sync Error in Non-OneWorld Accounts |
|
|
||
| This is a transaction form or classification configuration issue, not a token or subsidiary permission issue. | ||
|
|
||
| --- |
There was a problem hiding this comment.
Heading level violation (AI Readiness): This section heading uses # (H1) but should be ## (H2). The article title on line 8 is the only non-FAQ H1 heading allowed. This same issue applies to line 103 (# Fix the NS0885 Export Error for Non-Reimbursable Exports).
| --- | |
| ## Fix the NS0885 Export Error for Reimbursable Exports |
| Retry exporting the report. | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
Heading level violation: Same as above -- this should be ## (H2), not # (H1).
| ## Fix the NS0885 Export Error for Non-Reimbursable Exports |
| @@ -0,0 +1,118 @@ | |||
| --- | |||
There was a problem hiding this comment.
File naming inconsistency: This file is named NS0521-Sync-Error.md but is located in the Export-Errors/ directory. All other files in this directory are named NS####-Export-Error.md. This mismatch will confuse both readers and AI systems navigating the documentation structure. Consider either:
- Renaming the file to
NS0521-Export-Error.md(if this is an export error), or - Moving it to the
Sync-Errors/directory (if it is truly a sync error)
Note: The same NS0521 Sync Error article already exists in both Connection-errors/ and Sync-Errors/ directories, so having a third copy here seems unintentional.
| If you see the error: | ||
|
|
||
| NS0029 Export Error: Unable to export this report due to an error. | ||
|
|
There was a problem hiding this comment.
Markdown formatting (Readability): Error messages displayed to the user should be formatted in a blockquote or code block so they are visually distinct from the article's explanatory text. As plain text, the error message blends into the surrounding content. This pattern applies across all 90 files in this PR.
Suggested format:
| > NS0029 Export Error: Unable to export this report due to an error. |
| If you see the error: | ||
|
|
||
| NS0109 Sync Error: Failed to login to NetSuite. Please verify your admin credentials. | ||
|
|
There was a problem hiding this comment.
Markdown formatting (Readability): Same pattern as noted across all files -- the error message should be formatted as a blockquote or code block to visually distinguish it from explanatory text. This applies to all error message lines across all 90 files in this PR.
Suggested format:
| > NS0109 Sync Error: Failed to login to NetSuite. Please verify your admin credentials. |
| @@ -0,0 +1,93 @@ | |||
| --- | |||
There was a problem hiding this comment.
Duplicate content issue (AI Readiness): This file is identical to Authentication-and-Login-errors/NS0109-Sync-Error.md and also very similar to Sync-Errors/NS0109-Sync-Error.md. Having the same article duplicated across three directories creates confusion for both readers and AI systems.
The same duplication pattern applies to these error codes that appear in multiple folders:
- NS0109 (Authentication-and-Login-errors, Connection-errors, Sync-Errors)
- NS0123 (Authentication-and-Login-errors, Connection-errors, Sync-Errors)
- NS0521 (Connection-errors, Export-Errors, Sync-Errors)
- NS0565 (Authentication-and-Login-errors, Connection-errors, Sync-Errors)
- NS0593 (Authentication-and-Login-errors, Connection-errors, Sync-Errors)
- NS0739 (Authentication-and-Login-errors, Connection-errors, Sync-Errors)
- NS0942 (Authentication-and-Login-errors, Connection-errors, Sync-Errors)
Consider either: (1) keeping each error code in only one canonical location and linking from other categories, or (2) differentiating the content per category so each copy adds unique value.
|
|
||
| Follow the steps below to resolve the issue. | ||
|
|
||
| --- |
There was a problem hiding this comment.
Heading level violation (AI Readiness): The section heading ## Update the Expensify Connect Bundle in NetSuite is at ## (H2) level, which is correct. However, on line 42, the --- horizontal rule followed by the ## Update the Expensify Connect Bundle heading creates an inconsistency -- the preceding "How to Fix" section on line 38 uses ##, making this a sibling section rather than a child of the "How to Fix" section.
More importantly, on line 81, the ## Update NetSuite Role Token Permissions heading is also at H2 level, which is correct. But the structure would benefit from the "How to Fix" heading being the parent and the two resolution approaches being ### sub-steps, to create a clearer hierarchy:
## How to Fix the NS0510 Export Error
### Update the Expensify Connect Bundle in NetSuite
### Update NetSuite Role Token Permissions
|
|
||
| --- | ||
|
|
||
| ## Confirm the Role Assigned to the NetSuite Access Token |
There was a problem hiding this comment.
Heading level violation (AI Readiness): Lines 40, 52, and 63 use ## Confirm the Role..., ## Assign the Expensify Integration Role..., and ## Review Global Permissions... as H2 headings. These are sub-steps of the "How to Fix" section on line 36 and should be ### (H3) instead of ## (H2), to maintain a proper heading hierarchy under the parent section.
This structural pattern (fix steps as siblings of the "How to Fix" heading rather than children) appears across many files in this PR. Files should use:
## How to Fix the NS0565 Sync Error
### Confirm the Role Assigned to the NetSuite Access Token
### Assign the Expensify Integration Role to the Employee Record
### Review Global Permissions on the Employee Record
### Retry the Sync in the Workspace
| 2. Verify the integration role is active and has the required permissions. | ||
| 3. Confirm the account ID, role ID, consumer key, consumer secret, token ID, and token secret match what is configured in NetSuite. | ||
| 4. Update any credentials that were recently changed. | ||
| 5. Click **Save** in the Workspace if changes were made. |
There was a problem hiding this comment.
Button label violation (Expensify Style): Per Expensify HelpDot standards, the button at the end of a flow should be labeled Confirm rather than Save. This pattern appears across the majority of the 90 files in this PR wherever "Click Save" is used as the final step of a configuration flow within the Expensify Workspace.
Note: When the instruction refers to clicking Save within NetSuite (the third-party application), "Save" is appropriate since that is the actual NetSuite button label. However, when the instruction refers to saving settings in the Expensify Workspace, the correct label is Confirm.
Please audit each instance of "Click Save" across all files and update the ones that refer to saving in Expensify (not NetSuite) to "Click Confirm".
|
|
||
| In NetSuite: | ||
|
|
||
| - Roles must be assigned to a user to function. |
There was a problem hiding this comment.
Terminology violation (Expensify Style): Per Expensify documentation standards, use "member" instead of "user." The text here and in other places in this file says "not assigned to any user," "tied to a user," "role must be assigned to a user," etc. While these references are to a NetSuite user record (not an Expensify member), the front matter metadata on lines 4 and 5 also uses "user" terminology (Expensify Integration role not assigned to user, NetSuite role not added to user). At minimum, the keywords and internalScope metadata should use Expensify-standard terminology where possible.
For the body content, since "user" here refers specifically to NetSuite's terminology, consider clarifying with "NetSuite user" consistently to avoid ambiguity with Expensify's "member" terminology.
| @@ -0,0 +1,120 @@ | |||
| --- | |||
| title: NS0921 Export Error in NetSuite Integration | |||
| description: Learn what the NS0921 export error means and how to align subsidiaries across reports, users, accounts, tags, and categories in NetSuite. | |||
There was a problem hiding this comment.
Terminology violation (Expensify Style): The description uses "users" (align subsidiaries across reports, users, accounts, tags, and categories). Per Expensify standards, prefer "members" over "users." While the error message itself on line 12 uses "user" (which may be the literal NetSuite error text and should be preserved as-is), the description is authored content and should follow Expensify terminology.
| description: Learn what the NS0921 export error means and how to align subsidiaries across reports, users, accounts, tags, and categories in NetSuite. | |
| description: Learn what the NS0921 export error means and how to align subsidiaries across reports, members, accounts, tags, and categories in NetSuite. |
|
|
||
| --- | ||
|
|
||
| ## Confirm the Subsidiary Selected in the Workspace |
There was a problem hiding this comment.
Heading level violation: This ## Confirm the Subsidiary Selected in the Workspace heading is a sub-step of the "How to Fix" section on line 39 and should be ### (H3). The same applies to ## Verify Subsidiary Alignment in NetSuite on line 60 and ## Sync the Workspace and Retry the Export on line 86. These are implementation steps under the parent "How to Fix" section, not top-level sections of the article.
| 7. Click **Save** if changes are made. | ||
|
|
||
| On mobile: | ||
|
|
There was a problem hiding this comment.
Button label violation (Expensify Style): "Click Save if changes are made" -- if this refers to saving within the Expensify Workspace settings, the button label should be Confirm per Expensify standards. The same issue appears on lines 62 and 80, 86. Please verify whether the UI button in the Workspace actually reads "Save" or "Confirm" and update accordingly.
|
|
||
| ## Does the NS0295 Export Error Affect Only One User? | ||
|
|
||
| Yes. This error is specific to the employee or vendor record associated with the report. |
There was a problem hiding this comment.
Terminology violation (Expensify Style): "Does the NS0295 Export Error Affect Only One User?" -- per Expensify standards, use "member" instead of "user."
| Yes. This error is specific to the employee or vendor record associated with the report. | |
| ## Does the NS0295 Export Error Affect Only One Member? |
|
|
||
| If you see the error: | ||
|
|
||
| NS0005 Export Error: Please enter value(s) for 'department', 'location', or 'class' and attempt to export again. |
There was a problem hiding this comment.
Markdown formatting (Readability): The error message text should be formatted as a blockquote to visually distinguish it from the surrounding content. This is the same pattern flagged across all files. Additionally, this specific error message uses lowercase field names ('department', 'location', 'class') -- consider whether these should match the NetSuite UI casing (Department, Location, Class) for clarity. If this is the literal error message text, it should be preserved as-is but wrapped in a blockquote:
| NS0005 Export Error: Please enter value(s) for 'department', 'location', or 'class' and attempt to export again. | |
| > NS0005 Export Error: Please enter value(s) for 'department', 'location', or 'class' and attempt to export again. |
| --- | ||
|
|
||
| ## Fix the NS0005 Export Error for Vendor Bills | ||
|
|
There was a problem hiding this comment.
Heading hierarchy inconsistency (AI Readiness): This file uses a different heading structure from other files in the PR. Here, the fix sections use ## Fix the NS0005 Export Error for Vendor Bills (H2) with ### Update the Vendor Bill Form (H3) as sub-steps, which is actually the correct hierarchy. However, most other files in this PR (e.g., NS0921, NS0059, NS0919) place what should be H3 sub-steps at the H2 level, creating inconsistency across the collection.
This file's approach (H2 parent, H3 children) is the correct pattern and should be adopted as the standard across all 90 articles for consistency.
| --- | ||
|
|
||
| ## Disconnect the NetSuite Connection | ||
|
|
There was a problem hiding this comment.
Readability concern: The instruction "Take screenshots of: Imported categories, Imported tags, Mapping settings, Any custom configuration" is helpful but assumes the reader knows exactly where to find these settings. Consider linking to the relevant configuration documentation or being more specific about which screens to capture. This would improve the scannability and actionability of the instructions, especially for less experienced Workspace Admins.
|
|
||
| This is a connection or authentication issue, not a report data issue. | ||
|
|
||
| --- |
There was a problem hiding this comment.
Readability / Verbose language: The sentence "Because this error is tied to the NetSuite connection, it cannot be resolved directly from the report itself" and the following sentence "This is a connection or authentication issue, not a report data issue" convey essentially the same information. Consider combining them into a single, concise statement:
This is a connection or authentication issue -- it cannot be resolved from the report itself.
| 5. Update the approval level based on the export type: | ||
|
|
||
| - For **Expense reports** — Select **Supervisor & Accounting Approved**. | ||
| - For **Vendor bills** — Select **Approved for Posting**. |
There was a problem hiding this comment.
Button label violation (Expensify Style): Line 51 says Click **Save** and line 57 says Tap **Save** -- these appear to be within the Expensify Workspace settings flow (Accounting > Advanced). If the actual UI button in Expensify reads "Confirm," this should be updated. This is the same pattern flagged across many files.
Additionally, the approval level names on lines 48-50 ("Supervisor & Accounting Approved," "Approved for Posting") should be verified against the current Expensify UI labels to ensure accuracy.
|
|
||
| ## Confirm the Access Token Is Assigned to the Expensify Integration Role | ||
|
|
||
| 1. Log in to NetSuite as an administrator. |
There was a problem hiding this comment.
Heading level violation: The ## Confirm the Access Token... heading on line 43, ## Confirm Expensify Integration Role Permissions on line 57, and ## Sync the Workspace on line 102 are all sub-steps of the parent "How to Fix the NS0384 Sync Error" section on line 39. These should use ### (H3) to maintain proper heading hierarchy.
This is the same structural pattern seen across many files in this PR. The parent "How to Fix" section should be ##, and each resolution step beneath it should be ###.
| 4. Enable the integration. | ||
| 5. Click **Save**. | ||
|
|
||
| Confirm the integration is fully enabled before leaving the page. |
There was a problem hiding this comment.
Readability / Inconsistent instruction format: This file includes separate "On web:" and "On mobile:" instruction blocks for the "Sync Now" step. Some files in this PR include these dual-platform instructions (e.g., this file, NS0510, NS0565, NS0593, NS0739, NS0942) while others use a single set of instructions without platform distinctions (e.g., NS0109's "Retry the Sync" section at line 63 only shows the web path: "Go to Settings > Workspaces > Select > Accounting > Sync Now").
For consistency across all 90 files, choose one approach and apply it uniformly:
- Option A: Always include both "On web:" and "On mobile:" blocks (more thorough but adds length)
- Option B: Use a single platform-neutral set of instructions (more concise)
The current inconsistency may confuse readers who reference multiple articles.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 86fc3e9acf
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
| @@ -0,0 +1,130 @@ | |||
| --- | |||
There was a problem hiding this comment.
Placing pages under connections/netsuite/Troubleshooting/Export-Errors/... introduces a second nested section level that the route generator does not handle: .github/scripts/createDocsRoutes.ts iterates connections/netsuite/* and unconditionally calls getOrderFromArticleFrontMatter() (which does fs.readFileSync) on each entry, so when it encounters the Troubleshooting directory it attempts to read a directory as a file and exits. Because .github/scripts/createDocsRoutes.sh and .github/workflows/validateDocsRoutes.yml run this command, this change can break docs route validation/deployment.
Useful? React with 👍 / 👎.
|
|
||
| ## Set the Default Corporate Card Account in NetSuite | ||
|
|
||
| 1. Log in to NetSuite as an administrator. |
There was a problem hiding this comment.
Heading level violation: ## Set the Default Corporate Card Account in NetSuite on line 42, ## Sync the Workspace in Expensify on line 55, and ## Retry the Export on line 73 are all sub-steps of the parent "How to Fix" section on line 38. These should be ### (H3) rather than ## (H2).
This is the same heading hierarchy inconsistency noted across many files. Some files (like NS0005) correctly use ### for sub-steps; others (like this one) incorrectly use ##.
| --- | ||
|
|
||
| ## Confirm the Supervisor on the Employee Record | ||
|
|
There was a problem hiding this comment.
Heading level violation: ## Confirm the Supervisor on the Employee Record (line 44), ## Update the Supervisor's Expense Limit (line 55), and ## Sync the Workspace and Retry the Export (line 71) are sub-steps of the "How to Fix" section on line 40. These should use ### (H3) to maintain proper document hierarchy.
| --- | ||
|
|
||
| ## Confirm the CA-Zero Tax Group in NetSuite | ||
|
|
There was a problem hiding this comment.
Heading level violation: ## Confirm the CA-Zero Tax Group in NetSuite (line 44) and ## Sync the Workspace and Retry the Export (line 67) are sub-steps of the "How to Fix" section on line 40. These should be ### (H3).
- Troubleshooting/Authentication-and-Login-errors → Troubleshooting-Authentication-and-Login-errors - Troubleshooting/Connection-errors → Troubleshooting-Connection-errors - Troubleshooting/Export-Errors → Troubleshooting-Export-Errors - Troubleshooting/Sync-Errors → Troubleshooting-Sync-Errors - NetSuite-FAQ.md at netsuite root Made-with: Cursor
github-actions
Bot
changed the title
2 participants
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