Files
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

101 lines
3.1 KiB
Markdown

---
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.
:::