Overview
CASE SENSITIVITY
- All Parameter Names are case sensitive.
- Parameters using accepting a “True” value need to match the capitalization.
- Exact, Like, and List parameters are NOT case sensitive.
SPECIAL CHARACTERS
- Any List filer will not return expected results if the name contains a comma.
- Beware of the long dash when copying and pasting from Word. “-” is not the same as “–” and can be had to spot.
- Beware of leading or trailing spaces. Also beware of double space.
- Parameters should be URL encoded to avoid issues.
- Certain characters such as **“ ‘ & / ** may be problematic when included in parameter names.
EMPTY PARAMETERS
- Empty parameters should be removed in most cases it does not matter, but a few like TimeZoneOffest will give an error if an empty value is passed.
Date Range Filters
There are three types of dates that can used to limit the scope of data returned:
| Date Type | Description | Use Case |
|---|---|---|
| Submitted Date | The DateTime the “Submit” button was pressed by the Operator. | Submitted Date is based on the goal of reporting on when a record activity was completed. |
| Processed Date | The DateTime the System Processed the Record and saved the data. | Processed Date is best used for maintaining a data warehouse. This ensures the most recently added records can be retrieved. This is because Offline mode means that Submitted data is not when it was added to the database. For example, requesting all records submitted in the last hour does not guarantee that all records have been processed. |
| Modified Date | The Last Date the record was modified. | Modified Date may be needed or changed to records need to be exported to maintain a warehouse. Note: all records have a modification that as a minimum aligns with the submitted datetime. If modified date is used a record that was pulled previously may be included in a subsequent call. If this data is being inserted into a data warehouse you may need to add logic to replace or update that records in your data warehouse. |
Note:
The Modified Date is less performant than Submitted Date or Processed Date because the history data must be processed to set the last modified date.
Start and End Dates
Each of the three data times supports a Start and End suffix, For Example SubmittedStart ModifedEnd
The supported date format is “yyyy-MM-DD HH:mm:ss” for example 2021-10-01 23:05:00
If the End Time is omitted, then all records from the Start Time to the Current Time are returned.
If the Start Time is omitted all records before the end time are returned (rarely used).
Important
Do not use Start and End Dates when using MinAgo (Slide Time Scale); they cannot be used together.
Slide Time Scale
A sliding Time Scale of “Minutes Ago” is supported. This will return all records between the end time and a time established by subtracting the minutes ago. If no End Date is provided, the current datetime is used. For example: “SubmittedMinAgo=5 ” returns all records submitted in the last 5 minutes. (assuming they are available in the system).
Setting an End Date will return all records Submitted between the End Date - Minutes ago, and the End Date. For Example: SubmittedEnd = 2021-01-01 23:00:00 & SubmittedMinAgo = 60 will return all records between 22:00 and 23:00 on January first.
Note:
- When using a SubmittedEnd Date the time zone offset does not apply so all end dates must be in UTC.
- Do convert days to minutes, Multiply by 1440. Example: 2880 is 2 days.
Time Zone Offset
All dates are stored in a UTC time zone. A “TimeZoneOffset” parameter allows you to define the number of hours to offset from UTC adjust the date time values. The offset applies to all filter input parameters, as well as all date and time output parameters.
Note:
The Default is 0
| Time | Eastern | Central | Mountain | Pacific | Alaska | Hawaii |
|---|---|---|---|---|---|---|
| Standard | -5 | -6 | -7 | -8 | -9 | -11 |
| Daylight | -4 | -5 | -6 | -7 | -8 | -10 |
Exact Filters
Exact Filters request records based on key attributes of records. The Filters are additive with an AND conditions so adding more filters further restricts the results set. Exact Filters are faster than the _Like or _List filter and should be used wherever possible to narrow the scope of records returned.
| Parameter | Description |
|---|---|
| FormName | Exact Form Name |
| ResourceName | Exact Resource Name |
| LocationName | Exact Location Name |
| IdentifierName | The FieldName of an Identifier. Example "Lot' |
| IdentifierValue | The Value of an Identifier that corresponds to the Identifier name. Identifier Name and Value are used together |
| RecordNumber | Record Number. Returns a Single Record |
| RecordCompliance | Returns Records Where compliance is True of False. NOTE that records with No Compliance are assumed to be "True" |
| IsSigned | Returns any record that has a SignOff or Validation |
Like Filters
Like filters allows you search key attributes for a partial match on the name using a "Contains” match on any part of the parameter’s name. Like Filters are SLOWER than Exact.
| Parameter | Description |
|---|---|
| FormLike | Form Name 'Contains'. Example 'Check' Returns any Form that contains 'Check' |
| ResourceLike | Resource Name 'Contains'. Example: 'Apple' Returns All Resources that contain Apple |
| LocationLike | Location Name 'Contains': Example: . 'USA-' Returns all Locations that contain 'USA-' in the name. |
| isVerified | Filters the results to only records that have been signed or verified when the filter is set to "True". |
Note:
The List filter will not return expected results if an attribute name contains a comma.
...