From 928a4451f78128886f7ddefd53e9b74cd6fb9e7b Mon Sep 17 00:00:00 2001 From: Jaime Meza Date: Tue, 17 Nov 2026 10:42:21 -0500 Subject: [PATCH] Add DataHUB documentation and API reference - Introduced new documentation for the DataHUB service, including purpose, roles, and business case. - Added detailed API reference for Quotes and Visits, including search endpoints and response structures. - Created sections for service records, time reports, and visits in the CustomerHUB documentation. - Implemented a change log and test plan for the DataHUB project. - Updated the introduction to include links to the new DataHUB documentation. - Modified navbar configuration to reflect changes in documentation structure. --- .gitignore | 1 + docs/customerhub/_category_.json | 9 + docs/customerhub/explanation/_category_.json | 8 + .../explanation/what-is-customerhub.md | 35 ++ docs/customerhub/how-to/_category_.json | 8 + docs/customerhub/how-to/find-a-customer.md | 13 + .../how-to/import-customer-from-ifs.md | 17 + docs/customerhub/reference/_category_.json | 8 + docs/customerhub/reference/assets.md | 44 +++ docs/customerhub/reference/cases.md | 21 ++ docs/customerhub/reference/customer-orders.md | 54 +++ docs/customerhub/reference/customers.md | 82 +++++ docs/customerhub/reference/dashboard.md | 65 ++++ docs/customerhub/reference/forms.md | 24 ++ docs/customerhub/reference/invoices.md | 46 +++ docs/customerhub/reference/quotes.md | 82 +++++ docs/customerhub/reference/sales-parts.md | 44 +++ docs/customerhub/reference/service-records.md | 21 ++ docs/customerhub/reference/time-report.md | 23 ++ docs/customerhub/reference/visits.md | 34 ++ docs/customerhub/reference/work-tasks.md | 37 ++ docs/datahub/_category_.json | 9 + docs/datahub/explanation/_category_.json | 8 + docs/datahub/explanation/business-case.md | 79 +++++ docs/datahub/explanation/purpose-and-roles.md | 34 ++ docs/datahub/reference/_category_.json | 8 + .../reference/assumptions-and-dependencies.md | 30 ++ docs/datahub/reference/change-log.md | 18 + docs/datahub/reference/dataset-details.md | 332 ++++++++++++++++++ docs/datahub/reference/estimates.md | 39 ++ docs/datahub/reference/overview.md | 32 ++ docs/datahub/reference/performance-and-ao.md | 44 +++ docs/datahub/reference/quotes-search.md | 125 +++++++ docs/datahub/reference/solution-design.md | 133 +++++++ docs/datahub/reference/test-plan.md | 36 ++ docs/datahub/reference/visits-search.md | 100 ++++++ docs/intro.mdx | 19 + docusaurus.config.ts | 6 +- 38 files changed, 1725 insertions(+), 3 deletions(-) create mode 100644 docs/customerhub/_category_.json create mode 100644 docs/customerhub/explanation/_category_.json create mode 100644 docs/customerhub/explanation/what-is-customerhub.md create mode 100644 docs/customerhub/how-to/_category_.json create mode 100644 docs/customerhub/how-to/find-a-customer.md create mode 100644 docs/customerhub/how-to/import-customer-from-ifs.md create mode 100644 docs/customerhub/reference/_category_.json create mode 100644 docs/customerhub/reference/assets.md create mode 100644 docs/customerhub/reference/cases.md create mode 100644 docs/customerhub/reference/customer-orders.md create mode 100644 docs/customerhub/reference/customers.md create mode 100644 docs/customerhub/reference/dashboard.md create mode 100644 docs/customerhub/reference/forms.md create mode 100644 docs/customerhub/reference/invoices.md create mode 100644 docs/customerhub/reference/quotes.md create mode 100644 docs/customerhub/reference/sales-parts.md create mode 100644 docs/customerhub/reference/service-records.md create mode 100644 docs/customerhub/reference/time-report.md create mode 100644 docs/customerhub/reference/visits.md create mode 100644 docs/customerhub/reference/work-tasks.md create mode 100644 docs/datahub/_category_.json create mode 100644 docs/datahub/explanation/_category_.json create mode 100644 docs/datahub/explanation/business-case.md create mode 100644 docs/datahub/explanation/purpose-and-roles.md create mode 100644 docs/datahub/reference/_category_.json create mode 100644 docs/datahub/reference/assumptions-and-dependencies.md create mode 100644 docs/datahub/reference/change-log.md create mode 100644 docs/datahub/reference/dataset-details.md create mode 100644 docs/datahub/reference/estimates.md create mode 100644 docs/datahub/reference/overview.md create mode 100644 docs/datahub/reference/performance-and-ao.md create mode 100644 docs/datahub/reference/quotes-search.md create mode 100644 docs/datahub/reference/solution-design.md create mode 100644 docs/datahub/reference/test-plan.md create mode 100644 docs/datahub/reference/visits-search.md diff --git a/.gitignore b/.gitignore index 55ee151..af4bc27 100644 --- a/.gitignore +++ b/.gitignore @@ -8,6 +8,7 @@ .atl .docusaurus .cache-loader +.playwright-mcp # Misc .DS_Store diff --git a/docs/customerhub/_category_.json b/docs/customerhub/_category_.json new file mode 100644 index 0000000..13cff51 --- /dev/null +++ b/docs/customerhub/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "CustomerHUB", + "position": 4, + "collapsible": true, + "link": { + "type": "generated-index", + "description": "User documentation for the CustomerHUB application — reference, guides, and explanations for every module." + } +} diff --git a/docs/customerhub/explanation/_category_.json b/docs/customerhub/explanation/_category_.json new file mode 100644 index 0000000..028bc51 --- /dev/null +++ b/docs/customerhub/explanation/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Explanation", + "position": 1, + "link": { + "type": "generated-index", + "description": "Background and context for understanding how CustomerHUB works and why it is structured the way it is." + } +} diff --git a/docs/customerhub/explanation/what-is-customerhub.md b/docs/customerhub/explanation/what-is-customerhub.md new file mode 100644 index 0000000..c444d28 --- /dev/null +++ b/docs/customerhub/explanation/what-is-customerhub.md @@ -0,0 +1,35 @@ +--- +sidebar_position: 1 +title: What is CustomerHUB +--- + +# What is CustomerHUB + +CustomerHUB is a web portal built on HOIST HUB that centralizes customer-facing operations — from quotes and orders to invoices, assets, and service records. It connects directly to IFS, acting as the operational front end for field teams and back-office staff. + +## How it fits into the ecosystem + +CustomerHUB does not store data independently. Every customer, order, quote, and invoice originates in or synchronizes with IFS. The portal surfaces that data in a structured, role-agnostic interface and allows users to act on it — creating orders, reviewing invoices, logging service records — without needing direct IFS access. + +## Modules at a glance + +| Module | Purpose | +|---|---| +| Dashboard | At-a-glance summary of open quotes, orders, invoices, and work tasks | +| Customers | Manage customer profiles, contacts, addresses, and IFS sync | +| Quotes | Create and track sales quotes through their lifecycle | +| Customer Orders | Monitor order fulfillment from creation to invoicing | +| Invoices | Review and track customer invoice status | +| Visits | Log and manage customer site visits | +| Assets | Track customer-owned assets | +| Sales Parts | Browse the product catalog | +| Service Records | Attach and review service documentation | +| Forms | Fill and submit structured field forms | +| Cases | Manage support or service cases | +| Work Tasks | Track field work task status | +| Time Report | Log time entries against work | +| Administration | Manage users, profiles, and system configuration | + +## IFS synchronization + +Customer records can be imported directly from IFS using the **Import From IFS** tab in the Customers module. Once imported, the record can be kept in sync using the **Sync From IFS** action on the customer detail page. The **Last IFS Sync** field on each customer record shows when the last synchronization occurred. diff --git a/docs/customerhub/how-to/_category_.json b/docs/customerhub/how-to/_category_.json new file mode 100644 index 0000000..7c5cd82 --- /dev/null +++ b/docs/customerhub/how-to/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "How-to Guides", + "position": 3, + "link": { + "type": "generated-index", + "description": "Step-by-step guides for common tasks in CustomerHUB." + } +} diff --git a/docs/customerhub/how-to/find-a-customer.md b/docs/customerhub/how-to/find-a-customer.md new file mode 100644 index 0000000..bc8c312 --- /dev/null +++ b/docs/customerhub/how-to/find-a-customer.md @@ -0,0 +1,13 @@ +--- +sidebar_position: 1 +title: Find a customer +--- + +# Find a customer + +1. Click **Customers** in the sidebar. +2. Type the customer name or IFS Customer ID in the search field. +3. Click **Search**. +4. Click the customer card to open the detail view. + +To reset the search, click **Clear Filters**. diff --git a/docs/customerhub/how-to/import-customer-from-ifs.md b/docs/customerhub/how-to/import-customer-from-ifs.md new file mode 100644 index 0000000..b3dbffc --- /dev/null +++ b/docs/customerhub/how-to/import-customer-from-ifs.md @@ -0,0 +1,17 @@ +--- +sidebar_position: 2 +title: Import a customer from IFS +--- + +# Import a customer from IFS + +Use this when a customer exists in IFS but does not yet appear in CustomerHUB. + +1. Click **Customers** in the sidebar. +2. Click the **Import From IFS** tab. +3. Type the customer name or IFS ID and click **Search**. +4. Select the customer from the results. + +The customer record is created in CustomerHUB and is immediately available in the **Customers** tab. + +To keep an existing customer record up to date with IFS, use the **Sync From IFS** button on the customer detail page instead. diff --git a/docs/customerhub/reference/_category_.json b/docs/customerhub/reference/_category_.json new file mode 100644 index 0000000..d5fb385 --- /dev/null +++ b/docs/customerhub/reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Reference", + "position": 2, + "link": { + "type": "generated-index", + "description": "Field-by-field and section-by-section reference for every module in CustomerHUB." + } +} diff --git a/docs/customerhub/reference/assets.md b/docs/customerhub/reference/assets.md new file mode 100644 index 0000000..5f2b5f2 --- /dev/null +++ b/docs/customerhub/reference/assets.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 7 +title: Assets +--- + +# Assets + +The Assets module tracks customer-owned equipment and functional areas, organized as a hierarchical asset tree synchronized with IFS. + +## List view + +Assets has two tabs: **Assets** (the active asset list) and **Import From IFS**. + +**Search filters:** Asset Name or Code, Customer, Territory, Region. Use **+ Add Asset Attribute Filter** to add dynamic filters based on asset attribute values. + +Results display as a collapsible tree reflecting the asset hierarchy. Use **Expand All** to flatten the view. Each row shows: **Asset** (name and code, links to detail), **Level**, **Type**, **Install Date**, **Customer**, **Created By**, **Belongs To**, **Is Active**, and a **View in IFS** link. + +### Import From IFS tab + +Search IFS for assets not yet in CustomerHUB. Importing creates the asset record and makes it available in the Assets tab. + +--- + +## Asset detail + +### General Information + +- **Asset ID** — system-generated identifier +- **Asset Level** — hierarchy level (e.g. Functional Area) +- **Asset Type** — classification type +- **Asset Description** — display name +- **Belongs To** — parent asset in the hierarchy +- **Customer** — owning customer +- **Address** — physical location +- **Installation Date** — date installed +- **Last Synced On** — date of last IFS synchronization +- **HUB Status** — Active or Inactive +- **Operational Status** — current operational state (e.g. In Operation) + +Use **Sync From IFS** to refresh the asset data from IFS. Use **Change Operational Status** to update the operational state. + +### Asset Attribute Values + +Custom attributes defined for this asset type, showing attribute name, unit of measure, and current value. diff --git a/docs/customerhub/reference/cases.md b/docs/customerhub/reference/cases.md new file mode 100644 index 0000000..ef8dfab --- /dev/null +++ b/docs/customerhub/reference/cases.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 11 +title: Cases +--- + +# Cases + +The Cases module manages support and service cases. Access is controlled by user permissions — not all users can view this module. + +## List view + +### Search filters + +| Filter | Description | +|---|---| +| **Case Id** | Search by case identifier | +| **Queued To** | Filter by the queue the case is assigned to | + +:::note +Cases requires specific permissions. If you see "You don't have permissions to view this screen", contact your system administrator. +::: diff --git a/docs/customerhub/reference/customer-orders.md b/docs/customerhub/reference/customer-orders.md new file mode 100644 index 0000000..c36d2b6 --- /dev/null +++ b/docs/customerhub/reference/customer-orders.md @@ -0,0 +1,54 @@ +--- +sidebar_position: 4 +title: Customer Orders +--- + +# Customer Orders + +The Customer Orders module manages sales orders from creation in HUB through submission to IFS and fulfillment. + +## List view + +**Search filters:** Order No, Customer PO No, IFS Status, HUB Status, Customer, Territory, Region, Tech Id. + +Each result row shows: **Number**, **Customer PO No**, **Customer**, **IFS Status**, **HUB Status**, **Creation Date**, **Created By**, **Total Amount**. + +Use **New Order +** to create a new order. + +--- + +## Order detail + +### Header fields + +- **Customer** — customer this order is for (required) +- **Wanted Delivery Date** — requested delivery date (required) +- **Customer PO No** — customer's purchase order number (required) +- **Tag PO No** — optional secondary PO reference +- **Delivery Address** — address where goods will be delivered (required) +- **Document Address** — address for invoice and document delivery + +The summary bar shows **Total Value** and **Net Weight** across all order lines. + +### Actions + +- **Save** — save changes to the order header +- **Refresh From IFS** — pull the latest data from IFS for this order +- **Submit to IFS** — submit the order to IFS for processing +- **View In IFS** — open the order directly in IFS (link in header) + +--- + +## Tabs + +### Lines — Order Lines + +Individual products on the order: Line No, Part No, Part Description, Quantity, UoM, Weight, List Price, Customer Price, Discount (%). + +### Attachments + +Files attached to the order. + +### Notes + +Free-text notes associated with the order. diff --git a/docs/customerhub/reference/customers.md b/docs/customerhub/reference/customers.md new file mode 100644 index 0000000..791c27e --- /dev/null +++ b/docs/customerhub/reference/customers.md @@ -0,0 +1,82 @@ +--- +sidebar_position: 2 +title: Customers +--- + +# Customers + +The Customers module manages all customer profiles in CustomerHUB. It has two tabs: **Customers** (the active customer list) and **Import From IFS** (for bringing new customers in from IFS). + +## Customers tab + +Search by customer name or IFS Customer ID. Results are not shown until **Search** is clicked. Use **Clear Filters** to reset. + +Each result card shows: + +- **Customer** — customer name and IFS Customer ID +- **Representative** — assigned CRM representative(s) +- **MSHA** — whether the site is MSHA-regulated +- **IC** — inter company customer flag (checkmark if yes) +- **Service Contract** — linked service contract, if any +- **Agreement** — linked agreement, if any +- **Status** — Active or Inactive + +## Import From IFS tab + +Search IFS for customers not yet in CustomerHUB by name or IFS ID. Selecting a result imports the customer record and creates a profile in CustomerHUB. + +--- + +## Customer detail + +Clicking a customer opens the detail view. The top bar provides: + +- **Quick Find Customers** — jump to another customer without going back to the list +- **Quick Access (In Page)** — scroll directly to a section +- **User Profiles** — manage access profiles for this customer's portal users +- **Users** — manage individual portal users for this customer + +### General Information + +- **Portal Owner** — the internal owner of this customer's portal +- **Number of users allowed** — maximum portal users for this customer +- **Status** — Active or Inactive +- **Customer Name** — display name (from IFS) +- **IFS Customer ID** — the customer's ID in IFS +- **Price Group** — assigned pricing group +- **Created On** — date the record was created in HUB +- **Last Updated** — date of the last manual edit +- **Last IFS Sync** — date of the last sync from IFS +- **Is MSHA Site** — toggle: whether this is an MSHA-regulated site +- **Inter Company Customer?** — whether this is an inter-company customer +- **Inter Comp Markup** — markup percentage applied to inter-company orders + +Use **Sync From IFS** to re-fetch all IFS data for this customer. + +### Address Info + +Addresses associated with the customer. Filterable by type (Delivery, Document) and status (All, Active, Inactive). + +### Customer Contacts + +Contacts linked to this customer, showing name, role, and contact details. + +### Communication Methods + +Preferred communication channels (email, phone, etc.) for this customer. + +### CRM Representatives + +Internal representatives assigned to manage this customer relationship. + +### Proprietary Parts + +Parts specific to this customer that are not in the general catalog. + +### Customer Restricted Sales Groups + +Sales groups that are restricted or granted special access for this customer. + +### Customer Service Contracts + +Active and historical service contracts linked to this customer. diff --git a/docs/customerhub/reference/dashboard.md b/docs/customerhub/reference/dashboard.md new file mode 100644 index 0000000..8b36b87 --- /dev/null +++ b/docs/customerhub/reference/dashboard.md @@ -0,0 +1,65 @@ +--- +sidebar_position: 1 +title: Dashboard +--- + +# Dashboard + +The Dashboard is the home screen of CustomerHUB. It provides a real-time summary of activity across the main operational modules, filtered by customer and date period. + +## Filters + +- **Customer** — filters all widgets to a specific customer. Defaults to All. +- **Period** — date range applied to all widgets. Defaults to the last 90 days. + +## Widgets + +### My Quote Approvals + +Quotes pending your approval. Displays a count badge; shows "No items to show..." when the queue is empty. + +### All Quotes + +All quotes in the system, broken down by status. Each row links to the filtered quote list. + +- **Planned** — quote created but not yet released +- **Released** — quote sent to the customer +- **Cancelled** — quote cancelled +- **Closed** — quote completed + +### My Quotes + +Quotes assigned to the logged-in user. Shows a count badge; empty state when no quotes are assigned. + +### Customer Orders + +Open customer orders, broken down by fulfillment status. + +- **Planned / Created** — order created in HUB, not yet submitted to IFS +- **Planned / Ready for IFS** — order staged for IFS submission +- **Planned / Submitted to IFS** — order submitted, pending IFS processing +- **Invoiced** — order invoiced +- **Released** — order released for fulfillment +- **Reserved** — stock reserved for the order +- **Picked** — items picked for shipment +- **Cancelled** — order cancelled + +### Customer Invoices + +Open invoices, broken down by payment status. + +- **Printed** — invoice printed but not yet posted +- **Posted Authorized** — invoice posted and authorized +- **Paid Posted** — invoice paid and posted + +### Work Tasks + +Active work tasks, broken down by progress status. + +- **New** — task created, not yet started +- **Released** — task released to the field +- **Work Started** — task in progress + +## Navigation + +Each status row in every widget is a link. Clicking a row navigates to the corresponding module pre-filtered by that status, the selected customer, and the selected period. diff --git a/docs/customerhub/reference/forms.md b/docs/customerhub/reference/forms.md new file mode 100644 index 0000000..f73bfc3 --- /dev/null +++ b/docs/customerhub/reference/forms.md @@ -0,0 +1,24 @@ +--- +sidebar_position: 10 +title: Forms +--- + +# Forms + +The Forms module lists all dynamic forms that have been submitted — either standalone or as part of a visit. Forms are structured templates configured per installation; their sections and fields vary by form type. + +## List view + +**Search filters:** Form Name, Customer, Date Submitted, Created By. + +Results load automatically without needing to click Search. Each row shows: **Name** (links to detail), **Customer**, **Form Type**, **Created By**, **As Visit?** (whether submitted as part of a visit), **Date Submitted**, and a PDF download icon. + +--- + +## Form detail + +The detail view renders the submitted form with all answers visible, divided into the sections defined by the form template (e.g. People / Location, Task / Equipment). + +The metadata header shows: **Customer**, **Tech Id**, **Created By**, **Territory**, **Region**, **Date Submitted**. + +Form answers are read-only in the detail view. diff --git a/docs/customerhub/reference/invoices.md b/docs/customerhub/reference/invoices.md new file mode 100644 index 0000000..85a3169 --- /dev/null +++ b/docs/customerhub/reference/invoices.md @@ -0,0 +1,46 @@ +--- +sidebar_position: 5 +title: Invoices +--- + +# Invoices + +The Invoices module provides a read-only view of customer invoices synchronized from IFS. + +## List view + +**Search filters:** Invoice No, Order No, Status. + +Each result row shows: **Invoice No**, **Order No**, **Customer** (with IFS ID), **Date**, **Status** (PaidPosted, PostedAuth, Printed), **Gross Amt**, and a **View In IFS** link. + +Use **Export to Excel** to download the list. + +--- + +## Invoice detail + +### General Information + +- **Customer** — customer name and IFS ID +- **Series ID** — invoice series identifier +- **Invoice No** — invoice number +- **Status** — current status +- **Invoice Created At** / **Order Created At** — creation dates in IFS +- **Currency** — invoice currency +- **Gross Amount** — total amount including tax +- **Tax Amount** — tax portion +- **Net Amount** — amount excluding tax + +Use **View in IFS** (top right) to open the full record in IFS. + +### Invoice Lines + +Each line shows: position number, invoice item description, invoiced quantity, unit price including tax, and originating order number. + +### Attachments + +Files attached to the invoice. + +:::note +Invoices are sourced from IFS and cannot be edited in CustomerHUB. +::: diff --git a/docs/customerhub/reference/quotes.md b/docs/customerhub/reference/quotes.md new file mode 100644 index 0000000..1672540 --- /dev/null +++ b/docs/customerhub/reference/quotes.md @@ -0,0 +1,82 @@ +--- +sidebar_position: 3 +title: Quotes +--- + +# Quotes + +The Quotes module manages the full lifecycle of sales quotations, from creation through release, approval, and closure. + +## List view + +**Search filters:** Quotation No, Quotation Name, IFS Status, HUB Status, Quote Type (Transfer Point / Product with Install / Product Only), Customer Contact, Customer, Territory, Region, Tech Id. + +Each result row shows: **Number**, **Name**, **Customer**, **Contact**, **Quote Type**, **IFS Status**, **Hub Status**, **Creation Date**. + +Results are paginated. Use **New Quote +** to create a new quote. + +--- + +## Quote detail + +### Header fields + +- **Quotation No** — auto-generated quote number +- **Customer** — customer this quote is for (required) +- **Customer Contact** — primary contact for this quote (required) +- **Address** — delivery address (required) +- **Responsible Person** — internal owner of the quote (required) +- **Quote Type** — Transfer Point / Product with Install / Product Only (required) +- **Quotation Name** — descriptive name for the quote (required) +- **Pricing Validity** — how long the quoted prices are valid +- **Wanted Delivery Date** — requested delivery date +- **Expiration Date** — date the quote expires +- **Coordinator** — internal coordinator assigned to the quote +- **Formal Proposal Required** — toggle: whether a formal proposal document is needed +- **Risk Assessment** — toggle: whether a risk assessment is required +- **Region** / **Territory** / **Tech Id** — geographic and assignment context +- **Service Contract** — linked service contract, if any +- **Created By** — user who created the quote +- **Ships From Remote Inventory** — toggle: whether items ship from remote stock + +### Summary bar + +Displayed below the header: **Total Value**, **Net Weight**, **Total Install** (hours), and a **Show Section Total** toggle that displays per-section subtotals in the Lines tab. + +### Actions + +- **Save** — save changes to the quote header +- **Cancel Quote** — cancel the quote (sets IFS status to Cancelled) +- **Release** — release the quote to the customer (sets IFS status to Released) + +--- + +## Tabs + +### Lines + +Quote line items organized into sections. Each section can contain one or more product lines. Sections and individual lines can be added or deleted. + +### Quotation Charges + +Additional charges applied to the quote: Charge Type, Charge Group, Charge %, Charge % Basis, Qty, UoM, Tax Liability, Charge Amt. + +### Quotation Details + +Additional metadata in two groups. + +**General:** Customer Agreement, Customer Price Group, Alternative Quote, Credit Limit, Credit Blocked, Probability, Lead Time (Min / Max / Unit). + +**Miscellaneous:** Channel, Created On, Closed Date, Market, Sales Material. + +### Involved Parties + +Contacts associated with this quote: Name, Phone, Mobile, Email, and whether they are the main contact. + +### Photo Gallery + +Photos attached to the quote. + +### Attachments + +Files attached to the quote. diff --git a/docs/customerhub/reference/sales-parts.md b/docs/customerhub/reference/sales-parts.md new file mode 100644 index 0000000..cced0be --- /dev/null +++ b/docs/customerhub/reference/sales-parts.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 8 +title: Sales Parts +--- + +# Sales Parts + +The Sales Parts module is the product catalog — a searchable list of all parts available for quoting and ordering, synchronized with IFS. + +## List view + +Sales Parts has two tabs: **Sales Parts** (the catalog) and **Import from IFS**. + +**Search filters:** Part No or Description, and an **Include Proprietary Parts** toggle (on by default) that adds customer-specific parts to results. + +Each result row shows: **Part No**, **Description**, **Sales Group**, **Product Family**, **UoM**, **Unit Cost**, **List Price**, **Customer Price**, **Net Price**. + +Use **Export To Excel** to download the list. The catalog can contain 20,000+ parts. + +--- + +## Part detail + +### General Information + +- **Part No** — part number +- **Inventory Part** — whether the part is tracked in IFS inventory +- **Proprietary Part** — whether this part is customer-specific +- **Sales Group** — sales group classification +- **Sales Price Group** — pricing group (e.g. Max Discount 30%) +- **Active** — whether the part is available for use +- **Estimated Install Time** — estimated installation time +- **Description** — full part description +- **Unit Cost** / **List Price** / **Unit Price** / **Net Price** — pricing at each level +- **Currency** — pricing currency + +Use **Sync with IFS** to refresh the part data from IFS. + +### Sales Lead Times + +- **Next Day** — available for next-day delivery +- **Three Days** — available within 3 days +- **Five Days** — available within 5 days +- **To Be Scheduled** — requires scheduling diff --git a/docs/customerhub/reference/service-records.md b/docs/customerhub/reference/service-records.md new file mode 100644 index 0000000..a03a3d1 --- /dev/null +++ b/docs/customerhub/reference/service-records.md @@ -0,0 +1,21 @@ +--- +sidebar_position: 9 +title: Service Records +--- + +# Service Records + +The Service Records module provides a cross-customer view of submitted service forms, filtered by form type. It is the reporting layer on top of Forms — the same data, presented for review and export rather than submission. + +## List view + +**Search filters:** Form\* (required — pre-selected on load), Customer, Territory, Region. Use **+ Service Form Question Filters** to filter by specific answers within the form. + +The **Form** filter is required. Results only appear after selecting a form and clicking Search. + +Each result row shows: **Service Date**, **Created By**, **Customer**, **Address**, **Functional Area**, **Customer Base**, **Transfer Point**. + +### Actions + +- **Service Summary** — generate a summary report for the selected records +- **Full Service Report** — generate a full detailed report for the selected records diff --git a/docs/customerhub/reference/time-report.md b/docs/customerhub/reference/time-report.md new file mode 100644 index 0000000..1f3dcb0 --- /dev/null +++ b/docs/customerhub/reference/time-report.md @@ -0,0 +1,23 @@ +--- +sidebar_position: 13 +title: Time Report +--- + +# Time Report + +The Time Report module provides a weekly view of time entries logged against work tasks. It loads automatically for the current week without requiring a search. + +## Filters + +- **From Date / To Date** — date range for the entries shown. Use the **<** and **>** arrows to navigate week by week. +- **Resource** — filter by technician or resource. +- **Total Wage Hours** — total hours for the selected period (read-only). + +## Entries + +Each row shows: **Transaction Date**, **W. Task**, **Time Registration Type**, **Wage Code**, **Resource**, **Customer**, **Hours**, **Daily Total**. + +## Actions + +- **Import All In Range** — import all time entries from IFS for the selected date range +- **Export To Excel** — download the visible entries as a spreadsheet diff --git a/docs/customerhub/reference/visits.md b/docs/customerhub/reference/visits.md new file mode 100644 index 0000000..40882d0 --- /dev/null +++ b/docs/customerhub/reference/visits.md @@ -0,0 +1,34 @@ +--- +sidebar_position: 6 +title: Visits +--- + +# Visits + +The Visits module tracks customer site visits and links them to the quotes, service records, and forms produced during each visit. + +## List view + +**Search filters:** Visit Id, Customer, Territory, Region, Tech Id. + +Each result row shows: **Visit Id**, **Customer** (with IFS ID), **Date**, **Created By**, **Region**, **Territory**, **Tech**. + +Use **Export To Excel** to download the list. + +--- + +## Visit detail + +The detail page groups all work produced during the visit into three sections. + +### Quotes + +Quotes created during this visit. Each row shows the quote number (links to the full quote), customer, address, name, status, amount, and who created it. + +### Service Records + +Service records submitted during this visit. Each row shows form title, name, asset, status, description, form type, and date submitted. + +### Forms + +Forms completed during this visit. Same columns as Service Records. diff --git a/docs/customerhub/reference/work-tasks.md b/docs/customerhub/reference/work-tasks.md new file mode 100644 index 0000000..031587f --- /dev/null +++ b/docs/customerhub/reference/work-tasks.md @@ -0,0 +1,37 @@ +--- +sidebar_position: 12 +title: Work Tasks +--- + +# Work Tasks + +The Work Tasks module tracks field service work tasks linked to work orders and customer orders, synchronized with IFS. + +## List view + +Work Tasks has two tabs: **Work Tasks** and **Work Assignments**. + +**Search filters:** Search Keyword (task number or description), Customer Order No, Work Task Status. + +Each result row shows: **#** (task and work order numbers, links to detail), **Customer**, **Work Type**, **Description**, **Allocations** (total and unassigned), **Asset**, **W. Task Status**, **Assigned**. + +Use **Import From IFS** to pull new work tasks from IFS. + +--- + +## Work Task detail + +- **Work Order No** — parent work order number in IFS +- **Work Task No** — task number +- **Customer Order No** — linked customer order, if any +- **Work Task Status** — current status +- **Customer** — customer this task is for +- **Asset** — asset being serviced +- **Work Type** — type of work +- **Maintenance Priority** — priority level +- **Address** / **City** / **State** / **Country** — site location +- **Territory** / **Region** / **Tech Id** — assignment context +- **Description** — task description +- **Assignment Status** — toggle between Assigned / Unassigned + +Use **Refresh From IFS** to pull the latest task data from IFS. diff --git a/docs/datahub/_category_.json b/docs/datahub/_category_.json new file mode 100644 index 0000000..6c4e4c7 --- /dev/null +++ b/docs/datahub/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "DataHUB", + "position": 5, + "collapsible": true, + "link": { + "type": "generated-index", + "description": "REST API reference for the DataHUB service — endpoints, parameters, and response shapes for extracting HUB data." + } +} diff --git a/docs/datahub/explanation/_category_.json b/docs/datahub/explanation/_category_.json new file mode 100644 index 0000000..26d5636 --- /dev/null +++ b/docs/datahub/explanation/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Explanation", + "position": 1, + "link": { + "type": "generated-index", + "description": "The purpose, roles, and business case behind the DataHUB service." + } +} diff --git a/docs/datahub/explanation/business-case.md b/docs/datahub/explanation/business-case.md new file mode 100644 index 0000000..0be3e67 --- /dev/null +++ b/docs/datahub/explanation/business-case.md @@ -0,0 +1,79 @@ +--- +sidebar_position: 2 +title: Business Case +--- + +# Business Case + +## Preface + +Martin Engineering requires a reliable and standardized mechanism to extract information from HUB that supports its most common day-to-day business processes. The extraction capability should enable retrieval of records based on their created and updated timestamps, allowing downstream systems and integrations to efficiently identify and process new or modified data. + +To address this requirement, we propose the implementation of a DataHUB Service that will act as the central access layer for HUB data extraction. This service will provide a unified and controlled interface for accessing HUB data while leveraging a combination of: + +- Dedicated Service Accounts for system-to-system integrations. +- Standard HUB Role-Based Permissions to enforce data access controls and security policies. + +By adopting this approach, the DataHUB Service will deliver a consistent, secure, and compliant framework for data extraction. Access to data through each endpoint will be governed by the permissions assigned to the service account initiating the request, ensuring that consumers can only retrieve information they are authorized to access. + +This architecture promotes standardization across integrations, simplifies data access management, and provides a scalable foundation for future HUB data extraction requirements. + +--- + +## Business Value + +The proposed DataHUB Service provides a centralized, secure, and standardized mechanism for extracting HUB data, enabling Portal Owners to efficiently support key business processes. By leveraging service accounts and existing HUB permissions, the solution reduces integration complexity, improves data accessibility, strengthens governance and compliance, and ensures that downstream systems can reliably access only the data they are authorized to consume. This approach enhances operational efficiency, supports scalable integrations, and establishes a consistent foundation for future reporting, analytics, and automation initiatives. + +--- + +## Current Process / Workflow + +Currently, Martin Engineering must submit ad hoc requests to HOIST whenever HUB data is required for reporting, integration, or operational purposes. In response, HOIST manually generates and delivers data extracts for the specific entity being requested. + +This process presents several challenges: + +- Manual effort and dependency on HOIST resources for every data request. +- Longer turnaround times, which can delay business operations and decision-making. +- Increased risk of human error during data extraction, preparation, and delivery. +- Lack of standardization, resulting in inconsistent extraction methods and formats. +- Limited scalability, as the process becomes increasingly difficult to manage as data volume and integration needs grow. +- No self-service capability for consuming systems to retrieve data on demand. + +As a result, the current approach is both inefficient and prone to errors, creating operational overhead for both Martin Engineering and HOIST while limiting the organization's ability to access timely and reliable HUB data. + +--- + +## Desired Outcomes & Desired Process / Workflow + +The proposed solution is to implement a secure and standardized DataHUB REST API framework that enables authorized systems to extract HUB data on demand. + +Key objectives include: + +- Development of a suite of REST APIs that expose HUB data sets in a consistent and scalable manner. +- Support for incremental data extraction using `CreatedOn` and `UpdatedOn` timestamps, allowing consumers to retrieve only new or modified records. +- Integration with the existing HUB permission model to control access at the data-set level. + - Example: `Can Extract Visits` permission. +- Enable secure access through service accounts, ensuring all data retrieval is governed by existing authorization controls. + +### Data Sets in Scope + +- Quotes + - Quote → Lines + - Quotes → Charges + - Quotes → Labor Worksheet + - Quotes → Additional Information + - Quotes → Quotation Details +- Visits + - Visits → Quotes + - Visits → Service Records + - Visits → Forms + - Visits → Work Tasks +- Service Records +- Forms + - Forms => Answers +- Time Report +- Form Builder + - Form definition + - Question definitions + +The desired outcome is a self-service, reliable, and secure data extraction capability that eliminates manual data requests while providing efficient access to business-critical HUB information. diff --git a/docs/datahub/explanation/purpose-and-roles.md b/docs/datahub/explanation/purpose-and-roles.md new file mode 100644 index 0000000..230a5ac --- /dev/null +++ b/docs/datahub/explanation/purpose-and-roles.md @@ -0,0 +1,34 @@ +--- +sidebar_position: 1 +title: Purpose & Roles +--- + +# Purpose & Roles + +## Purpose and Guidance + +This document specifies how the defined functions shall be developed or how the application shall be customized to solve the business requirements. + +The **Solution Description** defines what will be delivered. The solution is matched against the requirements described in the Requirements section. + +The **Delimitations** describe what is explicitly not covered by this spec. Together with the Solution description, these sections delimit the extent of the functional addition agreed for implementation. + +The **Business Requirements and References** describe the business problem(s) to be resolved by this HUB spec. This section should be completed by a representative of the business user. The language of this section is aimed at capturing the desired outcomes and is less concerned with how those outcomes will be achieved. + +--- + +## HUB Process Roles and Responsibilities + +### Customer + +- ME to provide Tech from their end for testing + +### Hoist Developer (DEV) + +- Najib El-Husseini (Senior) +- Tiago Pereira (Senior) +- Jaime Mesa (Junior) + +### HUB Delivery Lead + +- Dan Lefebvre diff --git a/docs/datahub/reference/_category_.json b/docs/datahub/reference/_category_.json new file mode 100644 index 0000000..8e8f4ec --- /dev/null +++ b/docs/datahub/reference/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Reference", + "position": 2, + "link": { + "type": "generated-index", + "description": "Endpoint definitions, query parameters, and response shapes for the DataHUB REST API." + } +} diff --git a/docs/datahub/reference/assumptions-and-dependencies.md b/docs/datahub/reference/assumptions-and-dependencies.md new file mode 100644 index 0000000..588ddc0 --- /dev/null +++ b/docs/datahub/reference/assumptions-and-dependencies.md @@ -0,0 +1,30 @@ +--- +sidebar_position: 8 +title: Assumptions, Boundaries & Dependencies +--- + +# Project Assumptions, Boundaries, and Dependencies + +## Scope Delimitations + +The scope of this proposal is limited to the design and implementation of the DataHUB API framework and the data sets explicitly identified within this document. + +The following items are considered out of scope unless specifically approved through a separate change request: + +- Additional data sets or entities not identified in this specification. +- Additional fields, related entities, or expanded data views beyond those defined for the initial release. +- Custom API endpoints created for individual integrations. +- Modifications to existing HUB business processes, workflows, or underlying data structures. +- Reporting, analytics, or dashboard development consuming DataHUB data. +- Changes to user documentation, training materials, and knowledge base content. + +## Dependencies + +Successful delivery of the DataHUB solution is dependent upon: + +- Availability of the required data within HUB. +- Availability of existing HUB permissions and security infrastructure. +- Creation and management of DataHUB service accounts by Portal Owner administrators. +- Network accessibility between DataHUB consumers and HUB environments. +- Validation and approval of exposed data sets by Martin Engineering stakeholders. +- Availability of HUB development, testing, and production environments for deployment and validation activities. diff --git a/docs/datahub/reference/change-log.md b/docs/datahub/reference/change-log.md new file mode 100644 index 0000000..5acb791 --- /dev/null +++ b/docs/datahub/reference/change-log.md @@ -0,0 +1,18 @@ +--- +sidebar_position: 10 +title: Change Log +--- + +# Change Log + +| Date | Change | +|---|---| +| 2026-07-10 | Initial Draft | + +## Document Revision History + +| Revision | Date | Author | Role & Remarks | +|---|---|---|---| +| 1 | 2026-07-10 | Dan Lefebvre | Solution delivery lead | +| | 2026-07-10 | Najib El-Husseini | Initial | +| | 2026-07-10 | Tiago Pereira | Initial | diff --git a/docs/datahub/reference/dataset-details.md b/docs/datahub/reference/dataset-details.md new file mode 100644 index 0000000..397d3a9 --- /dev/null +++ b/docs/datahub/reference/dataset-details.md @@ -0,0 +1,332 @@ +--- +sidebar_position: 3 +title: DataSET Details +--- + +# DataSET Details + +The following data sets will be exposed through the DataHUB APIs. Each data set includes its primary identifiers, key business attributes, and relationships to other HUB entities. + +## Quote + +``` +Quote +├── Quotation No (PK) +├── Customer ID (FK → Customer) +├── Customer Contact +├── Address ID (FK → Customer Address) +├── Responsible Person +├── Quote Type +├── Quotation Name +├── Pricing Validity +├── Wanted Delivery Date +├── Coordinator +├── Formal Proposal Required +├── Territory +├── Tech Id +├── Service Contract +├── Created By +├── Source (MobileHUB, HUB) +└── Customer Agreement +``` + +``` +Quote +├── Quote Line +├── Quote Charge +├── Labor Worksheet +├── Additional Information +└── Quotation Detail +``` + +### Quote → Line + +``` +Quote Line +├── Id (PK) +├── Quotation No (FK → Quote) +├── Line No +├── Adjusted Estimated Installation Time (H) +├── Estimated Installation Time (H) +├── Part Number (FK → Sales Part) +├── Quantity +├── Status +├── Weight +├── Optional +├── List Price +├── Customer Price +├── Discount % +├── Discount Value +└── Total Price +``` + +### Quote → Charge + +``` +Quote Charge +├── Id (PK) +├── Quotation No (FK → Quote) +├── Charge No +├── Charge Type +├── Charge Group +├── Charge % +├── Charge % Basis +├── Qty +├── UoM +├── Tax Liability +└── Charge Amt +``` + +### Quote → Labor Worksheet + +``` +Labor Worksheet +├── Id (PK) +├── Quotation No (FK → Quote) +├── Installation Type +├── Labor Total +├── Equipment Ratio +├── Travel Total +├── Site Required Days +├── Site Specified Days +├── Site Required Hours per Day +├── Firewatch +├── Total Install Hours +└── Total Adjusted Hours +``` + +### Quote → Additional Information + +``` +Additional Information +├── Id (PK) +├── Quotation No (FK → Quote) +├── Proposal Type +├── Type of Upgrade +├── Current Problem +├── Installation Type +├── Available Hours per Day +├── Install Difficulty Factor +├── Install Notes +└── Describe the Scope of Work Requested +``` + +### Quote → Quotation Detail + +``` +Quotation Detail +├── Id (PK) +├── Quotation No (FK → Quote) +├── Customer Agreement +├── Customer Price Group +├── Alternative Quote +├── Credit Blocked +├── Probability +├── Channel +├── Created On +├── Closed Date +├── Market +├── Sales Material +├── Internal Comments +├── Customer Comments +└── Additional Information +``` + +--- + +## Visit + +``` +Visit +├── Visit Id (PK) +├── Customer No (FK → Customer) +├── Customer Address No (FK → Customer Address) +├── Date +└── Created By +``` + +``` +Visit +├── Visit Quote +├── Visit Service Record +├── Visit Form +└── Visit Work Task +``` + +### Visit → Quote + +``` +Visit Quote +├── Id (PK) +├── Visit Id (FK → Visit) +├── Quote No (FK → Quote) +├── Quote Name +├── Quote Status +├── Amount +├── Created By +├── Connected Object No (FK → FunObject) +└── Connected Object Type +``` + +### Visit → Service Record + +``` +Visit Service Record +├── Id (PK) +├── Visit Id (FK → Visit) +├── Object Id (FK → FunObject) +├── Object Name +├── Status +├── Form Name +├── Form Id (FK → Form Builder) +├── Submission Id (FK → Form) +└── Date Submitted +``` + +### Visit → Form + +``` +Visit Form +├── Id (PK) +├── Visit Id (FK → Visit) +├── Form Name +├── Form Id (FK → Form Builder) +├── Submission Id (FK → Form) +├── Connected Object Id (FK → FunObject) +├── Connected Object Type +└── Status +``` + +### Visit → Work Task + +``` +Visit Work Task +├── Id (PK) +├── Visit Id (FK → Visit) +├── Task No (FK → Work Task) +├── Work Type +├── Status +├── Date Submitted +└── Created Date +``` + +--- + +## Service Record + +``` +Service Record +├── Record Id (PK) +├── Object Id (FK → FunObject) +├── Object Level +├── Object Type +├── Form Id (FK → Form Builder) +├── Form Name +├── Service Date +├── Customer Id (FK → Customer) +├── Customer Name +├── Address Id (FK → Customer Address) +├── Address Name +└── Parent Object Id (FK → FunObject) +``` + +**Questions** + +```json +[ + { + "Question Key": "", + "Question Label": "", + "Type": "", + "Answer": "" + } +] +``` + +--- + +## Form + +``` +Form +├── Submission Id (PK) +├── Form Name +├── Customer Id (FK → Customer) +├── Customer Name +├── Form Type +├── Created By +├── Date Submitted +└── Visit +``` + +**Questions** + +```json +[ + { + "Question Key": "", + "Question Label": "", + "Type": "", + "Answer": "" + } +] +``` + +--- + +## Time Report + +``` +Time Report +├── Transaction Id (PK) +├── Transaction Date +├── Created By +├── Time Registration Type +├── Work Task Id (FK → Work Task) +├── Resource Id (FK → Resource) +├── Resource Name +├── Customer Id (FK → Customer) +├── Customer Name +├── Address Id (FK → Customer Address) +├── Address Name +├── Hours +├── Daily Total +├── MSHA +├── Update Needed +└── Status +``` + +--- + +## Form Builder (Form Definition and Question Definitions) + +``` +Form Builder +├── Form Id (PK) +├── Form Name +├── Service Report +├── Created Date +├── Last Update Date +├── Version +├── Active +└── Connect to Visit +``` + +**Sections** + +```json +[ + { + "Section Name": "", + "Repeatable": "", + "Questions": [ + { + "Question Key": "", + "Question Label": "", + "Type": "", + "Answer": "" + } + ] + } +] +``` diff --git a/docs/datahub/reference/estimates.md b/docs/datahub/reference/estimates.md new file mode 100644 index 0000000..420df66 --- /dev/null +++ b/docs/datahub/reference/estimates.md @@ -0,0 +1,39 @@ +--- +sidebar_position: 1 +title: Open Issues & T-Shirt Estimate +--- + +# Open Issues & T-Shirt Estimate + +## Open Issues/Decisions Required + +This specification cannot be finalized until the following issues and decisions are resolved. Each item listed must be cross-referenced with its corresponding entry in the RAID log, HUB register, or other project deliverables tracking system. + +| Issue/Decision | Responsible | Resolution | +|---|---|---| +| | | | + +--- + +## T-Shirt Estimate + +This section is used to specify a rough estimate for the development of the features specified in this HUB Spec. This estimate is given before any detailed business requirements have been captured and will be based on the QTY per type of HUB feature (New Module, Page, Field, Feature), but will not reflect details regarding how difficult or simple the implementation will be. + +### Size / Hours (Guideline only) + +| Size | HUB Type (Example) | Hours | +|---|---|---| +| XS | Extra Small | 4 | +| S | Small | 8 | +| M | Medium | 16 | +| L | Large | 40 | +| XL | Extra Large | 80 | +| EPIC | EPIC | 100+ | + +### HUB T-Shirt Estimates + +| HUB # | Description | HUB Type | Size | +|---|---|---|---| +| 1 | DataHUB | Module | EPIC | + +**Total Hours:** 240+ diff --git a/docs/datahub/reference/overview.md b/docs/datahub/reference/overview.md new file mode 100644 index 0000000..254d945 --- /dev/null +++ b/docs/datahub/reference/overview.md @@ -0,0 +1,32 @@ +--- +sidebar_position: 4 +title: API Overview & Conventions +--- + +# DataHUB REST API — Overview & Conventions + +Spec and user guide for API consumption. Covers endpoints verified against `hub-dev.hoist.tech` as of 2026-08-04. + +**Base URL:** `https://hub-dev.hoist.tech` + +**Auth:** header `X-API-KEY: {{apiKey}}` on every request. + +--- + +## API-Wide Conventions + +These conventions apply across all DataHUB REST endpoints: + +- **Pagination:** `startIndex` (0-based offset) and `maxRecords` (max rows to return). `maxRecords=0` returns the entire matching result set, not zero rows. +- **Identifiers:** each entity uses an `Id` field name (e.g. `VisitId`, `QuoteId`). +- **Response envelope:** results are wrapped in an entity-named array, alongside a `TotalCount` reflecting the total matching the filters — independent of `startIndex`/`maxRecords`. The array key name is specific to each endpoint (see its own page). +- **Optional nested data:** arrays/objects added via `include*`-style flags, or that represent related child records, are omitted entirely from the JSON when empty — they are not returned as `[]` or `null`. Client code must use safe/optional field access. + +:::warning[Known defect — date filters at/after current time] +Any endpoint accepting a `lastUpdated*`-style datetime filter returns an HTTP 500 (`{"Errors":["Error executing query."],"StatusCode":500}`) when the filter value is at or after the current server time, instead of an empty result set. Root cause unknown — no backend logs available to this team; flagged as an open item. +::: + +## Endpoints + +- [Quotes/Search](./quotes-search) +- [Visits/Search](./visits-search) diff --git a/docs/datahub/reference/performance-and-ao.md b/docs/datahub/reference/performance-and-ao.md new file mode 100644 index 0000000..63d6d68 --- /dev/null +++ b/docs/datahub/reference/performance-and-ao.md @@ -0,0 +1,44 @@ +--- +sidebar_position: 9 +title: Performance & AO Considerations +--- + +# Performance & Application Objects (AO) Considerations + +## Performance Considerations + +### Data Rate Considerations + +To ensure platform stability, predictable performance, and fair usage across consumers, the DataHUB service may implement configurable data rate limits at the service account level. + +Rate limiting can be used to: + +- Prevent excessive or unintended API consumption. +- Protect HUB and DataHUB resources from large-volume extraction requests. +- Ensure consistent performance for all API consumers. +- Support differentiated access models for service accounts with varying data consumption requirements. + +Rate limits may be based on factors such as: + +- Requests per minute/hour. +- Number of records returned per request. +- Maximum date range for incremental extraction requests. +- Concurrent requests per service account. + +Specific thresholds will be determined during implementation and may be configured on a per-service-account basis according to business requirements and expected data volumes. + +--- + +## Application Objects (AO) Considerations + +The proposed DataHUB solution is expected to introduce approximately 10 new Application Objects (AOs). + +Current estimates include: + +- 6 REST API AOs to expose the planned DataHUB endpoints. +- 1 Entity AO to manage Service Account configuration, permissions, API keys, and rate-limiting settings. +- Additional supporting AOs for business logic, security, monitoring, and future extensibility. + +Although the initial implementation is currently estimated at 7 primary AOs, a planning estimate of 10 AOs is recommended to accommodate implementation refinements, supporting components, and unforeseen requirements identified during development. + +This estimate provides sufficient flexibility while ensuring the solution remains scalable and maintainable. diff --git a/docs/datahub/reference/quotes-search.md b/docs/datahub/reference/quotes-search.md new file mode 100644 index 0000000..9f0f14e --- /dev/null +++ b/docs/datahub/reference/quotes-search.md @@ -0,0 +1,125 @@ +--- +sidebar_position: 5 +title: Quotes/Search +--- + +# Quotes/Search + +``` +GET /DataHUB/rest/Quotes/Search +``` + +See [API Overview & Conventions](./overview) for pagination, identifiers, and response envelope conventions shared by all endpoints. + +## Query Parameters + +| Param | Type | Required | Description | +|---|---|---|---| +| `startIndex` | int | Yes | 0-based offset. | +| `maxRecords` | int | Yes | Max rows. `0` = all. | +| `lastUpdatedFrom` | ISO 8601 datetime | Yes | Filters `UpdatedOn >= lastUpdatedFrom`. | +| `lastUpdatedTo` | ISO 8601 datetime | No | Filters `UpdatedOn <= lastUpdatedTo`. Combines with `lastUpdatedFrom` as a closed range. | +| `status` | string | No | Filters by quote status name. Valid values: `Released`, `Closed`, `Planned`, `Cancelled`. | +| `site` | string | No | Filters by site `ExternalId` (e.g. `US001`). Invalid values return a clear error (see below). | +| `includeQuoteLines` | bool | No | Adds `QuotationLines[]` to each quote. | +| `includeQuoteCharges` | bool | No | Adds `QuotationCharges[]` to each quote. | +| `includeLaborWorksheet` | bool | No | Adds `LaborWorksheet` to each quote, when one exists. | + +## Example Request + +``` +GET /DataHUB/rest/Quotes/Search?startIndex=0&maxRecords=10&lastUpdatedFrom=2026-05-01T00%3A00%3A00Z&lastUpdatedTo=2026-07-17T23%3A59%3A00Z&status=Released&site=US001&includeQuoteLines=true&includeQuoteCharges=true&includeLaborWorksheet=true +``` + +## Response Shape + +```json +{ + "Quotations": [ { ... } ], + "TotalCount": 311 +} +``` + +### Quotation Object (base, no include flags) + +```json +{ + "QuoteId": 2627, + "QuotationNo": "A1000007", + "QuotationName": "Test RP", + "Customer": { "CustomerNo": "202703", "CustomerName": "21ST CENTURY CONCRETE - HUDSON" }, + "Status": "Released", + "ApprovalStatus": "No Approvals", + "QuoteType": "Product with Install", + "Territory": { "TerritoryId": 185, "ExternalId": "US-1C", "Code": "US-1C", "Description": "Lower Great Lakes" }, + "Region": { "ExternalId": "1", "Description": "Northeast" }, + "Site": { "ExternalId": "US001", "Description": "Neponset" }, + "ResponsiblePerson": { "ExternalId": "AARONL", "Description": "Aaron Lee" }, + "OrderCoordinator": { "ExternalId": "SUSIEO", "Description": "Susie Orlandi" }, + "CancelReason": { "ExternalId": "False", "Description": "False" }, + "ExpirationDate": "2026-06-09", + "DeliveryDate": "2026-04-10", + "MinimumLeadTime": 2, + "MaximumLeadTime": 3, + "LeadTimeUnit": { "ExternalId": "CfEnum_DAYS", "Description": "Days" }, + "CreatedOn": "2026-04-10T11:44:44Z", + "UpdatedOn": "2026-05-02T20:56:45Z", + "HubCreatedBy": "ruwanthika.premalal@hoist.tech", + "HubUpdatedBy": "thomas.soubliere@hoist.tech", + "ShipToAddress": { + "Id": 152972, "Country": "US", "State": "MA", "City": "HUDSON", + "AddressName": "21ST CENTURY CONCRETE", "StreetAddress": "560 MAIN ST", + "ExternalId": "1", "IsDeliveryAddress": true, "IsDefaultDeliveryAddr": true + } +} +``` + +`HubUpdatedBy` holds a user identifier (email); `CreatedOn`/`UpdatedOn` are the date fields. + +### `include*` Flags — Added Fields + +| Flag | Adds field | Notes | +|---|---|---| +| `includeQuoteLines=true` | `QuotationLines[]` | Array of quote line items. | +| `includeQuoteCharges=true` | `QuotationCharges[]` | Array of quote charges. | +| `includeLaborWorksheet=true` | `LaborWorksheet` | Singular object, not an array. Only present when the quote has one. | + +## Pagination & Date Range Behavior (Verified) + +- `startIndex`/`maxRecords`/`maxRecords=0` behave as described in [API Overview & Conventions](./overview). +- `lastUpdatedFrom` + `lastUpdatedTo` together produce a correct closed-range filter (verified: narrower windows return a strict subset of the wider window). + +## Known Issues + +:::danger[1. 500 on lastUpdatedFrom at/after current time] +See [API Overview & Conventions](./overview). +::: + +:::danger[2. 500 when lastUpdatedTo precedes lastUpdatedFrom] +``` +GET /DataHUB/rest/Quotes/Search?...&lastUpdatedFrom=2026-07-17T00%3A00%3A00Z&lastUpdatedTo=2026-05-01T00%3A00%3A00Z +``` +```json +{ "Errors": ["Error executing query."], "StatusCode": 500 } +``` +Expected: an empty result or a 400 validation error, not a 500. Neither date-range edge case (future date, inverted range) is validated before hitting the query engine. +::: + +:::warning[3. status filter validates correctly, but still returns 500 instead of 400] +An invalid `status` value (e.g. `status=99999`) returns a descriptive error, but as an HTTP 500: + +```json +{ "Errors": ["Invalid Quote Status"], "StatusCode": 500 } +``` +::: + +:::warning[4. site filter validates correctly, but still returns 500 instead of 400] +``` +GET /DataHUB/rest/Quotes/Search?...&site=DOES_NOT_EXIST +``` +```json +{ "Errors": ["Invalid Site"], "StatusCode": 500 } +``` + +Valid `site=US001` works as expected. The validation itself is correct; only the status code is questionable (client error reported as a server error). +::: diff --git a/docs/datahub/reference/solution-design.md b/docs/datahub/reference/solution-design.md new file mode 100644 index 0000000..6d164a9 --- /dev/null +++ b/docs/datahub/reference/solution-design.md @@ -0,0 +1,133 @@ +--- +sidebar_position: 2 +title: Unified DataHUB Solution Design +--- + +# Unified DataHUB Solution Design + +## DATAHUB Service Module + +The proposed solution is to introduce a new DataHUB Service Application and Service Module within Service Center. This service will provide a centralized and secure mechanism for extracting data from the existing datasets managed within HOIST HUB Core. + +### Application Architecture + +DataHUB will be implemented as a standalone application, ensuring clear separation of concerns from existing HUB applications. + +This approach will reduce deployment dependencies and allow DataHUB releases to be delivered independently across TST and PROD environments. + +A new Application Type will be introduced within the `HoistHubApplication` static entity: + +``` +DataHUB +``` + +### Security and Permissions + +DataHUB will leverage the existing HUB authorization framework while maintaining its own dedicated permission set for data extraction activities. + +- A dedicated Service Profile will be introduced, containing only permissions related to data extraction. +- Portal Owners will be able to configure and fine-tune the data access granted to each service account. +- This model supports the creation of multiple service accounts with different extraction permissions, enabling controlled access to specific datasets and API endpoints. + +### Service Account Management + +DataHUB APIs will be secured using: + +- Service Account Username and Password authentication. +- A valid API Key. + +Using the HUB user interface, Portal Owner administrators will be able to: + +- Create and deactivate service accounts. +- Assign and manage extraction permissions. +- Generate and regenerate API keys. +- Control access to DataHUB endpoints. + +### API Design + +DataHUB will expose dedicated API endpoints for each major business entity. + +For example, the Quotes endpoint will return a structured JSON response containing related quotation data: + +**Quote Response Structure (QuoteRes)** + +- `QuoteHeaders` — Collection of quotation headers. +- `QuoteLines` — Collection of quotation lines linked to quotation headers. +- `QuoteCharges` — Collection of quotation charges linked to quotation headers. +- Additional related quotation entities as required. + +To improve performance and reduce payload sizes, endpoints will support optional inclusion parameters that allow consumers to request only the data required. + +**Example Request** + +``` +{baseUrl}/DataHub/Quotes +?lastUpdatedFrom=yyyy-MM-ddTHH:mm:ssZ +&includeHeaders=true +&includeLines=true +&includeCharges=false +``` + +**Parameter Defaults** + +- Header-level entities: `true` +- Detail-level entities: `false` + +This approach enables consumers to optimize data transfers while maintaining flexibility in the information returned by each endpoint. + +:::tip[See also] +The finalized endpoint contracts (verified against `hub-dev.hoist.tech`) are documented in [API Overview & Conventions](./overview), [Quotes/Search](./quotes-search), and [Visits/Search](./visits-search). +::: + +### Documentation + +DataHUB will provide comprehensive API documentation through Swagger/OpenAPI, including: + +- Authentication requirements. +- Endpoint definitions. +- Request and response schemas. +- Permission requirements. +- Sample requests and responses. +- Error codes and troubleshooting guidance. + +--- + +## Data Set Expansion and Related Entity Exposure + +The initial DataHUB APIs will expose the primary dataset and its first-level related entities as defined in this proposal. However, additional views or enhancements may be required when Martin Engineering needs access to data from referenced entities beyond the first level. + +For example, a Quote record may contain only a reference to the customer through `CustomerId`: + +``` +Quote +├── Quotation No (PK) +├── Customer Id (FK → Customer) +├── Other Quote Attributes... +``` + +If consumers require customer details such as the customer name, two possible approaches can be considered. + +### Option 1 – Nested Related Entity + +``` +Quote +├── Quotation No (PK) +├── Customer +│ ├── Customer Name +│ ├── Customer Number +│ └── Other Customer Attributes... +└── Other Quote Attributes... +``` + +### Option 2 – Flattened Response Structure + +``` +Quote +├── Quotation No (PK) +├── Customer Name +├── Customer Number +├── Other Customer Attributes... +└── Other Quote Attributes... +``` + +The preferred approach will be determined during implementation based on performance considerations, API usability, payload size, and business requirements. Where necessary, additional views and endpoints may be introduced to expose related entity data while maintaining a consistent and scalable API structure. diff --git a/docs/datahub/reference/test-plan.md b/docs/datahub/reference/test-plan.md new file mode 100644 index 0000000..ebbd66d --- /dev/null +++ b/docs/datahub/reference/test-plan.md @@ -0,0 +1,36 @@ +--- +sidebar_position: 7 +title: Test Plan +--- + +# Test Plan + +The DataHUB solution will undergo functional, security, performance, and user acceptance testing to ensure it meets all business and technical requirements. + +## Functional Testing + +- Validate all API endpoints return the expected data. +- Verify incremental extraction using `CreatedOn` and `UpdatedOn` filters. +- Confirm optional include/exclude parameters function correctly. +- Validate data accuracy against HUB source data. + +## Security & Permissions Testing + +- Verify authentication using service accounts and API keys. +- Confirm users can only access datasets they are authorized to extract. +- Validate account deactivation and API key regeneration scenarios. + +## Performance Testing + +- Test API response times for small, medium, and large data extracts. +- Validate system stability under concurrent requests and expected load. + +## User Acceptance Testing (UAT) + +- Confirm required datasets and fields are available. +- Validate data quality and extraction workflows with Martin Engineering stakeholders. +- Obtain business approval prior to production deployment. + +:::info[Exit Criteria] +All critical defects resolved, test cases successfully completed, and UAT sign-off received. +::: diff --git a/docs/datahub/reference/visits-search.md b/docs/datahub/reference/visits-search.md new file mode 100644 index 0000000..192f17a --- /dev/null +++ b/docs/datahub/reference/visits-search.md @@ -0,0 +1,100 @@ +--- +sidebar_position: 6 +title: Visits/Search +--- + +# Visits/Search + +``` +GET /DataHUB/rest/Visits/Search +``` + +See [API Overview & Conventions](./overview) for pagination, identifiers, and response envelope conventions shared by all endpoints. + +## Query Parameters + +| Param | Type | Required | Description | +|---|---|---|---| +| `startIndex` | int | Yes | 0-based offset into the result set. | +| `maxRecords` | int | Yes | Max rows to return. **`0` returns the entire result set** (no limit), not zero rows. | +| `lastUpdatedFrom` | ISO 8601 datetime | Yes | Filters `Visit.UpdateAt >= lastUpdatedFrom`. | + +## Example Request + +``` +GET /DataHUB/rest/Visits/Search?startIndex=0&maxRecords=10&lastUpdatedFrom=2026-01-01T00%3A00%3A00Z +``` + +## Response Shape + +```json +{ + "Vistations": [ { ... } ], + "TotalCount": 61 +} +``` + +### Visit Object + +```json +{ + "VisitId": 173, + "Guid": "c147f3eb-3a8b-46a2-9ef7-e6d7e2f38610", + "Company": { "ExternalId": "201191", "Description": "ATLAS SAND - KERMIT" }, + "Address": { + "Id": 149104, + "ExternalId": "1", + "AddressName": "ATLAS SAND - KERMIT", + "StreetAddress": "15456 N FM 874", + "City": "KERMIT", + "State": "TX", + "Country": "US", + "PostalCode": "79745" + }, + "Site": { "ExternalId": "US001", "Description": "Neponset" }, + "HubCreatedBy": "AdminUserDev@hoist.tech", + "CreatedOn": "2026-04-06T20:07:51Z", + "UpdatedOn": "2026-04-07T13:46:28Z", + "Quotes": [ + { "Id": 2617, "Number": "A1000002", "Name": "Test DL 1", "Status": "Released", "Amount": 0.5 } + ], + "ServiceRecords": [ { "...": "..." } ], + "WorkTasks": [ { "...": "..." } ] +} +``` + +**Fields:** + +| Field | Notes | +|---|---| +| `VisitId` | Integer visit identifier. | +| `Guid` | Visit GUID. | +| `Company` | `{ExternalId, Description}`. | +| `Address` | Full address object. | +| `Site` | `{ExternalId, Description}`. | +| `HubCreatedBy` | Creator's email. | +| `CreatedOn` | ISO 8601 datetime with `T`/`Z`. | +| `UpdatedOn` | ISO 8601 datetime with `T`/`Z`. This is the field `lastUpdatedFrom` filters against. | +| `Quotes` | Array, present when the visit has associated quotes. | +| `ServiceRecords` | Array, present only when non-empty. | +| `WorkTasks` | Array, present only when non-empty. Nested `HubCreatedAt`/`HubUpdatedAt` inside `WorkTasks` use a different format (`"2026-04-21 18:46:45"`, no `T`/`Z`) than the top-level Visit dates — handle both formats when parsing. | + +## Pagination Behavior (Verified) + +- Ordering: `ORDER BY [Id]`, ascending. +- `startIndex`/`maxRecords` map to SQL `OFFSET @Skip ROWS FETCH NEXT @MaxRecords ROWS ONLY`. +- `maxRecords=0` bypasses `OFFSET/FETCH` and returns the full matching set. +- `startIndex` beyond `TotalCount` returns `"Vistations": []` with `TotalCount` unchanged — no error. + +## Known Issue + +:::danger[500 Internal Server Error on lastUpdatedFrom at or after the current server time] +``` +GET /DataHUB/rest/Visits/Search?startIndex=0&maxRecords=0&lastUpdatedFrom=2026-08-04T00%3A00%3A00Z +``` +```json +{ "Errors": ["Error executing query."], "StatusCode": 500 } +``` + +Expected: an empty result set (`"Vistations": []`), since no records can have been updated in the future. Reproduced with both "today" and far-future dates. +::: diff --git a/docs/intro.mdx b/docs/intro.mdx index eed6cef..e41b655 100644 --- a/docs/intro.mdx +++ b/docs/intro.mdx @@ -11,6 +11,16 @@ Use the sections below to find what you need. --- +## [CustomerHUB](/docs/customerhub/explanation/what-is-customerhub) + +User documentation for the CustomerHUB application — the operational portal built on HOIST HUB. + +- **Explanation** — What CustomerHUB is and how it connects to IFS +- **Reference** — Field-by-field documentation for Dashboard and Customers +- **How-to Guides** — Find a customer, import from IFS, and more + +--- + ## [HOIST HUB](/docs/hoist-hub/ifs-integration) Technical documentation for the HOIST HUB platform itself. @@ -19,6 +29,15 @@ Technical documentation for the HOIST HUB platform itself. --- +## [DataHUB](/docs/datahub/explanation/purpose-and-roles) + +REST API for extracting HUB data — built for Martin Engineering as a self-service alternative to ad hoc data requests. + +- **Explanation** — Purpose, roles, and the business case for the DataHUB service +- **Reference** — Solution design, dataset structures, API endpoints (Quotes/Search, Visits/Search), test plan, and delivery estimates + +--- + ## [HOIST HUB Documentation Standard](/docs/hub-documentation/explanation/purpose) The standard that defines how HUB specs are written, structured, and approved. If you are authoring or reviewing a HUB spec, start here. diff --git a/docusaurus.config.ts b/docusaurus.config.ts index dc1cf69..571c729 100644 --- a/docusaurus.config.ts +++ b/docusaurus.config.ts @@ -75,7 +75,7 @@ const config: Config = { respectPrefersColorScheme: true, }, navbar: { - title: 'HOIST HUB Docs', + title: undefined, logo: { alt: 'HOIST Logo', src: 'img/hoist-logo.avif', @@ -97,11 +97,11 @@ const config: Config = { items: [ { label: 'Overview', - to: '/docs/hub-documentation/overview/purpose', + to: '/docs/hub-documentation/explanation/purpose', }, { label: 'IFS Integration', - to: '/docs/hub-documentation/integration/ifs-integration', + to: '/docs/hoist-hub/ifs-integration', }, ], },