Files
wiki-hoist/docs/datahub/reference/solution-design.md
T
jaime.meza 928a4451f7 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.
2026-11-17 10:42:21 -05:00

134 lines
4.6 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
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.