FORMAT SETTINGS

Format settings are used to define the format to be used for CONTACT OBJECTS.

Format settings priority for FORMAT.CASE and FORMAT.CASE.NEW are:

1. CURRENT SUBSCRIPTION 

2. SUBSCRIPTION OWNER TEAM

3. OWNER OF THE SUBSCRIPTION OWNER TEAM

4. SYSTEM TEAM

5. CONFIGURATION SETTINGS (FORMAT.CASE and FORMAT.CASE.NEW are defined at WEB SERVICES CONFIGURATION)

Format setting priority for FORMAT.USER and FORMAT.USER.NEW is:

1. TEAM SETTING of the setting to add the USER as a TEAM MEMBER

2. TEAM OWNER SETTING

3. SYSTEM TEAM

4. CONFIGURATION SETTINGS (FORMAT.USER and FORMAT.USER.NEW are defined at WEB SERVICES CONFIGURATION)

The properties for USER and CASE CONTACT data follows the OBJECT CODES description for CONTACT.

Notice that FORMAT SETTINGS now include IDENTIFIER SETTINGS in the "identifiers" parameter.

This page contains FORMAT.CASE and FORMAT.USER use the following FORMAT:

FORMAT SETTINGS Structure

The FORMAT SETTINGS  structure is represented by a JSON object with the following parts (all parts are optional):

• pictures: if present, it indicates that it is possible to edit the image of the CONTACT OBJECT

• username: Defines if it is possible to edit the USERNAME of the CONTACT OBJECT

  • label: must be "CONTACT.USERNAME"

  • required: see The "required" Property below

• identifiers: List of IDENTIFIER that can be assigned to a CONTACT OBJECT and rules to validate them.

  • list: array of identifiers

    • label: One of the supported IDENTIFIER CODES

    • team: When defining the FORMAT SETTINGS of a TEAM IDENTIFIER (see IDENTIFIER OBJECT) it is necessary to indicate the reference or TEAM_CODE of the related TEAM. If is is not defined the FORMAT SETTING for this IDENTIFIER will be ignored. Introduced in API Version 2.7.20

    • program: When defining the FORMAT SETTINGS of a SUBSCRIPTION IDENTIFIER (see IDENTIFIER OBJECT) it is necessary to indicate the reference or PROGRAM_CODE of the related PROGRAM. If is is not defined the FORMAT SETTING for this IDENTIFIER will be ignored. Introduced in API Version 2.7.18

    • format: formatting rules for the IDENTIFIER

      • mask: A string representation of the format expected for the IDENTIFIER value. This is only a literal that can be used to display a help or a placeholder when the value is requested in a user interface

      • validation: a regular expression that should match the IDENTIFIER value. If empty, no verification will be performed. IMPORTANT: If the expression contains escape characters, (e.g. "\d"), then the escape character must be written twice (e.g. "\\d"). This is necessary because when the JSON parser finds a escape character, it interprets that you are escaping the next character instead of taking it literally.

      • picture: (disabled/enabled/mandatory) An IDENTIFIER can have an attached image. This property defines the requirement for the image

    • auto_generate: Rule for autogenerating a value for the IDENTIFIER. If a value is not provided when creating a new CASE, then a value will be automatically generated following the rules defined in this section (Introduced in API Version 2.7.21). The values generated are always a number formatted as a text of a predefined length (leading "0" are added as necessary). It is also possible to prepend an alphabetic string (a preffix)

      • length: length of an incremental numeric sequence. For example, if length=4, the values generated will have the format "0001", "0002"...

      • preffix: text that will precede the numeric sequence. For example, preffix = "xyz", the values generated for the IDENTIFIER will have the format "xyz0001", "xyz0002"..

    • required: see The "required" Property below

  • groups: (Introduced in API Version 2.7.21) Allows to define groups of IDENTIFIERs that share some characteristics. For example, we could say that NAT_ES and NAT_FR belong to the same group because they both are "National Identifiers". This property has no effect on the behavior of the API and its purpose is only visual (to be used by a client application to improve the user interface). See The "identifiers.groups" property below.
    The groups property must be an array where each item defines a group of IDENTIFIERS (another array with the names of the IDENTIFIERS that belong to the same group).
    This property is used by API functions case_get_contact () and user_get_contact (), which assign a group name to the IDENTIFIERs belonging to the same group.

  • combinations: Combination of IDENTIFIERS that should have valid values. See The "combinations" property below

• age: Indicates if the birthdate or age is an editable field

  • label: can be "CONTACT.AGE" or "CONTACT.BDATE"

  • required: see The "required" Property below

• gender: Indicates if the gender is an editable field

  • label: must be "CONTACT.GENDER"

  • required: see The "required" Property below

• nationality: (Introduced in API Version 2.7.23) Indicates if the contact nationality is an editable field

  • label: must be "CONTACT.NATIONALITY"

  • required: see The "required" Property below

• name: list of fields used to define the NAME OBJECT of a CONTACT OBJECT and some validation rules to decide which fields are necessary

  • list: array of name fields

    • label: One of the following: CONTACT.NAME.GIVEN, CONTACT.NAME.FAMILY, CONTACT.NAME.COMPLETE

    • required: see The "required" Property below

  • combinations: Combination of name fields that should have valid values. See The "combinations" property below

• address: (Introduced in API version 2.7.10) list of fields used to define the ADDRESS OBJECT of a CONTACT OBJECT and some validation rules to decide which fields are necessary

  • list: array of address fields

    • label: One of the following: CONTACT.ADDRESS.ADDRESS, CONTACT.ADDRESS.CITY, CONTACT.ADDRESS.POSTCODE, CONTACT.ADDRESS.STATE, CONTACT.ADDRESS.COUNTRY, CONTACT.ADDRESS.COMMENT

    • required: see The "required" Property below

  • combinations: Combination of address fields that should have valid values. See The "combinations" property below

• channels: list of communication channels assigned to a CONTACT OBJECT and some validation rules to decide which channels are necessary

  • list: array of channels

    • label: One the following: CHANNEL.EMAIL, CHANNEL.PHONE, CHANNEL.IM, CHANNEL.WEB

    • required: see The "required" Property below

    • preferred: (default = true) Indicates whether the contact channel must be stored as preferred. Introduced in API Version 2.7.21

  • combinations: Combination of channels that should have valid values. See The "combinations" property below

• professional_role: (Introduced in API 2.7.14) This setting only applies for PROFESSIONALS (ignored in CASE or ASSOCIATES, only in FORMAT.USER and FORMAT.USER.NEW). Defines the professional role of the user:

  • label: must be "CONTACT.PROFESSIONAL_ROLE"

  • required: see The "required" Property below

The "combinations" property

Some FORMAT SETTINGS admit the property "combinations" (e.g. "identifiers" or "name"). This property permits to define a cross field validation when more than one field is necessary.

For example, to enter a valid address it should be necessary to enter the "City" and a "Address", and if one is missing we should not accept the name as valid. We can even define several combinations of admitted fields (e.g ["CONTACT.ADDRESS.CITY", "CONTACT.ADDRESS.ADDRESS"] or ["CONTACT.ADDRESS.STATE", "CONTACT.ADDRESS.POSTCODE"]. In this situation, if any of the combinations appears to be valid, the name will be accepted.

The format of the "combinations" property is a JSON array where each item is another array with the list of fields required:

Combinations example

The "identifiers.groups" property

This property is not used at all for the API and is only provided as a way on enhancing the user experience in the client application. The goal is to provide a way of indicating that some IDENTIFIERS belong to the same logical group.

This property is used by API functions case_get_contact () and user_get_contact (), which assign a group name to the IDENTIFIERs belonging to the same group

Imagine the following scenario: we have a PROGRAM that requires any new CASE must provide his national identifier, and we allow to introduce a Spanish ID (DNI), a French ID (CNI) or a PASSPORT, so we define a FORMAT SETTINGS that has a list  with these IDENTIFIERS, and we also define the combinations so that at least one of them is mandatory (but not all of them):

When adding a new CASE, the client's application user interface can present all of them event though only one is necessary:

Open

but it can be a little bit confusing for the user, because he may think that all of them are necessary.

In the previous example we also defined that the IDENTIFIERS NAT_ES, NAT_FR and PASS belong to the same group, so we can take profit of this information and present the list of IDENTIFIERS as a dropdown list so that it becomes clear to the user that only one of them must be introduced:

Open

Note that it is possible to define multiple groups of IDENTIFIERS: The groups property must be an array where each item defines a different group of IDENTIFIERS, which is another array with the names of the IDENTIFIERS that belong to the same group.

The following example shows a FORMAT SETTINGS definition where there are 2 groups of IDENTIFIERS:

The "required" property

The fields that support a "required" property can assign one of the following values:

• "false": The field is optional. It is not a problem to leave that field empty

• "true": The field is mandatory. A valid value must be provided

• "minimum": This value is similar to required=true but has a special meaning when creating ADMISSIONS. To create a new ADMISSION it is necessary that all FORMAT SETTINGS fields marked as required=true or required=”minimum" have valid values. Nevertheless, the system, allows to create ADMISSIONs in status "INCOMPLETE" if a field is marked as required=true (see admission_create ()), but it will never be possible to create the ADMISSION if a field marked as required=”minimum" does not have a valid value.. 

FORMAT SETTINGS Example