[No QA] Helpsite: NetSuite integration error messages (New Expensify) by stephanieelliott · Pull Request #84441 · Expensify/App

stephanieelliott · 2026-03-06T18:53:02Z

Note for reviewers: you only need to review 2 of these files!

This PR changes the route data structure and section template used for the help site, and then also adds 143 help site files.

I've already reviewed the help site files so you can ignore all of those - really just need your review on the changes to these files:

docs/_includes/section.html
.github/scripts/createDocsRoutes.ts

A very thorough summary of the changes that were made and why are in this comment.

I verified this looks good on the Dev build - this page is the prototype: https://509fd29c.helpdot.pages.dev/new-expensify/hubs/connections/netsuite/Troubleshooting

Master project issue https://github.com/Expensify/Expensify/issues/469226
Breaks this main PR into smaller batches: [No QA] [HOLD] Integration Errors Revamp Testing #83106

cc: @CortneyOfstad

Explanation of Change

Rebuilt the docs route script to support true nested sections (no more hardcoded 2-level limit).

See full summary in this comment .

Fixed Issues

https://github.com/Expensify/Expensify/issues/469226
PROPOSAL: N/A

Tests

Verify that no errors appear in the JS console

Offline tests

QA Steps

N/A, no tests

Verify that no errors appear in the JS console

PR Author Checklist

Screenshots/Videos

Android: Native

android.mp4

Android: mWeb Chrome

android.mweb.mp4

iOS: Native

iOS: mWeb Safari

MacOS: Chrome / Safari

web.mp4

github-actions · 2026-03-06T18:57:07Z

HelpDot Documentation Review

Overall Assessment

This PR adds 87 new markdown documentation files for NetSuite integration error messages under the docs/articles/new-expensify/connections/netsuite/Troubleshooting/ directory. The documentation is well-structured, consistent in tone, and will be highly valuable for Workspace Admins encountering NetSuite errors. The consistent template format (error message, why it happens, how to fix, FAQ) makes these files easy to navigate. However, there are several structural and organizational issues that should be addressed before merging.

Scores Summary

Readability: 8/10 - Clear, direct language at an appropriate reading level. Good use of numbered steps and bullet lists. Some files are slightly repetitive in phrasing across categories, and error messages are rendered as plain text rather than distinguished formatting (blockquotes or code blocks), which reduces scanability.
AI Readiness: 7/10 - YAML metadata is thorough with well-formed internalScope fields. However, there are significant heading hierarchy issues: multiple # (H1) headings per file (the # FAQ section uses H1 instead of H2), and some files use H1 for mid-content sections. Several files also duplicate the same error code content across multiple categories with near-identical or identical content, which could confuse AI retrieval systems.
Style Compliance: 7/10 - Good Expensify voice and terminology ("Workspace", "Concierge", "member"). Web/mobile step differentiation is a nice touch. However, error message text is not formatted as blockquotes or code blocks to distinguish it from surrounding prose, ### (H3) headings are used 69 times across files (the style guide recommends # and ## only), and the FAQ heading uses # instead of ##, creating multiple H1s per document.

Key Findings

Critical: Duplicate files across categories. Several error codes appear in multiple category folders with identical or near-identical content:

NS0109-Sync-Error.md appears in Authentication-and-Login-errors/, Connection-errors/, AND Sync-Errors/ (3 copies)
NS0123-Sync-Error.md appears in Authentication-and-Login-errors/, Connection-errors/, AND Sync-Errors/ (3 copies)
NS0565-Sync-Error.md appears in Authentication-and-Login-errors/, Connection-errors/, AND Sync-Errors/ (3 copies)
NS0593-Sync-Error.md appears in Authentication-and-Login-errors/, Connection-errors/, AND Sync-Errors/ (3 copies)
NS0739-Sync-Error.md appears in Authentication-and-Login-errors/, Connection-errors/, AND Sync-Errors/ (3 copies)
NS0942-Sync-Error.md appears in Authentication-and-Login-errors/, Connection-errors/, AND Sync-Errors/ (3 copies)
NS0521-Sync-Error.md appears in Connection-errors/, Export-Errors/, AND Sync-Errors/ (3 copies)
NS0318-Sync-Error.md appears in Authentication-and-Login-errors/ AND Sync-Errors/ (2 copies)
NS0510-Export-Error.md appears in Authentication-and-Login-errors/ AND Export-Errors/ (2 copies)
NS0029-Export-Error.md appears in Authentication-and-Login-errors/ AND Export-Errors/ (2 copies)

This is 26 duplicate files out of 87. While some have minor wording variations, most are effectively identical. This creates confusion for both users and AI systems about which is the canonical version.

Heading hierarchy violations. Every file has two # (H1) headings: one for the title and one for # FAQ. The FAQ section should use ## FAQ instead. Additionally, in Sync-Errors/NS0521-Sync-Error.md, the mid-content headings # How to Fix the NS0521 Sync Error in OneWorld Accounts and # How to Fix the NS0521 Sync Error in Non-OneWorld Accounts use H1 instead of H2. The NetSuite-FAQ.md file uses H1 for every question, resulting in 10+ H1 headings in a single document.

H3 headings used extensively. There are 69 ### headings across the PR. Per HelpDot style guidelines, only # and ## should be used. Sub-steps currently marked as ### should be restructured under ## headings.

Error messages not visually distinguished. All 86 error messages are rendered as plain text paragraphs. Using a blockquote (> prefix) or code block would make them stand out from surrounding prose and be easier for users to match against what they see in the product.

Positive aspects:

Extremely consistent template structure across all 87 files
YAML frontmatter is complete and well-formed, with proper internalScope following the "Audience is... Covers... Does not cover..." pattern
Clear, actionable resolution steps with appropriate web/mobile differentiation
Good keyword coverage for search discoverability
FAQ sections are relevant and anticipate real user questions
Language is jargon-free and appropriate for the target audience
Consistent use of Expensify terminology (Workspace, Concierge, Sync Now, etc.)

Recommendations

[High Priority] Deduplicate files. Each error code should exist in exactly one category folder. If an error spans multiple categories (e.g., NS0109 is both an authentication error and a connection error), place it in the most specific/primary category and consider adding cross-references or a lookup table in NetSuite-FAQ.md.
[High Priority] Fix heading hierarchy. Change # FAQ to ## FAQ in all files. Change ### sub-headings to ## throughout, and restructure content accordingly. Fix the NetSuite-FAQ.md to use ## for questions and ### for sub-sections (or restructure to only use # and ##).
[Medium Priority] Format error messages distinctly. Wrap each error message in a blockquote:
```
> NS0029 Export Error: Unable to export this report due to an error.
```
This improves scanability and helps users confirm they are reading the right article.
[Low Priority] Remove redundant --- horizontal rules. Some files have --- rules that add visual noise without improving structure. Consider removing --- between sections where headings already provide clear separation.

Files Reviewed

Authentication-and-Login-errors/: 9 files -- Well-written; 7 of 9 are duplicated in other categories
Connection-errors/: 7 files -- All 7 are duplicated in other categories (identical or near-identical content)
Export-Errors/: 48 files -- Largest and most unique category; 3 files duplicated elsewhere; 1 file (NS0521-Sync-Error.md) appears misplaced (Sync error in Export-Errors folder)
Sync-Errors/: 22 files -- Good coverage of unique sync errors; several duplicated from Authentication/Connection categories
NetSuite-FAQ.md: 1 file -- Useful overview; heading hierarchy needs correction (multiple H1s)

Note: This review is based on the full diff of all 87 new files proposed in this PR.

OSBotify · 2026-03-06T18:57:38Z

A preview of your ExpensifyHelp changes have been deployed to https://7912a5be.helpdot.pages.dev ⚡️

Updated articles:

github-actions · 2026-03-06T18:59:14Z

@@ -0,0 +1,93 @@
+---


AI Readiness / Readability concern: This file (Connection-errors/NS0109-Sync-Error.md) appears to be an exact duplicate of Authentication-and-Login-errors/NS0109-Sync-Error.md and Sync-Errors/NS0109-Sync-Error.md. The same content exists in three locations.

This duplication pattern affects 7 error codes across this PR:

NS0109 (3 copies): Auth, Connection, Sync

NS0123 (3 copies): Auth, Connection, Sync

NS0521 (3 copies): Connection, Export, Sync

NS0565 (3 copies): Auth, Connection, Sync

NS0593 (3 copies): Auth, Connection, Sync

NS0739 (3 copies): Auth, Connection, Sync

NS0942 (3 copies): Auth, Connection, Sync

NS0318 (2 copies): Auth, Sync

NS0510 (2 copies): Auth, Export

NS0029 (2 copies): Auth, Export

Duplicate articles create confusion for both AI retrieval systems and human readers. If the intent is cross-referencing, consider keeping a single canonical article and adding redirects or cross-links from the other locations instead.

github-actions · 2026-03-06T19:00:42Z

@@ -0,0 +1,118 @@
+---


Categorization issue (AI Readiness): This file is named NS0521-Sync-Error.md and documents a Sync Error, but it is placed in the Export-Errors/ directory. This could confuse both AI retrieval systems and readers who expect Export-Errors to contain only export errors. Consider moving this to the Sync-Errors/ directory (where a copy already exists) and removing it from Export-Errors/.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 8726fdc655

ℹ️ 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".

MelvinBot · 2026-03-06T21:18:07Z

Fixed the remaining build failure.

Problem: Liquid's empty keyword resolves to an empty string "", not an empty array []. When section.articles is nil (e.g., for sections that only have child sections and no direct articles), | default: empty produced "", and then | sort tried to call map on a string, causing undefined method 'map' for "":String.

Fix: Replaced the | default: empty | sort pattern with a proper conditional:

{% assign sortedArticles = "" | split: "," %}
{% if section.articles %}
    {% assign sortedArticles = section.articles | sort: 'order', 'last' %}
{% endif %}

"" | split: "," is the standard Liquid idiom for creating an empty array. The sort now only runs when articles actually exist.

stephanieelliott · 2026-03-07T03:03:59Z

@MelvinBot can you please summarize the changes to the help site layout made from this PR, especially those around scripts and templates?

MelvinBot · 2026-03-07T03:05:54Z

Here's a summary of the help site layout changes in this PR, focusing on scripts and templates:

Route Generation Script (`.github/scripts/createDocsRoutes.ts`)

Before

The old script handled nested article directories with hardcoded nesting depth (up to 2 levels deep). It iterated through section subdirectories manually with nested for loops:

Level 0: section/file.md — article with href file
Level 1: section/SubFolder/file.md — article with href SubFolder/file, hardcoded title "Troubleshoot SubFolder"
Level 2: section/SubFolder/NestedFolder/file.md — article with href SubFolder/NestedFolder/file, hardcoded title "Troubleshoot NestedFolder"

All nested articles were flattened into a single articles[] array on the parent section. There was no concept of nested sections — only nested article hrefs with path separators.

After

The new script uses a recursive buildSection() function that supports arbitrary nesting depth. Key changes:

Section type now supports child sections?: Section[] — sections can be nested inside other sections, forming a tree
buildSection() recursively walks a directory, creating Article objects for .md files and child Section objects for subdirectories. Each section's href is built by concatenating parent paths (e.g., netsuite/Troubleshooting/Export-Errors)
flattenSections() produces a flat array of all sections (including deeply nested ones) stored as hub.flatSections for easy lookup by full path
getArticleObj() simplified — removed the titleOverride parameter; titles now always derive from the filename
getOrderFromArticleFrontMatter() wrapped in a try/catch so a malformed article file won't crash the entire route generation

Route data structure change

Before: A hub's section looked like:

sections:
  - href: netsuite
    title: Netsuite
    articles:
      - href: Overview
      - href: Troubleshooting/Export-Errors/NS0005-Export-Error  # flat path

After: Sections are now hierarchical:

sections:
  - href: netsuite
    title: Netsuite
    articles:
      - href: Overview
    sections:
      - href: netsuite/Troubleshooting
        title: Troubleshooting
        sections:
          - href: netsuite/Troubleshooting/Export-Errors
            title: Export Errors
            articles:
              - href: NS0005-Export-Error
flatSections:  # flat list of ALL sections for page lookup
  - href: netsuite
  - href: netsuite/Troubleshooting
  - href: netsuite/Troubleshooting/Export-Errors
  - ...

Section Template (`docs/_includes/section.html`)

Before

The old template:

Extracted the section name from urlArray[3] (a single path segment, e.g., netsuite)
Looked up the section in hub.sections by that single name
Rendered all articles in a flat list, using complex Liquid logic to:
- Group articles by subfolder path segments (manually collecting unique subfolder names via pipe-delimited strings)
- Render 2-segment paths under <h3> subfolder headings
- Render 3-segment paths under <h4> sub-subfolder headings
Was ~120 lines of complex, hard-to-follow Liquid

After

The new template:

Builds the full activeSectionPath from the URL (e.g., netsuite/Troubleshooting/Export-Errors) by stripping the hub prefix and .html
Uses a multi-step section lookup:
- First tries the top-level section by the first path segment (sectionParts[0])
- Falls back to matching the full path against hub.sections
- Then drills into section.sections (1 level) looking for a match on activeSectionPath
- Then drills into grandchild sections (2 levels) for deeper nesting
Renders a simple, flat card grid for the resolved section:
- Child sections render as section cards (linking to sub-section pages)
- Child articles render as article cards
Uses section.articles | default: empty to safely handle sections with no direct articles
Is now ~53 lines — much simpler because the nesting complexity moved into the route data structure

Key architectural shift

The grouping/nesting logic moved from the Liquid template to the route generation script. Instead of the template parsing nested article hrefs at render time, the script now builds a proper section tree, and the template just renders whatever section it resolves to — showing its direct child sections and articles as cards.

New Hub Pages

The PR adds new hub .html pages for nested troubleshooting sections across multiple integrations (netsuite, certinia, quickbooks-desktop, sage-intacct). These are simple pages containing just {% include section.html %} — the section template handles all the rendering. Each .html file corresponds to a navigable section page (e.g., netsuite/Troubleshooting.html shows the Troubleshooting subsections, netsuite/Troubleshooting/Export-Errors.html shows the export error articles).

rushatgabhane

LGTM

Screen.Recording.2026-03-07.at.12.02.59.mov

…ions again

…-error-docs-flatsections [No QA] use hub.flatSections in section.html to avoid having to traverse sections again

stephanieelliott · 2026-03-09T22:18:23Z

Reviewer Checklist

I have verified the author checklist is complete (all boxes are checked off).
I verified the correct issue is linked in the ### Fixed Issues section above
I verified testing steps are clear and they cover the changes made in this PR
- I verified the steps for local testing are in the Tests section
- I verified the steps for Staging and/or Production testing are in the QA steps section
- I verified the steps cover any possible failure scenarios (i.e. verify an input displays the correct error message if the entered data is not correct)
- I turned off my network connection and tested it while offline to ensure it matches the expected behavior (i.e. verify the default avatar icon is displayed if app is offline)
I checked that screenshots or videos are included for tests on all platforms
I included screenshots or videos for tests on all platforms
I verified that the composer does not automatically focus or open the keyboard on mobile unless explicitly intended. This includes checking that returning the app from the background does not unexpectedly open the keyboard.
I verified tests pass on all platforms & I tested again on:
- Android: HybridApp
- Android: mWeb Chrome
- iOS: HybridApp
- iOS: mWeb Safari
- MacOS: Chrome / Safari
If there are any errors in the console that are unrelated to this PR, I either fixed them (preferred) or linked to where I reported them in Slack
I verified there are no new alerts related to the canBeMissing param for useOnyx
I verified proper code patterns were followed (see Reviewing the code)
- I verified that any callback methods that were added or modified are named for what the method does and never what callback they handle (i.e. toggleReport and not onIconClick).
- I verified that comments were added to code that is not self explanatory
- I verified that any new or modified comments were clear, correct English, and explained "why" the code was doing something instead of only explaining "what" the code was doing.
- I verified any copy / text shown in the product is localized by adding it to src/languages/* files and using the translation method
- I verified all numbers, amounts, dates and phone numbers shown in the product are using the localization methods
- I verified any copy / text that was added to the app is grammatically correct in English. It adheres to proper capitalization guidelines (note: only the first word of header/labels should be capitalized), and is either coming verbatim from figma or has been approved by marketing (in order to get marketing approval, ask the Bug Zero team member to add the Waiting for copy label to the issue)
- I verified proper file naming conventions were followed for any new files or renamed files. All non-platform specific files are named after what they export and are not named "index.js". All platform-specific files are named for the platform the code supports as outlined in the README.
- I verified the JSDocs style guidelines (in STYLE.md) were followed
If a new code pattern is added I verified it was agreed to be used by multiple Expensify engineers
I verified that this PR follows the guidelines as stated in the Review Guidelines
I verified other components that can be impacted by these changes have been tested, and I retested again (i.e. if the PR modifies a shared library or component like Avatar, I verified the components using Avatar have been tested & I retested again)
I verified all code is DRY (the PR doesn't include any logic written more than once, with the exception of tests)
I verified any variables that can be defined as constants (ie. in CONST.ts or at the top of the file that uses the constant) are defined as such
If a new component is created I verified that:
- A similar component doesn't exist in the codebase
- All props are defined accurately and each prop has a /** comment above it */
- The file is named correctly
- The component has a clear name that is non-ambiguous and the purpose of the component can be inferred from the name alone
- The only data being stored in the state is data necessary for rendering and nothing else
- For Class Components, any internal methods passed to components event handlers are bound to this properly so there are no scoping issues (i.e. for onClick={this.submit} the method this.submit should be bound to this in the constructor)
- Any internal methods bound to this are necessary to be bound (i.e. avoid this.submit = this.submit.bind(this); if this.submit is never passed to a component event handler like onClick)
- All JSX used for rendering exists in the render method
- The component has the minimum amount of code necessary for its purpose, and it is broken down into smaller components in order to separate concerns and functions
If any new file was added I verified that:
- The file has a description of what it does and/or why is needed at the top of the file if the code is not self explanatory
If a new CSS style is added I verified that:
- A similar style doesn't already exist
- The style can't be created with an existing StyleUtils function (i.e. StyleUtils.getBackgroundAndBorderStyle(theme.componentBG)
If the PR modifies code that runs when editing or sending messages, I tested and verified there is no unexpected behavior for all supported markdown - URLs, single line code, code blocks, quotes, headings, bold, strikethrough, and italic.
If the PR modifies a generic component, I tested and verified that those changes do not break usages of that component in the rest of the App (i.e. if a shared library or component like Avatar is modified, I verified that Avatar is working as expected in all cases)
If the PR modifies a component related to any of the existing Storybook stories, I tested and verified all stories for that component are still working as expected.
If the PR modifies a component or page that can be accessed by a direct deeplink, I verified that the code functions as expected when the deeplink is used - from a logged in and logged out account.
If the PR modifies the UI (e.g. new buttons, new UI components, changing the padding/spacing/sizing, moving components, etc) or modifies the form input styles:
- I verified that all the inputs inside a form are aligned with each other.
- I added Design label and/or tagged @Expensify/design so the design team can review the changes.
If a new page is added, I verified it's using the ScrollView component to make it scrollable when more elements are added to the page.
For any bug fix or new feature in this PR, I verified that sufficient unit tests are included to prevent regressions in this flow.
If the main branch was merged into this PR after a review, I tested again and verified the outcome was still expected according to the Test steps.
I have checked off every checkbox in the PR reviewer checklist, including those that don't apply to this PR.

Screenshots/Videos

Android: HybridApp

Android: mWeb Chrome

iOS: HybridApp

iOS: mWeb Safari

MacOS: Chrome / Safari

stephanieelliott · 2026-03-09T22:19:15Z

@MelvinBot how can I fix the failed test?

MelvinBot · 2026-03-09T22:21:03Z

The failing ESLint check is not caused by your PR — it's a pre-existing issue on main. The warnings are all in files your PR doesn't touch:

src/pages/workspace/travel/WorkspaceTravelInvoicingExportPage.tsx — react-hooks/set-state-in-effect
src/pages/workspace/upgrade/WorkspaceUpgradePage.tsx — react-hooks/preserve-manual-memoization
src/pages/workspace/workflows/approvals/WorkspaceWorkflowsApprovalsEditPage.tsx — react-hooks/set-state-in-effect
src/pages/workspace/workflows/approvals/WorkspaceWorkflowsApprovalsExpensesFromPage.tsx — react-hooks/set-state-in-effect

Your PR only modifies docs files, createDocsRoutes.ts, and section.html — none of which have lint issues (the Changed files ESLint check passed).

No action needed from you. This should resolve once main is fixed, or you can try merging the latest main into your branch in case it's already been addressed there. The other failing check (checklist) is just the PR author checklist and doesn't block merge.

Merge main into my branch to fix failed lint test

melvin-bot · 2026-03-09T23:33:10Z

@deetergp looks like this was merged without a test passing. Please add a note explaining why this was done and remove the Emergency label if this is not an emergency.

OSBotify · 2026-03-10T19:21:41Z

🚀 Deployed to staging by https://github.com/deetergp in version: 9.3.35-0 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

OSBotify · 2026-03-11T19:35:53Z

🚀 Deployed to production by https://github.com/luacmartins in version: 9.3.35-1 🚀

platform	result
🕸 web 🕸	success ✅
🤖 android 🤖	success ✅
🍎 iOS 🍎	success ✅

deetergp · 2026-03-11T19:38:36Z

The tests were all passing when I merged it.

Add error message files to folder

8726fdc

stephanieelliott requested a review from CortneyOfstad March 6, 2026 18:53

stephanieelliott self-assigned this Mar 6, 2026

stephanieelliott changed the title ~~Helpsite: NetSuite integration error messages~~ Helpsite: NetSuite integration error messages (New Expensify) Mar 6, 2026