Cannot store document after update to 2025.06: not supported date value

Data Services Query API
,
1

When trying to store an a12 document I get the error

java.lang.String is not supported date value

I may be mistaken, but I think the problem is that we set a date field using a string

documentV2.withFieldValue(“/…long_path…/DateOfBirth”, “2024-02-15”)

That used to work in 2024.06, but now fails in com.mgmtp.a12.dataservices.utils.internal.DateTimeUtils#getTemporalAccessor

2

and when I use a Java LocalDate instead of String, I just get a different error:

“Failed to set field with path /…/DateOfBirth of type DateType(format=yyyy-MM-dd, youngerThan1900Check=false, datePrecision=FULL, notInDCustomFormat=Optional.empty) to 2024-02-15”

EDIT: Sorry, that was how our app wrapped the error.
The error message from A12 is

unexpected type of BasicTypeV2 value: class java.time.LocalDate (value: 2024-02-15)

3

Hi @stephen-warm-graph,
because of documentV2, I assume that you are using the DocumentV2 API. If so, the values which should be set in the document must be typed, in this case you need an instance of Instant.

4

Thanks for the quick answer!
I have so many questions though:

  • How is a date an instant? A date specifies a specific day/month/year without specifying any timezone.

    • Do I convert it to the time at the start of that specific day in UTC timezone? Will it work correctly in other time zones?
    • Or maybe better use 12:00:00 for the time component to be sure it converts back to the correct day regardless of time zone?

  • This is a breaking change in my opinion. In 2024.06 the way to set a value to a date field was to specify it as a date string in iso format, like ‘2024-02-15’.

    • Was it just an unintentionally made, undocumented breaking change?
    • Or is it documented somewhere?
    • Or do you not consider it breaking just because the method signature of DocumentV2.withFieldValue() did not change?
5

@stephen-warm-graph: regarding to your questions related to Instant:

  • The use of an object for a date field in a document has the intention that the user (and also A12 internal) can easily perform further operations on that value, e.g. check if it is in the past / future, compute the difference in days / months / years between two such values, etc.
  • To create the corresponding Instant-value, the method IDmAwareDocService#convertToJavaTypeV2 should be used.

Regarding to your questions related to the breaking change:
With the introduction of the DocumentV2 API (2024.06), the idea was (and still is) to always have typed values in the document, in this section of the Kernel documentation for developers the supported types are listed. Since in A12 an Instant-object is expected for a date field, in this case, there is no (breaking) change at all.
I will create a ticket to improve the documentation.

6

Thanks for the answer! I got it working.

A couple of remarks:

  • Regarding the terminology of a breaking change:
    I can see your point, which basically is “It was not documented before, so it was incidental that it worked.”
    My perspective is simply: “The application worked fine before the update, but was broken afterwards.”

  • It would be much nicer if DocumentV2.withFieldValue() would fail-fast instead of accepting a data type that will later cause the document persist to fail.

  • The JavaDoc of IDmAwareDocService could really mention how I can get hold of an instance of it!
    (I had the same issue in the past with many other A12 API classes.)
    I found out that I can do
    IDmAwareDocService dmAwareDocService = documentServiceFactory.createDmAwareDocService(documentV2.getDocumentModelId());
    and later call
    value = dmAwareDocService.convertToJavaTypeV2(fieldPath, textValue, (RankedNotification it) -> {});
    All in all, this seems like overkill because I already have both the document model and the field at hand. (So there is really no need for the indirections by dm id and field path. Also I am not interested in any RankedNotification. )
    I guess if this turns out to be a performance problem, I can at least cache the service by dm.

  • A consistent terminology in source code would be nice.
    The path of a field is named completely differently in different places:

    • “path” (e.g. IDocumentModelSearchService.getByPath() - this one makes the most sense, ny my opinion)
    • “fieldFullName” (e.g. dmAwareDocService.convertToJavaTypeV2())
    • “pointer” (e.g. documentV2.withFieldValue() - even though there is a class DocumentPointer, but the argument is just a String)
    • “field” (e.g. FieldAwareOperator - even though there is a class IField, but the argument is just a String)
      I think, ideally, there should be a glossary of A12 terms and the terms defined there should be mandatory in all a12 code.

  • I tried to have a look at the sources for RankedNotification to find out what exactly that is but something seems to be off with the publication:

Sources download failed
Sources were not downloaded for: com.mgmtp.a12.base:base-model-consistency:29.0.0:sources"

(source download works fine for data-services module)

7

@stephen-warm-graph: thank you very much for your remarks / feedback.

  • I created a bug ticket to fix the documentation. I hope that this helps in the future to avoid this situation.
  • This is a bit difficult without having the information about the corresponding DM, for such checks, you could have a look at the feature Typed Accessor Classes.
  • I added the part related to the documentation to the ticket I created before, thanks.
  • I will give the feedback regarding the terminology to the Kernel team.
  • Could you please create a bug ticket for this? This should not be like this.
8

Could you please create a bug ticket for this? This should not be like this.

Created A12-17583

9

Update: A12-17583 has been released in 2025.06-ext1.