/
library_program_task_list ()

library_program_task_list ()

Function prototype

library_program_task_list ( session, program , [version], [protocol], [stage], [trial] )

API Version

All

Supported interfaces

SOAP, REST (Since API Version 2.8.1)

Description

Returns the list of TASK TEMPLATES of a PROGRAM

Detailed explanation of the function.

Required permissions: The active user must have role XXXX. Otherwise an INSUFFICIENT_PRIVILEGES error will be returned.

Input parameters:

  • session: is the session token obtained in the session_init() call

  • program: reference of the PROGRAM

  • version: (optional) Specific version of the PROGRAM. If not provided, then the last published version will be used

  • protocol: (optional)

    • If NULL, then the TASK TEMPLATES returned depend on the type of PROGRAM:

      • In stratified PROGRAMS (multiple protocols) only the TASK TEMPLATES of the common PROTOCOL will be returned.

      • In non-stratified PROGRAMS all the TASK TEMPLATES of the PROGRAM will be returned.

    • If non NULL, then the TASK TEMPLATES of the specific PROTOCOL plus the TASK TEMPLATES of the "common" PROTOCOL will be returned

  • stage: (optional) If provided (one of the PROGRAM.STAGE CODES), only the TASK TEMPLATES of that stage will be returned

  • trial:(optional) Only makes sense in PROGRAMS configured as "Medical Trial". Possible values are "I" (Intervention group) and "C" (Control Group). If provided, only the TASK TEMPLATES of the selected trial group will be returned.

Output parameters:

  • result: XML with the following structure:

    • stages: list of available Stages with TASK TEMPLATES

      • stage: Contains the list of TAST TEMPLATES of a stage.

        • ref: Reference of the Stage.

        • description: Name of the Stage in the active Session language.

        • tasks/task: (multiple) Information about each TASK TEMPLATE of a Stage

          • ref: Generally is a numeric value that identifies a existing TASK TEMPLATE. It can also a string representing a virtual TASK TEMPLATE that doesn't really exist but can be inserted in the PROGRAM. See the "class" property of the TASK TEMPLATE below.

          • name: Name of the TASK TEMPLATE in the current session language.

          • description: Description of the TASK TEMPLATE in the current session language.

          • code: TASK CODE of the TASK TEMPLATE.

          • trial_group: Trial group assigned to the TASK TEMPLATE. Can be

            • NULL: Not assigned to a trial group

            • "I": Intervention trial group

            • "C": Control trial group

          • class: indicates the type of TASK TEMPLATE. Can be one of the following:

            • "TASK"

            • "TEMPLATE": represents a virtual TASK TEMPLATE that does not really exist in the PROGRAM. This class of TASK TEMPLATEs only exist in "DRAFT" versions and are included as a reminder of possible TASKs that can be inserted in the PROGRAM.

  • ErrorMsg: If any error occurs, then this value contains a description of the error translated to the current language

  • ErrorCode: If any error occurs, then this value contains any of the standard ERROR CODES

Request example

library_program_task_list(“LCAAAAAAAAAAAA”, 373, 1)

Response

The response format is XML when the function has been invoked via the SOAP API, and JSON when it has been invoked via the REST API

Return Error codes

ERROR CODE

 

ERROR CODE

 

INVALID_TOKEN

The session token provided is not valid

PROGRAM.NOT_FOUND

The PROGRAM referenced by program (and version if provided) was not found

PROTOCOL.NOT_PRESENT

The PROTOCOL referenced by protocol does not exist

WRONG_PARAMS

The stage passed in parameter stage is not one of the PROGRAM.STAGE CODES