Fix paging when the ordering field is not a plain UTC string

[rolandbanks]

Addresses #74, originally reported by @jamesmanning in #25.

The problem

Paging read the ordering field with ToString() and concatenated "Z" onto it. That breaks in two ways once sysparm_display_value is involved.

With sysparm_display_value=all every field is returned as a { display_value, value } object, so ToString() yields JSON and the parse throws, taking the whole query with it. This is the failure reported in #25.

Less obviously, Newtonsoft recognises ISO-8601 text while deserialising and converts it to a DateTime before the client ever sees it, shifting it to the host's local timezone. ToString() then renders it in the host's culture:

returned:  2026-01-02T05:00:00+05:00     true instant: 2026-01-02 00:00:00Z
ToString:  02/01/2026 07:00:00           shifted to host local, rendered dd/MM/yyyy
parsed:    2026-02-01 07:00:00Z          invariant culture reads 02/01 as 1 February

The paging window ends up a month out, with no error raised. Being host-dependent, this behaves differently on a UTC build agent than on a developer machine, which makes it easy to miss.

Appending "Z" is separately wrong for any value that already carries an offset, since it produces an unparseable string.

The change

ParsePagingFieldValue now:

1. Unwraps { display_value, value }, preferring the raw value, which carries the underlying UTC timestamp
2. Takes Date tokens as dates, avoiding the ToString() round-trip that introduced the host's culture and timezone
3. Parses any remaining string with InvariantCulture and AssumeUniversal | AdjustToUniversal, instead of concatenating "Z"
4. Raises a ServiceNowApiException naming the field and the offending value when the ordering field cannot be interpreted, rather than a bare FormatException surfacing from inside a Max()

Testing

Adds PagingFieldParsingTests (5 cases) and extracts StubServiceNowHandler into its own file so both paging test classes can share it. The stub now records request URIs, so a test can assert on the paging window actually sent rather than only on the rows returned.

These are credential-free and run in CI.

Verified against the previous behaviour: reverting the parse makes 4 of the 5 new cases fail. The fifth, PlainUtcPagingField_StillPagesAsBefore, passes either way, which is the point: the common case is unchanged.

Verified against a live instance: the same multi-page query run with sysparm_display_value unset, =true and =all now returns the same 5,410 rows in all three modes. The all run is the one that previously died.

Notes

• The instance used for the live check has a session user on UTC, so its display and raw values are identical. Whether a non-UTC session user shifts the paging window is therefore untested, and is deliberately not addressed here. See the note in Paging misparses the ordering field when sysparm_display_value is set #74.
• This supersedes add support so using sysparm_display_value=all doesn't cause parsing exceptions during query #24, which proposed falling back to DateTimeOffset.MinValue on a parse failure. That interacts badly with the termination logic: if every row in a page fails to parse, the window cannot advance, producing either a spurious "paging window has not increased" error or a silently truncated result. The DateTimeStyles.AssumeUniversal idea from that PR is carried forward.

[codacy-production]

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 22 complexity · 7 duplication

Metric	Results
Complexity	22
Duplication	7

View in Codacy

AI Reviewer: run a review on demand. To trigger the first review automatically, go to your organization or repository integration settings. AI can make mistakes. Always validate suggestions.

_{TIP This summary will be updated as you push new changes.}