SDK1.12 - Some fields with property "id-ref" are not using displayType COMBOBOX

[Giulio999]

Hi all,
I started working on the eForm-SDK upgrade from 1.9 to 1.12.

Looking at the differences between the two versions I have seen that some fields like "BT-13716-notice" or "BT-1501(p)-Contract" ("BT-1501(s)-Contract" in the older version) in fields.json the "type" property switched from "id" to "id-ref", and in most of the "different types of procurement notices" json files inside the "notice-types" folder has been added in these related fields the "_idSchemes" property filled with a String Array.

Now, as reported in TED Developer Docs at this link (noted below the relevant section) I expect that for the above fields should also be changed the "displayType" from TEXTBOX to COMBOBOX

Property

Description

"_idSchemes"

This property appears only for fields of type id-ref (identifier reference). Such fields will typically have their displayType set to COMBOBOX with the intention of providing the user with a list of valid existing identifiers to chose from. The property provides a list of identifier prefixes (idSchemes) that can be used to find all available valid identifiers in the notice which can be used to populate the options of the combobox. The value can be retrieved from the field metadata (fields.json) but is also provided here for convenience.value: any string (e.g. "LOT")

Is there a valid reason why the "displayType" has not been changed?

If TEXTBOX is the correct option, how should these fields be rendered, and how should the provided options be rendered?

Notice Editor Sample is broken for the newest versions

Thanks in advance for the clarification
Giulio

[rouschr]

From what I remember, we were able to change from "id" to "id-ref" thanks to the use of business entities and the docs does say "typically" but that does not mean always.

After a few SDK releases we may decide to put COMBOBOX instead of TEXT but we fear this could break existing applications that did not yet move to usage of the new "referencedBusinessEntityIds". The problem is that sometimes populating the COMBOBOX is a bit more complex.

There are easy cases where the new and old solutions are identical:

    "idSchemes" : [ "LOT" ],
    "referencedBusinessEntityIds" : [ "lot" ],

In that case using idSchemes vs referencedBusinessEntityIds makes little difference.
But then there are cases like for example "BT-13716-notice", where in fields.json you have:

In the past we only provided this array:

"idSchemes" : [ "CON", "GLO", "LOT", "ORG", "PAR", "RES", "TEN", "TPA", "TPO", "UBO" ],

As you can see the pattern allowed for more values, some which were not just 3 letter like "PROCEDURE":

 "pattern" : {
      "value" : "^(PROCEDURE|BUYER|RESULT|((PAR|LOT|GLO|RES|ORG|TPA|TPO|TEN|CON|UBO)-\\d{4}))$",
      "severity" : "ERROR"
    }

This meant the SDK was providing values, but that they were spread in the idSchemes + pattern.
As this looked abnormal or incomplete, it took us a while to come up with a more generic solution, which ended up being the business entities (they handle this kind of case and more).

Since the business entities we provide a more extensive array to cover all values of the pattern:

"referencedBusinessEntityIds" : [ "buyer", "contract", "groupOfLots", "lot", "organization", "part", "procedure", "resultForLot", "noticeResult", "tender", "tenderingParty", "touchpoint", "ultimateBeneficialOwner" ],

As you can see things like "PROCEDURE" of the pattern now appear in this new array as "procedure".
The business entity ID is "procedure" in that array and the business entity on top of the fields.json is:

{
    "id" : "procedure",
    "name" : "Procedure",
    "description" : "Information on the procedure",
    "labelId" : "business-entity|name|procedure",
    "repeatable" : false,
    "changeIdentification" : {
      "identifyInChangeNotice" : true,
      "useInstanceIdentifier" : false,
      "changeIdentifier" : "PROCEDURE"
    }
  }

So the technical value you can set in the field is provided by the logic:

-> get business entity information by id
-> "changeIdentification"
-> "identifyInChangeNotice"?
-> "useInstanceIdentifier"?
-> (in this case 'false' means no)
-> if false use "changeIdentifier"
-> "PROCEDURE" (obviously the value we are after as it exists in the pattern of the field)

With a bit of logic this will give you the correct value for any business entity found in the referencedBusinessEntityIds array.
You can see that the values you are after match the values in the pattern, these values are present somewhere in the business entities (it varies by business entity):

"value" : "^(PROCEDURE|BUYER|RESULT|((PAR|LOT|GLO|RES|ORG|TPA|TPO|TEN|CON|UBO)-\\d{4}))$",

So this new mechanism allows to fully automate what was previously in the combination of idSchemes + looking into the pattern.
You are not forced to immediately use new "referencedBusinessEntityIds" but we recommend you start using it as it avoid having to parse the pattern or to hardcode some logic in your application.

You can find some public (but not officially released) docs about business entities but this git branch could disappear at any time in the future:
https://github.com/OP-TED/eforms-docs/blob/feature/TEDEFO-2944-business-entities/modules/fields/pages/business-entities.adoc

We will have more comprehensive official documentation about this later.