1 OVERVIEW
2 ITEM TEMPLATE PROPERTIES
- 2.1 Properties table
  - 2.1.1
- 2.2 Special properties
  - 2.2.1 Property “OPTIONS FORMULAS”
  - 2.2.2 OPTION's DEFAULT VALUE FORMULAS
  - 2.2.3 Property "ARRANGEMENT"
  - 2.2.4 Property "CONSTRAINTS"
3 WEB SERVICES

OVERVIEW

Is each individual object that composes a FORM TEMPLATE OBJECT.

Can be used to create:

Titles (static text) to be displayed in a questionnaire
A interactive question to request data to a professional or patient. Supports many types of data (text, numbers, visual analog scale, list of options, check boxes, binary selections…)
Insert automatic calculations or execution of complex functions using the internal FORM FORMULAS language
Display multimedia content (images, videos, reproduce audios)
Capture GPS geolocation data
etc.

The reference (unique ID) that identifies an ITEM TEMPLATE is a combination of two values:

Property	Description

Property

Description

FORM_TEMPLATE_REFERENCE

Reference of the FORM TEMPLATE where an ITEM TEMPLATE is embedded

ITEM_TEMPLATE_REFERENCE

Reference of the ITEM TEMPLATE. this value is unique only inside a FORM TEMPLATE (can be repeated in other FORM TEMPLATES).

This value can be used in a FORMULA by prepending a '$' character (for example $14)

ITEM TEMPLATE PROPERTIES

Properties table

Property	Description

Property	Description
ITEM_CODE	A customized reference to the ITEM that can be used instead of the REFERENCE generated automatically by the system. The ITEM_CODE property must meet the following restrictions: It must be composed by a preceding letter followed by any alphanumeric character of '_' (underscore) ITEM_CODE values are always converted to an uppercase string An ITEM_CODE cannot be repeated within the same FORM TEMPLATE OBJECT Introduced in API version 2.7.18
ORDER	The order of the question in the ITEM[]. The list of ITEMS[] is sorted automatically
DATA_CODE	Is a code identifying the particular purpose of an ITEM value. The description of the different available DATA_CODE can be found in the CODES library under the DATA_CODE codification. For example: code_search (session, "DATA_CODE", "HR") will return the multilingual description of an ITEM with DATA_CODE = HR (Heart Rate) in the active language of the session. There are two special DATA_CODE uses beyond this general definition: System DATA_CODE: Some DATA_CODE are reserved for system use. System DATA_CODE are identified by a hash before the code. Local DATA_CODE: DATA_CODE can also be used to refer to a particular ITEM for local ( form limited scope ) to be referred by a FORMULA. Example: SUM($item1, $item2) will add the value of the items referred with DATA_CODE $item1 and $item2. Local DATA_CODE are not part of the CODES library. Restrictions: Only accepted numbers, letters, underscores, dots and dollars. Validation is applied using next regular expression /^[a-zA-Z0-9_$.]*$/
TYPE	Is the type of the question. (*) See ITEM TYPE for more information.
SECTION_TITLE	Used in STATIC TEXT ITEMS. Indicates that the TITLE of this ITEM is a "Section" title. This is normally used in the UI to display a caption when presenting an ITEM to know that it belongs to a particular section. All ITEMS following an ITEM marked as "Section title" are considered to belong to that section (until a new ITEM marked as "Section title" appears, which would start a new section)
DESCRIPTION	Is the text that must be shown when displaying this ITEM such as a header (if the ITEM is a STATIC_TEXT) a question if the ITEM is any of most kind of ITEMs etc. The literal is always returned in the active session language unless it's instructed otherwise. Some Web Services allow to retrieve the value in all the available languages. If the literal has the system value #DATA_CODE the text returned will be the one associated to the DATA_CODE field. The literal may also include{{OBJECT CODE}}, that will be replaced by by the value of an ITEM with this DATA_CODE when calling form_get_summary () , mobile_form_get_summary () and form_get_question () Example: <table border="0" style="background-color:white;border-collapse:collapse;border:0px solid black;color:black;width:100%" cellpadding="9" cellspacing="9"><thead><tr><th ></th><th><b>FVC</b></th><th><b>FEV1</b></th><th><b>FEV1/FVC</b></th><th><b>PEF</b></th><th><b>FEF25-75</b></th></tr></thead><tbody>{% for key,value in ADMISSION.DATA.SPIRO.PBD.FEV1 %}<tr><td><b>{{loop.index}}</b></td><td>{{ ADMISSION.DATA.SPIRO.PBD.FVC[loop.index0] }}</td><td>{{ ADMISSION.DATA.SPIRO.PBD.FEV1[loop.index0] }}</td><td>{{ ADMISSION.DATA.SPIRO.PBD.FEV1-FVC[loop.index0] }}</td><td>{{ ADMISSION.DATA.SPIRO.PBD.PEF[loop.index0] }}</td><td>{{ ADMISSION.DATA.SPIRO.PBD.FEF2575[loop.index0] }}</td></tr>{% endfor %}</tbody></table> This will show something like:
DESCRIPTION_ONEDIT	The same than DESCRIPTION, but represents the text to show when the FORM is being edited. If empty, the value of DESCRIPTION will be used. This is useful to show different texts when editing a FORM to fill the answers or when just seeing the contents of the FORM. For example, a question could have the following literals: DESCRIPTION: "Blood pressure of the patient is:" DESCRIPTION_ONEDIT: "What is your blood pressure?" This way, when a patient is answering the FORM, the texts appears as a question, but when the FORM is not being edited, the text appears as a statement (not a question)
LITERAL_FORMAT	Determines how the text of the description should be presented. Is responsibility of the client to apply the indicated format. The format is expressed using a JSON string with the following properties: text_format: there are two possibilities: plain (default): The literal is plain text that can be formatted with the values indicated in "style" property html: The literal is an HTML string, and it is not necessary to indicate the "style" property (if indicated, it should be ignored) style: contains a list of properties that determine the appearance of the text. The properties for the style have equivalent names to those in CSS specification. code_format: for a CODE ITEM determines which properties of the code to display `{ "text_format" : "plain \| html", "code_format" : "value\|description\|all" "font-family" : "Times new roman", "font-size" : "18", "font-style" : "normal \| italic", "font-weight" : "normal \| bold", "text-align" : "center \| left \| right" }`
VALUE_FORMAT	Same than ITEM TEMPLATE OBJECT#LITERAL_FORMAT but applied to the value (answer) of the questions in the FORM
IMAGES	List of images associated to this ITEM. The property ARRANGEMENT PROPERTY defines how the images will be displayed
ARRANGEMENT	Determines the arrangement of the answer in the interface. Is responsibility of the client to apply the indicated format. The format is expressed using a JSON string (see ARRANGEMENT PROPERTY)
CONSTRAINTS	Allows to define constraints for the value admitted for this ITEM (See CONSTRAINT PROPERTY)
MIN_LEN	Minimum Length of the field (ITEM)
MAX_LEN	Maximum Length of the field (ITEM)
DEF_VAL	Default Value that will be assigned to an ITEM based in this ITEM TEMPLATE when no value has been specifically assigned. See ITEM OBJECT for more information about how the default value is applied It can contain FORMULAS which are executed if are preceded by '='.
MIN_VAL	Minimum value of the field (ITEM)
MAX_VAL	Maximum value of the field (ITEM)
NUM_DEC	Number of decimals for numeric ITEMs
MIN_ROWS	Minimum number of rows required in an ITEM of type ARRAY. Supports a number or a FORMULA Introduced in API version 2.8.1
MAX_ROWS	Maximum number of rows permitted in an ITEM of type ARRAY. Supports a number or a FORMULA Introduced in API version 2.8.1
REQUIRED	Indicates if it is required (mandatory) to provide a value for in ITEMS generated from this ITEM TEMPLATE Values accepted: NULL, false, 0: Value is not required (not mandatory) true, 1: Non null value is required (mandatory) FORMULA: Use a FORM FORMULAS to set the required property. Introduce in API Version 2.7.20
FORMULA	FORM FORMULAs to calculate complex values depending on referenced ITEMs (questions) or constant values. See more information in FORM FORMULAS
HIDDEN	If the ITEM (question) must be hidden in the browse format to the user. Possible values: 0: Always visible (not hidden) 1: Always hidden 2: Hidden only when FORM is closed 3: Hidden only if FORM is open
CONDITIONED	An ITEM with a condition different null will only "exist" if the formula in the condition property returns 1 (Y). NOTE: Be aware that condition is different from hidden. While a hidden ITEM exists but cannot be displayed, so it can be part of a follow-up report or be referenced by a formula; A conditioned field doesn't exists at all if the condition property is not true and neither has an associated value nor can be referenced by a formula. NOTE2 (Array Conditions): If the condition is on an Array block, when the Array add a new file and if the condition references to another question ID (of the same Array), the condition is recalculated NOTE3 (Code Conditions): When conditioning to a previous question that is CODE item type, condition expression should contain the whole JSON structure: e.g. $2,{"option_id":"0"} (the first manual answer included in the CODE item type, starts with option_id = 0).
VISIBILITY_CONDITION	This property allows to decide whether an ITEM OBJECT generated from this ITEM TEMPLATE will be visible for the active SESSION USER. The VISIBILITY CONDITION is generally expressed as a FORMULA. The ITEM OBJECT is considered to be visible when this field evaluates to a value different than 0
NUM_ASOCIADAS (ARRAY)	Removed in API Version 2.7.24 Is a numeric field indicating if the field may have more than one instance. When a field has the "ARRAY" value of 1, once the field is filled a new blank field is shown. If the field is left empty the next field will be shown. If the ARRAY value is higher that 1 means that the next N ITEMs will be sequentially shown until the first field in the group is left blank
ARRAY_REF	Used to indicate that an ITEM TEMPLATE is part of an array. The value can be: NULL: The ITEM TEMPLATE is not part of an array Number: Should be the ID of an ITEM TEMPLATE of type "ARRAY". All ITEM TEMPLATES that belong to the same array will have the same ARRAY_REF Introduced in API Version 2.7.24 as a replacement of the deprecated property NUM_ASOCIADAS
ARRAY_COL	When an ITEM TEMPLATE is part of an array, this property indicates the position (column) of the ITEM in the array. Otherwise it is null. This value is read-only because it is automatically assigned by the system. The position of an ITEM TEMPLATE and can be modified using the API function library_form_question_move () Introduced in API Version 2.7.24 as a replacement of the deprecated property NUM_ASOCIADAS
OPTIONS FORMULA	This field allows to generate a dynamic list of options for the following types of ITEMS HORIZONTAL_CHECK VERTICAL_CHECK VERTICAL_RADIO HORIZONTAL_RADIO CODE The value of this field must be a FORMULA that generates a list of options. See OPTION FORMULAS for more details
MONITORED	(true/false) Indicates if the values stored in ITEMS created from this TEMPLATE should be monitored. This value is used for statistics, extractions and evolution graphs
MONITORED_CATEGORY	The name of a DATA_CODE that can be used to categorize a monitored value. This property only produces some effect if MONITORED=true.
EXCLUSION	Removed in API Version 2.7.29 If EXCLUSION is set: If the CONDITIONED field is null admission will be rejected if answered current question with No, otherwise if CONDITIONED = 'S' admission will be rejected answering current question with Yes. Note: To activate option EXCLUSION question should be BOOLEAN type.
DEVICE_TYPE	Only for ITEMs of type "DEVICE": identifies the type of device. Possible values: SPIROMETER PEDOMETER PULSEOXYMETER ACTIVITY_MONITOR SPHYGMOMANOMETER GPS
BARCODE_SCAN	This property is used to indicate that it may be possible for the user to enter the value of the ITEM by scanning a barcode. This is only a suggestion for the client APP because the API has no control on the way the items are presented to the user. Accepted values for this property are: NULL / 0: Do not allow barcode scan 1: Allow barcode scan and manual input 2: Allow only barcode scan Introduced in API version 2.7.15
DESCRIPTION_AUX_1	Auxiliar text used by some type of ITEMS. For example, an ITEM of type FILE uses this description to allow to configure the text that should appear in the "Upload" button The literal is always returned in the active session language unless it's instructed otherwise. Some Web Services allow to retrieve the value in all the available languages. Introduced in API version 2.7.16
DESCRIPTION_AUX_2	Auxiliar text used by some type of ITEMS. For example, an ITEM of type FILE uses this description to allow to configure the text that should appear in the "Skip" button The literal is always returned in the active session language unless it's instructed otherwise. Some Web Services allow to retrieve the value in all the available languages. Introduced in API version 2.7.16
NAVIGATION_MODE	This property is used to indicate how the ITEM should be presented to the user when editing its value. Note that this is only a recommendation of the designer to the client application about how to present the ITEM, but It is responsibility of the client application to implement the suggested behavior. Possible values are 0: List (default value). When editing the ITEM value, it should be presented in a list along with the rest of ITEMs of the FORM. 1: Step by Step. When editing the ITEM value, it should be presented individually (preferably in a popup modal dialog) Introduced in API version 2.7.19 Examples: Suggestion to present an ITEM with NAVIGATION_MODE=0 (list):
DOCUMENTATION	Developer notes about the ITEM TEMPLATE Introduced in API version 2.8.1

Special properties

Property “OPTIONS FORMULAS”

OPTION FORMULAS in CODE ITEMS

To generate a list of options for an ITEM of type CODE it is possible to use one of the following expressions:

a DATA_CODE value (e.g. "ICD9"). This will cause to return a list of CODE OBJECTS where ID_STANDARD_CODE is the indicated value
a DATA_CODE TREE expression

OPTION FORMULAS in RADIO or CHECKBOX ITEMS

to generate a list of options for this types of ITEM you can use any FORM FORMULAS that returns a value with a valid format

The result of the formula should be an array with the list of options. Ideally each option consists of three values:

Description (string) This is the literal that will be returned as the description of the option
Value assigned to the option (string)
ID of the option (integer)

But it is not mandatory to provide all values. The value returned by the FORMULA can have the following formats:

A scalar value (e.g. "Option 1"): it will be interpreted as only one option where the Description and Value and ID will be equal to that scalar, and the ID will be 1.
An array of values. An option will be generated for each item in the array, where each item can be:
- A scalar value (e.g. "Option 1"): the Description, Value and ID will be equal to that scalar, and the ID will be a sequential number starting at 1.
- An array with 1 up to 3 subitems (additional subitems will be ignored)
  - The first subitem will be used as the Description of the option
  - The second subitem will be used as the Value of the option. If it does not exist then the Value will equal to the description
  - The third subitem will be used as the ID of the option only if it exists and is a positive integer. Otherwise a sequential number will be assigned

The following FORMULAS have been specifically designed to generate lists of options:

NAME

NAME
GET_LIST (SCOPE, PROPERTY{, PARAMETER, OPTIONS})
GET_LIST_MEMBERS()

OPTION's DEFAULT VALUE FORMULAS

NAME	DESCRIPTION

NAME	DESCRIPTION
OPTION_SELECT	OPTION_SELECT allows to set in the DEFAULT or FORMULA properties of an OPTION field a default or calculated selection. Valid only for H_CHECK and V_CHECK.

Property "ARRANGEMENT"

The ARRANGEMENT property is a JSON expression that contains instructions about the appearance of the question (how should it be displayed in the User Interface):

answer_position: indicates if the answer should be presented beside or below the question text. This property should be applied when not editing the FORM
answer_position_onedit: the same than answer_position, but his property should be applied when editing the FORM
images: This property only makes sense if there is at least one image loaded in the question (see property IMAGES). Defines how the images should be displayed:
- position: ("above", "below") to define where the image should be positioned relative to the title text
- alignment: ("left", "center", "right") alignment of the image
- presentation: this property makes sense when there are more than one image loaded. The possible values are:
  - "normal": is the default presentation mode. When there exist only one image, a single image will be displayed. If there exist more than one image, all of them will be visible and lying one beside each other
  - "carrousel": Only one image will be visible at a time. The user can manually switch to the next/previous image
  - n: (where n is a positive number) permits to select only one image of the set. The value of n represent the ordinal position of the image in the set of images
multioption_layout: only valid for CHECK or RADIO question types. Determines if the list of options should be presented as a horizontal or vertical list (NOTE: currently there exist the H_CHECK, H_RADIO, V_CHECK and V_RADIO to define the arrangement, but in the future this will be substituted by only CHECK or RADIO, and the arrangement will be determined by this property)
codes_layout: used in questions of type "CODE". Defines how the list of CODES will be displayed. Possible values:
- "default": an autocomplete field that permits to enter some characters and shows the CODES that match in a dropdown list
- "radio": show all the CODES in a list of RADIOS
VAS section (only for ITEMS of type VAS)
- show_progress: defines whether the visual slider should be filled up to the current value (similar to a progress bar). Possible values:
  - true
  - false
- tooltip_text: format of the tooltip balloon that appears when selecting a value on the visual slider
  - "none": do not display tooltip
  - "description": the tooltip text will be the description instead of the value (see #ELEMENT:CHOICE to find out how to set up descriptions)
  - "value": the tooltip text will display the currently selected value (numeric)
  - "mixed": the tooltip text will be a combination of the text and the value
- title: format of the title shown above the VAS (introduced in API Version 2.7.22). Possible values:
  - "none": do not display title
  - "description": the title will be the description instead of the value (see #ELEMENT:CHOICE to find out how to set up descriptions)
  - "value": the title will display the currently selected value (numeric)
  - "mixed": the title will be a combination of the text and the value
link_display: (only for ITEMs of type LINK) Indicates how to display a link in the client application. Introduced in API Version 2.7.24. Contains 2 properties:
- mode:
  - "default": Show a in the client application so that it is followed when clicked.
  - "embedded": Show the web page referred by the link in an embedded frame so that the contents can be viewed directly without the need of clicking to redirect to another page
- size: Only necessary when mode = "embedded". Indicates the vertical size (in pixels) of the embedded frame where the contents of the link will be displayed.

{
  "answer_position" : "beside/below",
  "answer_position_onedit" : "beside/below",
  "images" : {
       "position" : "below",
       "alignment" : "center",
       "presentation" : "normal",
  }
  "multioption_layout" : "vertical/horizontal",
  "codes_layout" : "default/radio",
  "VAS" : {
      "show_progress" : true,
      "show_ticks" : true,
      "tooltip_text": "description",
      "title": "none"
  }
}

Property "CONSTRAINTS"

The CONSTRAINT property allows to define restrictions and/or validations to verify that the value assigned to an ITEM is valid.

This property is expressed as a JSON string, and the contents depends on the ITEM type as explained below:

ALL ITEM TYPES

All ITEM TYPES accept the following properties for the constraints:

error_message: (optional) A custom error message that will be returned if the constraint is not accomplished. If no message is provided, a generic error message will be returned. The error message can be a FORM FORMULAS. If there are additional validations (see next point) that do not provide a specific message, then this error message will be used as default. Introduced in API Version 2.7.16
validations: array of FORMULAS that can be used to verify that the value entered is valid. Each validation consists of 2 fields (Introduced in API Version 2.7.16)
- formula: Admits any valid FORMULA. See FORM FORMULAS for more details. If the evaluation of the FORMULA returns "false", then the value will be considered invalid (validation failed).
- error_message: (optional) A custom error message that will be returned if the validation fails. If no message is provided, a generic error message will be returned. The error message can be a FORM FORMULAS

The $0 variable: When writing a FORMULA expression, the term $0 will refer to the value that we are evaluating. Remember that a term with the form $n represents an ITEM Reference, where n is an ITEM ID, which are always greater than 0. We use $0 to represent the value being validated. Introduced in API Version 2.7.16

Example

In this example, the value entered must be different than "XXX" and "YYY". If one of them is entered, we'll get one of the following error messages:

If the value is "XXX" the error message "XXX is not admitted" will be returned because it was specifically defined for that validation
If the value is "YYY" the error message "The value entered is not accepted" will be returned because there is no specific message defined for that validation, an therefore the general error message is used

Validate value using a FORMULA

{
  "error_message": "The value entered is not accepted",
  "validations": [
    {"formula" : "$0 != \"XXX\"", "error_message": "XXX is not admitted"},
    {"formula" : "$0 != \"YYY\""}
  ]
}

TEXT ITEMS Specific constraints

regex: (default = null) a regular expression to define the format allowed for the value.

Example 1

The value entered must match the pattern defined by the regular expression "^A\d*N$" to only accept strings composed by a letter "A", 1 or more digits and an ending letter "N" like "A875N". If the value provided is invalid, a standard error message will be returned (no custom error message has been defined in this example)

Validate value with a regular expression

{
  "regex" : "^A\\d*N$"
}

Example 2

the value entered must match the pattern defined by a regular expression and also be different than "A666N" and "A999N". In this example there are 2 validation formulas to display different message depending on the wrong value entered.

Validate value using a FORMULA

{
  "regex": "^A\\d*N$",
  "error_message": "The value must have format AnnnN",
  "validations": [
    {"formula" : "$0 != \"A666N\"", "error_message": "A666N is not admitted"},
    {"formula" : "$0 != \"A999N\"", "error_message": "A999N is not admitted"}
  ]
}

NOTE

In the LIBRARY of linkcareapp the regex and formulas expressions must not be placed "escaped". The following screenshot is the same of the "Example 2" but introduced from the Library:

"Regular expression" only shows one "\" and "formula" is showing " instead of \"

FILE ITEMS Specific constraints

Available from API version 2.7.16

file_type: (default = null) a comma-separated list of permitted file types. Each file type can be expressed as:
- a specific file extension (e.g. "pdf", "doc"...)
- a general group of file extension. The possible values are: image/*, audio/* and video/*
max_size: (default = null). Maximum allowed size (in bytes). The value null or 0 means 'any size'
max_width: (default = 1024) Maximum width in pixels that the client should allow before uploading the image. This is only an indication to avoid uploading large files from the client application. The API does not check the size in pixels of the files received.
max_height: (default = 1024) Maximum height in pixels that the client should allow before uploading the image. This is only an indication to avoid uploading large files from the client application. The API does not check the size in pixels of the files received.

Example

The uploaded file must be a PDF, DOCX (Word document) or any type of image file with a maximum size of 100KB

Validate value with a regular expression

{
  "file_type" : ".pdf, .docx, image/*",
  "max_sixe" : 100000,
  "max_width" : 1024,
  "max_height" : 1024
}

DATE ITEMS Specific constraints

The following properties allow to define which parts of a date value are required, optional or not necessary. The possible values are:

year : Define if the "year" part of the date should be asked. The possible values are:
- "required": the year part of the date is mandatory
- "optional": (this is the default value) the year part of the date is optional (it can be left empty)
month:
- "required": the year part of the date is mandatory. It makes no sense specifying "required" in this property if year = "no" or "optional"
- "optional": (this is the default value) the year part of the date is optional (it can be left empty)
- "no": the month part of the date should not be asked. If a date with month and/or day parts is provided, they will be ignored and only the year will be used
day:
- "required": the year part of the date is mandatory. It makes no sense specifying "required" in this property if month = "no" or "optional"
- "optional": (this is the default value) the year part of the date is optional (it can be left empty). It makes no sense specifying "optional" in this property if month = "no"
- "no": the day part of the date should not be asked. If a date with day parts is provided, it will be ignored and only the year and month will be used.

Example of constraints for a DATE ITEM

{
  "year" : "required",
  "month" : "optional",
  "day" : "optional"
}

WEB SERVICES

List of web services to manage form template:

WS	DESCRIPTION

WS	DESCRIPTION
library_form_get_question ()	This function get a XML with information of specific question in a template.
library_form_question_move ()	Sets new order for questions of a FORM TEMPLATE
library_form_set_answer ()	Sets a value of specific field in a template. This specific field is determined in datacode of question in template.

ITEM TEMPLATE OBJECT

OVERVIEW

ITEM TEMPLATE PROPERTIES

Properties table

Special properties

Property “OPTIONS FORMULAS”

OPTION FORMULAS in CODE ITEMS

OPTION FORMULAS in RADIO or CHECKBOX ITEMS

OPTION's DEFAULT VALUE FORMULAS

Property "ARRANGEMENT"

Property "CONSTRAINTS"

ALL ITEM TYPES

Example

Validate value using a FORMULA

TEXT ITEMS Specific constraints

Example 1

Validate value with a regular expression

Example 2

Validate value using a FORMULA

NOTE

FILE ITEMS Specific constraints

Example

Validate value with a regular expression

DATE ITEMS Specific constraints

Example of constraints for a DATE ITEM

WEB SERVICES