[Hold] Add integration sync troubleshooting decision trees#91787
[Hold] Add integration sync troubleshooting decision trees#91787MelvinBot wants to merge 1 commit into
Conversation
Co-authored-by: Stephanie Elliott <stephanieelliott@users.noreply.github.com>
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| --- | ||
| title: NetSuite Sync Troubleshooting | ||
| description: Step-by-step decision tree to diagnose and resolve common NetSuite sync errors before contacting support. | ||
| keywords: [Expensify Classic, NetSuite, sync error, troubleshooting, decision tree, connection error, export error, NS error, sync failed, integration sync, NetSuite troubleshooting] |
There was a problem hiding this comment.
Missing required YAML field: The internalScope field is mandatory per HELP_AUTHORING_GUIDELINES.md Section 3. Add it to specify the audience and scope, e.g.:
internalScope: Audience is Workspace Admins. Covers diagnosing and resolving NetSuite sync errors using a decision tree, does not cover specific NS error code fixes or initial NetSuite setup.
This same issue applies to all 10 new Sync-Troubleshooting.md files in this PR.
| --- | ||
|
|
||
| ## Before You Start | ||
|
|
There was a problem hiding this comment.
Non-task-based heading: Per HELP_AUTHORING_GUIDELINES.md Section 2, all ## headings must start with an action verb or question word (How, What, Where, Who, Why, When). "Before You Start" is a generic/topic heading.
Suggested fix: ## What to confirm before troubleshooting NetSuite sync issues
This applies to the same heading in all 10 files.
|
|
||
| ## Decision Tree: Diagnosing Sync Issues | ||
|
|
||
| Work through these steps in order. Stop when you find the step that matches your situation. |
There was a problem hiding this comment.
Prohibited heading level and generic heading name: ### headings are not allowed -- per HELP_AUTHORING_GUIDELINES.md Section 4 and the pre-publish checklist (Section 9), only ## is permitted for content sections. Additionally, "Step 1" is explicitly listed as a forbidden generic heading in Section 2.
Suggested fix: Restructure the decision tree to use ## headings with task-based phrasing, e.g.:
## How to check if the NetSuite connection is visible in your workspace
This pattern (### Step 1 through ### Step 4) repeats in all 10 files and needs to be restructured throughout.
| - **Note when the issue started.** Knowing whether the sync worked previously or never completed helps narrow down the cause. | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
Non-task-based heading: "Decision Tree: Diagnosing Sync Issues" is a noun/topic heading. Per HELP_AUTHORING_GUIDELINES.md Section 2, it must describe an action or question.
Suggested fix: ## How to diagnose NetSuite sync issues
Same issue in all 10 files.
| - **Role permissions were modified** — Ensure the Expensify Integration role still has the required permissions (Lists, Transactions, Reports, and Custom Records access). | ||
| - **New custom fields, segments, or record types were added** — Check that any new fields are mapped correctly in [Configure NetSuite](https://help.expensify.com/articles/expensify-classic/connections/netsuite/Configure-Netsuite). | ||
| - **NetSuite subscription or account changes** — Confirm your NetSuite edition still supports Web Services and TBA. | ||
|
|
There was a problem hiding this comment.
Non-task-based heading: "Common Causes by Category" is a noun/topic heading. All ## headings must start with an action verb or question word.
Suggested fix: ## What commonly causes NetSuite sync failures
Same issue in all 10 files.
| - **NetSuite subscription or account changes** — Confirm your NetSuite edition still supports Web Services and TBA. | ||
|
|
||
| --- | ||
|
|
There was a problem hiding this comment.
Prohibited heading level: ### is not allowed per HELP_AUTHORING_GUIDELINES.md Section 4 and the pre-publish checklist. Only # (title) and ## (sections) are permitted. The sub-categories (Authentication Issues, Permission Issues, Data Issues, Configuration Issues) should be reformatted as bold text or merged into the parent section.
This applies to all ### sub-category headings under "Common Causes" in all 10 files.
| ### Configuration Issues | ||
| - Export settings in Expensify reference a NetSuite account or item that no longer exists. | ||
| - Subsidiary settings were changed after the initial connection. | ||
| - Custom form preferences in NetSuite conflict with Expensify export formats. |
There was a problem hiding this comment.
Non-task-based heading: "Self-Service Resolution Steps" is a noun/topic heading.
Suggested fix: ## How to resolve NetSuite sync issues yourself
Same issue in all 10 files.
|
|
||
| 1. **Re-sync manually.** Go to your workspace Accounting settings and trigger a manual sync to see if the issue clears on retry. | ||
| 2. **Disconnect and reconnect.** Remove the NetSuite connection from your workspace and set it up again following [Connect to NetSuite](https://help.expensify.com/articles/expensify-classic/connections/netsuite/Connect-To-NetSuite). | ||
| 3. **Review your NetSuite configuration.** Compare your settings in Expensify against your NetSuite setup using [Configure NetSuite](https://help.expensify.com/articles/expensify-classic/connections/netsuite/Configure-Netsuite). |
There was a problem hiding this comment.
Non-task-based heading: "When to Contact Support" is not phrased as a task or question.
Suggested fix: ## When to contact Expensify Support about NetSuite sync issues
Same issue in all 10 files.
|
|
||
| - You have followed all the steps above and the sync still fails. | ||
| - The error code you see is not listed in the Troubleshooting articles. | ||
| - The issue involves data that appears correct on both sides but still does not sync. |
There was a problem hiding this comment.
Wrong heading level for FAQ: Per HELP_AUTHORING_GUIDELINES.md Section 4 and TEMPLATE.md, the FAQ section must use # FAQ (not ## FAQ). The article is allowed exactly one # heading (the title) plus an optional # FAQ.
Additionally, the FAQ questions below use ### but should use ## per TEMPLATE.md structure.
Change:
## FAQ
### How long should a NetSuite sync take?
To:
# FAQ
## How long should a NetSuite sync take?
Same issue in all 10 files.
| Before diving into troubleshooting, confirm the following: | ||
|
|
||
| - **The NetSuite connection is active.** Open your workspace settings and verify the connection is listed under Accounting. If it is not connected, follow the steps in [Connect to NetSuite](https://help.expensify.com/articles/expensify-classic/connections/netsuite/Connect-To-NetSuite). | ||
| - **Check for a specific error code.** If you see an error code starting with **NS** (for example, NS0109), look it up directly in the error code articles under the Troubleshooting folder for a targeted fix. |
There was a problem hiding this comment.
Full URL used instead of relative link: Per HELP_AUTHORING_GUIDELINES.md Section 7 (Link Formatting), articles must use relative links only -- do not use full URLs.
Change [Connect to NetSuite](https://help.expensify.com/articles/expensify-classic/connections/netsuite/Connect-To-NetSuite) to a relative link like [Connect to NetSuite](/articles/expensify-classic/connections/netsuite/Connect-To-NetSuite).
This applies to all cross-links across all 10 files in this PR -- every link uses a full https://help.expensify.com/... URL.
|
|
||
| ## When to Contact Support | ||
|
|
||
| Contact Expensify Support if: |
There was a problem hiding this comment.
Link inside numbered step: Per HELP_AUTHORING_GUIDELINES.md Section 7, links should not be placed inside numbered step instructions. Move cross-references to a sentence after the step list, or to a "Related articles" section.
This applies to steps 2-3 in the "Self-Service Resolution Steps" section across all 10 files.
HelpDot Documentation ReviewOverall AssessmentThis PR adds 10 new Sync Troubleshooting articles (5 for Expensify Classic, 5 for New Expensify) covering NetSuite, QuickBooks Desktop, QuickBooks Online, Sage Intacct, and Xero. The content is well-written, thorough, and genuinely useful for users encountering sync issues. The decision-tree structure is a strong pattern for troubleshooting docs. However, there are several systematic governance violations that repeat across all 10 files and should be addressed before merge. Scores Summary
Key FindingsCritical -- Repeated across all 10 files:
Positive aspects:
Minor -- QuickBooks Desktop articles only:
Recommendations
Files Reviewed
Note: All 10 files share the same structural template, so the governance violations are consistent across the entire PR. Fixing the template pattern once and applying it to all files will resolve the majority of issues. |
![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: da600a03ca
ℹ️ 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".
| Yes. Disconnecting removes all imported options and configuration settings from Expensify. You will need to reconfigure your export and coding settings after reconnecting. | ||
|
|
||
| ### Can I run the Web Connector on a different computer than QuickBooks Desktop? | ||
| No. The Web Connector must be installed on the same computer where the QuickBooks Desktop company file is stored and opened. |
There was a problem hiding this comment.
For Terminal Server/file-server setups, this says the Web Connector must be installed on the machine where the company file is stored, but the existing QuickBooks Desktop setup doc's Terminal Server FAQ says the company file may be stored elsewhere and the Web Connector just needs to run alongside the active QuickBooks Desktop client. Users with a server-stored company file would be incorrectly told their supported setup is impossible; adjust this answer and the Classic mirror to distinguish the QuickBooks Desktop client machine from the file-storage server.
Useful? React with 👍 / 👎.
| title: NetSuite Sync Troubleshooting | ||
| description: Step-by-step decision tree to diagnose and resolve common NetSuite sync errors before contacting support. | ||
| keywords: [New Expensify, NetSuite, sync error, troubleshooting, decision tree, connection error, export error, NS error, sync failed, integration sync, NetSuite troubleshooting] | ||
| --- |
There was a problem hiding this comment.
The HelpDot authoring spec in docs/HELP_AUTHORING_GUIDELINES.md marks internalScope as mandatory for every article's YAML metadata. These new Sync-Troubleshooting pages close the frontmatter after keywords, so they lack the required audience/scope metadata used for review and retrieval; add internalScope before the closing delimiter in each new article.
Useful? React with 👍 / 👎.
stephanieelliott
changed the title
2 participants
@stephanieelliott note: HOLD - these need rewriting
Summary
Related: Expensify/Expensify#637958
New Files
docs/articles/new-expensify/connections/netsuite/Troubleshooting/Sync-Troubleshooting.mddocs/articles/expensify-classic/connections/netsuite/Troubleshooting/Sync-Troubleshooting.mddocs/articles/new-expensify/connections/quickbooks-online/Troubleshooting/Sync-Troubleshooting.mddocs/articles/expensify-classic/connections/quickbooks-online/Troubleshooting/Sync-Troubleshooting.mddocs/articles/new-expensify/connections/quickbooks-desktop/Troubleshooting/Sync-Troubleshooting.mddocs/articles/expensify-classic/connections/quickbooks-desktop/Troubleshooting/Sync-Troubleshooting.mddocs/articles/new-expensify/connections/xero/Troubleshooting/Sync-Troubleshooting.mddocs/articles/expensify-classic/connections/xero/Troubleshooting/Sync-Troubleshooting.mddocs/articles/new-expensify/connections/sage-intacct/Troubleshooting/Sync-Troubleshooting.mddocs/articles/expensify-classic/connections/sage-intacct/Troubleshooting/Sync-Troubleshooting.mdTest plan