Some API functions that return lists of TASKS (e.g. user_get_task_list()) accept a filter expression to limit the amount of results returned.

The filter is expressed in JSON format, and the possible filter fields are:

• from_date: a datetime expression with format "yyyy-mm-dd hh:nn:ss"). from_date can have some special values:

  • 'first_task' will use the date of the first TASK or EVENT

  • 'first_open' will use the date of the first OPEN TASK or EVENT or from the last TASK if there is no TASK OPEN

  • 'day', 'month', 'year': this options only make sense if the filter to_date is 'fist_task' or 'first_open'. If any of this options is indicated, then the TASKS returned will be the ones enclosed in the corresponding period prior to 'to_date'

• to_date: a datetime expression with format "yyyy-mm-dd hh:nn:ss"). to_date can have some special values:

  • 'first_task' will use the date of the first TASK or EVENT

  • 'first_open' will use the date of the first OPEN TASK or EVENT or from the last TASK if there is no TASK OPEN

  • 'day', 'month', 'year': this options only make sense if the filter from_date is 'fist_task' or 'first_open'. If any of this options is indicated, then the TASKS returned will be the ones enclosed in the corresponding period posterior to 'from_date'

• program: List of PROGRAM identifiers separated by commas. If informed, only the TASKS from that PROGRAMs will be returned. From version 2.7.20 it is also allow to provide PROGRAM CODES instead of the PROGRAM IDs.

• protocol: List of PROTOCOL identifiers separated by commas. If informed, only the TASKS from that PROTOCOLs will be returned

• subscription: List of SUBSCRIPTION identifiers separated by commas. If informed, only the TASKS from that SUBSCRIPTIONs will be returned

• subscription_team: A list of TEAM identifiers (referring to the TEAM that is the owner of a SUBSCRIPTION) separated by commas. From version 2.7.20 it is also allow to provide TEAM CODES instead of the TEAM IDs.

• admission: List of ADMISSION identifiers separated by commas. if informed, only the TASKS from that ADMISSIONs will be returned

• status: If informed, only TASKS with the specified status (a list of STATUS identifiers separated by commas), otherwise, all TASKS will be returned. See TASK STATUS OBJECT to view accepted status values.
  From API version 2.7.17 the status should be preferably identified by its name (e.g. "OPEN"), but also its numeric ID is supported though it should be avoided because they may change in the future.
  In API Versions 2.7.16 and older only the numeric status IDs were supported. The literal status supported are:

  • "OPEN": Include all TASKS that are open

  • "CLOSED": Include all TASKS that are closed

  • "PAUSED": Include all TASKS that are paused

  • "CANCELED": Include all TASKS that are canceled

  • "PENDING" (Introduced in API version 2.7.31): This is similar to "OPEN" but applying a date limit. The platform considers that a "pending" TASK is one that is open and is ready to be done (not scheduled in the future). This filter should not be mixed with other status filters.

• code: a list of TASK CODEs or EVENT CODEs separated by commas (Introduced in API Version 2.7.20)

• role: A list of ROLE identifiers separated by commas (see ROLE OBJECT). Since API Version 2.7.21 it is also possible to use the following special names:

  • PROFESSIONAL: Any professional role (all except CASE)

  • CASE: Only CASE role (TASKs assigned to a CASE)

  • ALL: Is equivalent to leave the role filter empty. All roles will be included in the search

• team_assigned: A list of TEAM identifiers (referring to the TEAM to which the TASKS are assigned) separated by commas. From version 2.7.20 it is also allow to provide TEAM CODES instead of the TEAM IDs.

• patient: A list of PATIENTS references to filter separated by commas
  
  

• flagged: (true/false): If true, the function will return only flagged EVENTS (Introduced in API Version 2.7.15)

• locked (true/false): indicates if locked TASKs must be included. By default this field is assumed to be "true".

• external (true/false): indicates if external TASKs must be included. By default this field is assumed to be "false". A TASK is considered to be external it it belongs to a SUBSCRIPTION in which the USER is a member (directly or indirectly) but has no permissions to complete that TASK

• forms (true/false): indicates if task/ form will be retrieved with forms or not

• object_types: (ALL/TASKS/EVENTS) allows to select which kind of items will be returned. If empty, "ALL" is assumed

Example

TASK FILTER

NOTE: Each function can support all or only part of the field filters. When calling to API functions it is not necessary to include empty filters.