WebService REST - Options for Fields
How to search and filter in the database
By field
In the HTTP requests, you can do a search/filter on one or several fields of the Service Manager database by using the names of corresponding objects. However, you cannot use only once the same object in the same request (the union is not possible).
Syntax
- (prefix_object_name_x.): Prefix to be only indicated when the wished object is contained in another object.
- object_name_x: Name of the used object. Mandatory parameter.
- object_name_value_x: Value of the used object. Mandatory parameter.
Examples
Correct requests
/assets?search=asset_tag:"1012D"
/assets?search=employee.last_name:"Taverner, David"
/assets?search=department.department_en:"Finance"
/requests?search=department.department_en:"Industry"
/requests?search=status.status_en:"Closed"
/requests?search=status.status_en:"In Progress",submit_date_ut:this_week&sort=recipient.last_name+asc
/requests?search=recipient.last_name:"Morley, Gaby"
/requests?search=requestor.last_name:"Morley, Gaby"
/requests?search=recipient.last_name:"Morley, frédérique",status.status_en:"In Progress"
/requests?search=recipient.e_mail:fpachelbel@evtry.com,status.status_en:"Escalated"
/requests?search=recipient.e_mail:adam@evtry.com,status.status_en:"In Progress",submit_date_ut:today
/requests?search=recipient.last_name:"Adam, George",status.status_en:"Closed",submit_date_ut:this_year
/requests?search=recipient.last_name:"Adam, George",status.status_en:"In Progress",submit_date_ut:this_week&sort=submit_date_ut+asc
Incorrect requests
/requests?search=recipient.e_mail:adam@evtry.com,recipient.e_mail:morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&morley@evtry.com
/requests?search=recipient.e_mail:adam@evtry.com&recipient.e_mail:morley@evtry.com
By date
Note: The expected date format is that employed by the logged-in Service Manager REST API user.
- Filtering by date can be carried out in all Date fields.
- Date intervals are inclusive.
- You can use predefined intervals.
See the list and examples.
- You can use specific intervals.
See the list and examples.
Predefined intervals
Note : The values are not case sensitives.
- this_year
- this_month
- this_week
- this_day / today
- last_year
- last_month
- last_week
- first_quarter / Q1
- second_quarter / Q2
- third_quarter / Q3
- fourth_quarter / last_quarter/ Q4
- next_day / tomorrow
- next_week
- next_month
- next_year
- daysbefore
- daysafter
example
search=SUBMIT_DATE_UT:3daysbefore
Specific intervals
By date
example Requests created from 07/09/2020 to 07/10/2020
Result:
"RFC_NUMBER": "I200709_000001",
"SUBMIT_DATE_UT": "2020-07-09T04:34:59.593-04:00"
}
By date and hour
example Requests created from 07/09/2020 12:00 am to 07/10/2020 11:59 pm
Result: 04:34:59.593 is corresponding to 08:34 am in UT hour
"RFC_NUMBER": "I200709_000001",
"SUBMIT_DATE_UT": "2020-07-09T04:34:59.593-04:00"
}
example Requests created from 07/09/2020 12:30 pm to 07/09/2020 12:35 pm in the -4 hours time zone
Result : 04:34:59.593 is corresponding to 08:34 am in UT hour in the -4 hours time zone
"RFC_NUMBER": "I200709_000001",
"SUBMIT_DATE_UT": "2020-07-09T04:34:59.593-04:00"
}
Formats for the date
Many options are available to format all the dates / hours and timezone information by using the formatDate parameter in the HTTP request string.
When you use this parameter, new fields suffixed by _FORMAT will be added in the string HTTP result to display the date in the format you want.
Notes
- All Date fields can be formated.
example LAST_UPDATE, MAX_RESOLUTION_DATE_UT
- The same date formatting applies to all fields specified in the HTTP request string.
Caution
- This parameter is only used to display the date in the format you want. It does not allow you to filter information on a date. To do this, use the search parameter when the method allows it.
Examples
Formats for the date
Format | Result |
---|---|
formatDate = l/M/Y |
Friday/Nov/2018 |
formatDate = l jS \of F Y h:i:s A |
Friday 16th of November 2018 12:00:00 AM |
formatDate=Y-m-d H:i:s |
2018-03-10 17:16:18 |
Using the formatDate parameter
Without Date fields formatting
Result:
"HREF": "https://{your_server}/api/v1/{your_account}/requests?max_rows=1&fields=LAST_UPDATE,MAX_RESOLUTION_DATE_UT"
"record_count": "1",
"total_record_count": "13818",
"records": [
{
"HREF": "https://{your_server}/api/v1/{your_account}/requests/000002",
"RFC_NUMBER": "000002",
"LAST_UPDATE": "2018-11-01T06:17:46.297-05:00",
"MAX_RESOLUTION_DATE_UT": "2018-11-04T20:00:00.000-04:00"
}
]
}
With Date fields formatting
Result: LAST_UPDATE_FORMAT and MAX_RESOLUTION_DATE_UT_FORMAT will be added with the desired date formatting.
"HREF": "https:// {your_server}/api/v1/{your_account}/requests?max_rows=1&fields=LAST_UPDATE,MAX_RESOLUTION_DATE_UT&formatDate=l/M/Y"
"record_count": "1",
"total_record_count": "13818",
"records": [
{
"HREF": "https:// {your_server}/api/v1/{your_account}/requests/000002",
"RFC_NUMBER": "000002",
"LAST_UPDATE": "2018-11-01T06:17:46.297-05:00",
"MAX_RESOLUTION_DATE_UT": "2018-11-04T20:00:00.000-04:00",
"LAST_UPDATE_FORMAT": "Thursday/Nov/2018",
"MAX_RESOLUTION_DATE_UT_FORMAT": "Sunday/Nov/2018"
}
]
}
Formatting options
Day
Format | Description | Example | ||
---|---|---|---|---|
d | Day of the month as a number
|
01 to 31 | ||
D | Short name of the day
|
Sun (Sunday) to Sat (Saturday) | ||
j | Day of the month as a number
|
1 to 31 | ||
l
(lowercase L) |
Full name of the day | Sunday to Saturday | ||
N | ISO-8601 day of the month as a number
|
1 (Monday) to 7 (Sunday) | ||
S | Ordinal suffix for the number of the day: st, nd, rd ou th
|
1st, 2nd, 3rd, 4th | ||
w | Day of the week as a number
|
0 (Sunday) to 6 (Saturday) | ||
z | Day of the year as a number
|
0 to 365 |
Week
Format | Description | Example | ||
---|---|---|---|---|
W | ISO-8601 week of the year as a number
|
42 = 42th week of the year |
Month
Format | Description | Example | ||
---|---|---|---|---|
F | Full name of the month | January to December | ||
m | Month of the year as a number
|
01 (January) to 12 (December) | ||
M | Short name of the month
|
Jan (January) to Dec (December) | ||
n | Month of the year as a number
|
1 (January) to 12 (December) | ||
t | Number of days in the month | 28 to 31 |
Year
Format | Description | Example | ||
---|---|---|---|---|
L | Leap year | 0 = Non-leap year ; 1 = Leap year | ||
o | ISO-8601 year | 1999 ; 2003 | ||
Y | Year as a 4-digit number | 1999 ; 2003 | ||
y | Year as a 2-digit number | 99 ; 03 |
Hour
Format | Description | Example | ||
---|---|---|---|---|
a | Lowercase am (ante meridiem = before noon) or pm (post meridiem = after noon) after the hours | 15am ; 15pm | ||
A | Uppercase AM (ante meridiem = before noon) or PM (post meridiem = after noon) after the hours | 15AM ; 15PM | ||
B | Swatch Internet Time (SIT) | 000 to 999 | ||
g | 12-hour format of an hour
|
1 to 12 | ||
G | 24-hour format of an hour
|
0 to 23 | ||
h | 12-hour format of an hour
|
01 to 12 | ||
H | 24-hour format of an hour
|
01 to 23 | ||
i | Minute
|
00 to 59 | ||
s | Second
|
00 to 59 | ||
u | Microsecond | 654321 | ||
v | Millisecond | 654 |
Full Date / Hour
Format | Description | Example | ||
---|---|---|---|---|
c | ISO-8601 date | 2004-02-12T15 :19 :21+00 :00 | ||
r | RFC 2822 formatted date | Thu, 21 Dec 2000 16 :01 :07+0200 | ||
U | Number of seconds since the Unix Epoch
|
3/5/2019 at 15:44:18 = 1551800658 seconds |
Timezone
Format | Description | Example | ||
---|---|---|---|---|
e | Timezone identifier | UTC ; GMT ; Atlantic/Azores | ||
I
(capital i) |
Standard time or daylights savings time | 0 = Standard time ; 1 = Daylights savings time | ||
O | Timezone difference to Greenwich time (GMT) in hours | +0200 | ||
P | Timezone difference to Greenwich time (GMT) in hours:minutes | +02:00 | ||
T | Timezone abbreviation | EST ; MDT | ||
Z | Timezone offset from UTC (Universal Coordinated Time) in seconds
|
-43200 to 50400 |