- 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.
101 lines
3.1 KiB
Markdown
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.
|
|
:::
|