- Available Since API Version – 2.0\
The DateTimeField type is used to represent date and time fields in Maximizer. DateTimeField objects contain the following properties:
-
Value - A string value containing the date value of the field in ISO8601 format.\
-
DisplayValue - A string value containing the date value formatted for display in the current user's locale, as specified in their user preferences.\
Basic Read Request
The highlighted portion of the following example illustrates the syntax for a request for the default value of a DateTimeField in a Read method call.
This example illustrates the return value for a date user-defined field, which only stores the date with day-level precision, so the returned date does not have a time component.
Request
{
"Token":"{{Token}}",
"AbEntry":{
"Criteria":{
"SearchQuery":{
"CompanyName":{
"$EQ":"Delta Bike Company"
}
}
},
"Scope":{
"Fields":{
"Key":1,
"Udf/$NAME(Contract Start Date)":1
}
}
}
}
Response
{
"Code":0,
"AbEntry":{
"Data":[
{
"Key":"Q29tcGFueQlERU1PXzRDCTA=",
"Udf/$NAME(Contract Start Date)":"2017-08-24"
}
]
}
}
Detailed Read Request
The following example illustrates the syntax for a request for all properties of a DateTimeField in a Read method call.
This example illustrates the return value for the CreationDate system field, which stores the date with second-level precision, so the returned date does include the time component.
Request
{
"Token":"{{Token}}",
"AbEntry":{
"Criteria":{
"SearchQuery":{
"CompanyName":{
"$EQ":"Delta Bike Company"
}
}
},
"Scope":{
"Fields":{
"Key":1,
"CreationDate":{
"Value":1,
"DisplayValue":1
}
}
}
}
}
Response
{
"Code":0,
"AbEntry":{
"Data":[
{
"Key":"Q29tcGFueQlERU1PXzRDCTA=",
"CreationDate":{
"Value":"2015-01-20T20:37:51Z",
"DisplayValue":"January 20, 2015 8:37 PM"
}
}
]
}
}
Basic Create/Update Request
The following example illustrates the syntax for including a DateTimeField in a Create or Update method call.
Request
{
"Token":"{{Token}}",
"AbEntry":{
"Data":{
"Key":"{{AbEntryKey}}",
"Udf/$NAME(Contract Start Date)":"2019-01-01"
}
}
}
Response
{
"Code":0,
"AbEntry":{
"Data":{
"Key":"Q29tcGFueQkxOTA5MTcyNTA5MTgxNTE3MDA0MzBDCTA=",
"Udf/$NAME(Contract Start Date)":"2019-01-01"
}
}
}
Detailed Create/Update Request
The following example illustrates the syntax for including a DateTimeField in a Create or Update method call.
Request
{
"Token":"{{Token}}",
"AbEntry":{
"Data":{
"Key":"{{AbEntryKey}}",
"Udf/$NAME(Contract Start Date)":{
"Value":"2011-03-12",
"DisplayValue":"March 12, 2011"
}
}
}
}
Response
{
"Code":0,
"AbEntry":{
"Data":{
"Key":"Q29tcGFueQkxOTA5MTcyNTA5MTgxNTE3MDA0MzBDCTA=",
"Udf/$NAME(Contract Start Date)":{
"Value":"2011-03-12",
"DisplayValue":"March 12, 2011"
}
}
}
}
Common Pitfalls
The following are some examples that illustrate incorrect syntax for including DateTimeField in requests.
Invalid Create/Update Request - Integer-Valued Value
The default Value property of a DateTimeField is an ISO8601-formatted string. Numeric types are not valid, even if the Value in question is a numeric representation of a timestamp. In the example below, the call will fail because the Value is passed as an integer representation of a timestamp.
{
"Token":"{{Token}}",
"AbEntry":{
"Data":{
"Key":"{{AbEntryKey}}",
"Udf/$NAME(Contract Start Date)": 1299888000
}
}
}
Invalid Create/Update Request - Invalid Date Format
The Value of a DateTimeField is an ISO8601-formatted string. Non-date-format strings are not accepted. Some date strings in other formats may be accepted if they can be parsed to a date value; however, the behaviour may be unexpected if the supplied format cannot be parsed or is ambiguous, and should therefore not be used.
In the example below, the call will succeed because the value of the field is passed as a parseable date string. However the result may be unexpected, because the supplied date format string is ambiguous, and could be interpreted as "MM/DD/YY", "DD/MM/YY", "YY/MM/DD", all of which would yield different results.
{
"Token":"{{Token}}",
"AbEntry":{
"Data":{
"Key":"{{AbEntryKey}}",
"Udf/$NAME(Contract Start Date)": "03/12/11"
}
}
}
Invalid Create/Update Request - Missing Value
When setting the value for a DateTimeField, you must use the Value of the value that you want to set. Passing only the DisplayValue will result in the value not being set correctly. In the example below, the call will fail because the Value is missing from the request.
{
"Token":"{{Token}}",
"AbEntry":{
"Data":{
"Key":"{{AbEntryKey}}",
"Udf/$NAME(Contract Start Date)":{
"DisplayValue":"March 12, 2011"
}
}
}
}
Invalid Create/Update Request - Mismatched Value and DisplayValue
When setting the value for a DateTimeField in a Create or Update request, only the Value property of the field is observed. In the example below, a DisplayValue is passed that does not match the supplied Value. This request will succeed; however it may have unintended effects, as the value of the field will be set to the supplied Value, and the DisplayValue will be ignored.
{
"Token":"{{Token}}",
"AbEntry":{
"Data":{
"Key":"{{AbEntryKey}}",
"Udf/$NAME(Contract Start Date)":{
"Value":"2011-12-03",
"DisplayValue":"March 12, 2011"
}
}
}
}