- 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.
4.6 KiB
sidebar_position, title
| sidebar_position | title |
|---|---|
| 2 | 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, Quotes/Search, and 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.