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,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