Core - Additional User Data Fields

This module is dedicated to the management of user data fields. These fields can be added and customised, giving full control on the type of data assigned to the user records.

The base url for the APIs in this page is at:

/api/admin

A JSON file with OpenAPI data about all core-related admin APIs can be downloaded here.

The value types of the additional user fields can be one of the AdditionalValueTypes enumeration, with the following implications:

Value	Implications
Number	In the `ValidValues` there can be a JSON array of three items, the first being the lower bound and the second being the upper bound of the allowed range, while the third is set to 0 if the number has to be an integer and 1 if it is decimal. A value of null or undefined lets the end unbounded. No `ValidValuesLabels` are to be expected.
Boolean	No `ValidValues` are to be expected, but there can be `ValidValuesLabels`. In that case, both labels for “true” and “false” are expected.
String	In the `ValidValues` there can be a JSON array of two items, the first being the lower bound and the second being the upper bound of the allowed length.
Enumeration	Both `ValidValues` and `ValidValuesLabels` are to be expected, as in the example. `ValidValues` has to be an array of string values.
Multi-enumeration	Both `ValidValues` and `ValidValuesLabels` are to be expected. `ValidValues` has to be an array of string values.
DateTime	In the `ValidValues` there can be a JSON array of three items, the first two being lower and upper buond, and the third being an enum that describes the bound type. Possible values of the third item are: 0 - the bounds refers to the year of the date (i.e. between 1990 and 2000) 1 - the buonds refers to the age in years of the inserted date; the age is computed as full years, so between 02/01/2000 and 01/01/2002 the age is still one year 2 - the bounds refers to the age in months of the inserted date; the age is computed as full months 3 - the bounds refers to the age in days of the inserted date A value of null or undefined lets the end unbounded. No `ValidValuesLabels` are to be expected. The `Value` field should be a date as a string in the format yyyy-MM-dd
Attachment	No `ValidValues` or `ValidValuesLabels` are to be expected

When expected, ValidValuesLabels should be a dictionary structure that maps every value defined in ValidValues to a stringified JSON that contains the localization values (i.e. {“dog”: {“en”:”Dog”,”it”:”Cane”}.

Get one additional user data field

Returns the record in the additional user data field table corresponding to the ID provided in the request:

GET /v1/additional-data-fields/{id}

Returns the record corresponding to the ID

Parameters

id (integer) –

Status Codes

200 OK – Success

DELETE /v1/additional-data-fields/{id}

Mark a field as deleted

Parameters

id (integer) – The ID of the field to delete

Status Codes

200 OK – Success

id: Int

It returns the first element corresponding to the provided ID:

{
  ID: 3,                                                                                            // Int
  CreatedDate: "2001-01-01T01:01:01Z",                                                              // DateTime
  LastUpdated: "2001-01-01T01:01:01Z",                                                              // DateTime
  FieldName: "CustomFieldName",                                                                     // String
  Type: 0,                                                                                          // Int
  FieldLabels: ""{\"en\":\"Test attachment\",\"it\":\"Allegato di test\"}",                         // String
  FieldDescriptionLabels: "{\"en\":\"Attachment description\",\"it\":\"Descrizione allegato\"}",    // String (nullable)
  ValidValues: "",                                                                                  // String (nullable)
  ValidValueLabels: "",                                                                             // String (nullable)
  IsRequired: true,                                                                                 // Boolean
  IsServerOnly: false                                                                               // Boolean
}

The fields FieldLabels and FieldDescriptionLabels contains a stringified Json containing pairs “language code”:”localized value”.

The fields ValidValues and ValidValueLabels also contains a stringified localizable Json, and are set only for Enumeration and MultipleEnumeration types.

Value types can be one of the AdditionalValueTypes enumeration.

Get the list of all additional user data fields

Returns an array with all records in the table:

GET /v1/additional-data-fields/list-all

Returns an array with all records in the table

Status Codes

200 OK – Success

The following is an example of the returning array:

[
  {
    ID: 3,                                                                                            // Int
    CreatedDate: "2001-01-01T01:01:01Z",                                                              // DateTime
    LastUpdated: "2001-01-01T01:01:01Z",                                                              // DateTime
    FieldName: "CustomFieldName",                                                                     // String
    Type: 0,                                                                                          // Int
    FieldLabels: ""{\"en\":\"Test attachment\",\"it\":\"Allegato di test\"}",                         // String (nullable)
    FieldDescriptionLabels: "{\"en\":\"Attachment description\",\"it\":\"Descrizione allegato\"}",    // String (nullable)
    ValidValues: "",                                                                                  // String (nullable)
    ValidValueLabels: "",                                                                             // String
    IsRequired: true,                                                                                 // Boolean
    IsServerOnly: false                                                                               // Boolean
  },
  ...
]

The fields FieldLabels and FieldDescriptionLabels contain a stringified Json containing pairs “language code”:”localized value”

The fields ValidValues and ValidValueLabels also contains a stringified localizable Json, and are set only for Enumeration and MultipleEnumeration types.

Value types can be one of the AdditionalValueTypes enumeration.

If there is a problem while retrieving the list, a generic json error will be returned.

Get the list of additional user fields

Returns the list of additional user fields (it’s a Paged List APIs, as explained in the introduction):

GET /v1/additional-data-fields/list

Returns the list of available additional user fields

Status Codes

200 OK – Success

Returns a list of the records in the following format:

[
  {
    ID: 3,                                                                                            // Int
    CreatedDate: "2001-01-01T01:01:01Z",                                                              // DateTime
    LastUpdated: "2001-01-01T01:01:01Z",                                                              // DateTime
    FieldName: "CustomFieldName",                                                                     // String
    Type: 0,                                                                                          // Int
    FieldLabels: ""{\"en\":\"Test attachment\",\"it\":\"Allegato di test\"}",                         // String
    FieldDescriptionLabels: "{\"en\":\"Attachment description\",\"it\":\"Descrizione allegato\"}",    // String (nullable)
    ValidValues: "",                                                                                  // String (nullable)
    ValidValueLabels: "",                                                                             // String (nullable)
    IsRequired: true,                                                                                 // Boolean
    IsServerOnly: false                                                                               // Boolean
  },
  ...
]

The fields FieldLabels and FieldDescriptionLabels contain a stringified Json containing pairs “language code”:”localized value”

The fields ValidValues and ValidValueLabels also contains a stringified localizable Json, and are set only for Enumeration and MultipleEnumeration types.

Value types can be one of the AdditionalValueTypes enumeration.

The number of records shown will be limited by page settings.

Get the list required additional user data fields

Returns an array with the Required fields in the table:

GET /v1/additional-data-fields/list-required

Return an array with the Required fields in the table

Status Codes

200 OK – Success

The request will return an array of all the records where the field IsRequired is true. The response format is the same as the previous described APIs.

If there is a problem while retrieving the list, a generic json error with no additional data will be returned.

Add or edit an additional user field

Persists edits about a new or existing additional field:

POST /v1/additional-data-fields

Persists edits about a new or existing additional field

Status Codes

200 OK – Success

The request format is the following:

{
  ID: 1234,                                                                                                             // Int
  Fieldname: "Edited or new Field Name",                                                                                // String
  Type: 1,                                                                                                              // Int
  FieldLabels: ""{\"en\":\"English label\",\"it\":\"Italian label\"}",                                                  // String
  FieldDescriptionLabels: "{\"en\":\"English attachment description\",\"it\":\"Descrizione allegato in italiano\"}",    // String (nullable)
  ValidValues: "Edited or New valid values",                                                                            // String (nullable)
  ValidValueLabels: "Edited or New valid values labels",                                                                // String (nullable)
  IsRequired: true,                                                                                                     // Boolean (nullable)
  IsServerOnly: false                                                                                                   // Boolean (nullable)
}

The fields FieldLabels and FieldDescriptionLabels contain a stringified Json containing pairs “language code”:”localized value”

The fields ValidValues and ValidValueLabels also contains a stringified localizable Json, and are set only for Enumeration and MultipleEnumeration types.

Value types can be one of the AdditionalValueTypes enumeration.

If the provided ID is a valid id, the corresponding record will be updated. Otherwise a new record will be created. If the request is succesfull, it will return a positive Json response.

Possible error messages are:

err_NotAdministrable: The provided id maps to a system-defined field, that is not modifiable
err_InvalidElement: No field name or labels have been provided, the field is either a selection or multiple selection type and no valid values has been provided, or no field has been found for the ptovided id
err_DuplicateElement: The user is trying to add a field with the same FieldName as an existing one.

Delete one additional user field

Remove from the DB the field based on the id provided in the request:

GET /v1/additional-data-fields/{id}

Returns the record corresponding to the ID

Parameters

id (integer) –

Status Codes

200 OK – Success

DELETE /v1/additional-data-fields/{id}

Mark a field as deleted

Parameters

id (integer) – The ID of the field to delete

Status Codes

200 OK – Success

The result can be a plain positive response or a generic json error with no additional data if the operation is successful.