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.
This commit is contained in:
1 parent
d1251a5f05
commit
928a4451f7
38 files changed
+1725
-3
No files matched your search
@@ -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."
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"label": "Explanation",
|
||||
"position": 1,
|
||||
"link": {
|
||||
"type": "generated-index",
|
||||
"description": "The purpose, roles, and business case behind the DataHUB service."
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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
|
||||
@@ -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."
|
||||
}
|
||||
}
|
||||
@@ -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.
|
||||
@@ -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 |
|
||||
@@ -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": ""
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
@@ -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+
|
||||
@@ -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 `<Entity>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)
|
||||
@@ -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.
|
||||
@@ -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).
|
||||
:::
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
:::
|
||||
@@ -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.
|
||||
:::
|
||||
Reference in new issue
Block a user