task_activity_insert()

task_activity_insert()

Function prototype

task_activity_insert (session, task , task_code, position, insert_closed, parameters)

API Version

2.7.26 and higher

Supported interfaces

SOAP, REST

Description

Insert an ACTIVITY into a existing TASK

An ACTIVITY is a https://linkcare.atlassian.net/wiki/spaces/WS/pages/27263072 that can contain several https://linkcare.atlassian.net/wiki/spaces/WS/pages/4260257 and https://linkcare.atlassian.net/wiki/spaces/WS/pages/37486691 .

This function inserts all the objects contained in the TASK TEMPLATE referenced by task_code into another existing TASK

Input parameters:

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

  • task: A reference to the TASK where the ACTIVITY will be inserted

  • task_code: A TASK CODE referring to the activity to be inserted

  • position: A number indicating the position in the TASK where the activity will be inserted. it is possible to indicate a negative value, which is interpreted as the position counting backwards from the last existing FORM.

    Additionally, it is possible to indicate one of the following options:

    • "FIRST": The ACTIVITY will be inserted at the beginning of the TASK (first activity of the TASK)

    • "NEXT":The ACTIVITY will be inserted after the current FORM (the one that is invoking the FORMULA ACTIVITY_INSERT() )

    • "LAST": The ACTIVITY will be inserted at the end of the TASK (last activity of the TASK)

  • insert_closed: (true/false) if 'true' try to close the forms of the selected ACTIVITY after insert, otherwise keep them open (the CLOSED property configured in the WORKPLAN of the TASK is ignored)

  • parameters: Array of values that will be assigned to the the ITEMS into the objects inserted. See section #PARAMETERS_DESCRIPTION below.

Output parameters:

  • result: List of the objects inserted (FORMS and/or REPORTS)

    • type: Type of object inserted (FORM or REPORT)

    • ref: Reference of the object inserted

    • code: Code of the object inserted

    • name: Name of the object inserted in the active session language

  • 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 sample:

api_function ( “LCAAAAAAAAAAAA”, "xxx", "yyy" );

Request example

task_activity_insert ( “LCAAAAAAAAAAAA”, 32131, "BLOOD_PRESSURE_TASK", "LAST", false, "[{'code': 'SYSTOLIC', \"value\":\"11.2\"}]")

Reponse

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

INSUFFICIENT_PRIVILEGES

The session user does not have the necessary privileges to insert an ACTIVITY

TASK.NOT_FOUND

The TASK referenced by the value specified in the task parameter doesn’t exist

TEMPLATE.NOT_PRESENT

The TASK TEMPLATE with the TASK CODE indicated in the parameter task_code does not exist

TASK.CODE_AMBIGUOUS

There exist more than one TASK TEMPLATE with the TASK CODE indicated in the parameter task_code

INVALID_JSON

The JSON string provided in parameters is not correct

Passing parameters to the inserted ACTIVITY

The parameter called parameters allows to provide a list of values that will be assigned to the ITEMS inserted

It must be a JSON string representing an array of objects with initial values that will be applied to the ITEMS of the ACTIVITIES. Each array item must be an object with 2 properties:

  • code: name of the DATA CODE to which the value will be assigned

  • value: value assigned

The values can be either  simple values or arrays.

The values assigned to each parameter will be stored in the newly created ACTIVITY into the ITEMS whose ITEM_CODE matches the property "code"

See the following examples:

Example of passing 2 parameters with simple values:

Passing parameters

[ {"code":"PARAMETER.RELATIVE", "value":"RELATIVE.PARENT(M)"}, {"code":"PARAMETER.DIAGNOSE.ICD10", "value":"H60.20"} ]
  • The ITEM with ITEM_CODE = "PARAMETER.RELATIVE" will be assigned the value "RELATIVE.PARENT(M)"

  • The ITEM with ITEM_CODE = "PARAMETER.DIAGNOSE.ICD10" will be assigned the value "H60.20"

Note that if the TEMPLATE of the new ACTIVITY does not contain an ITEM with a ITEM_CODE named as any of the parameters provided, then a new ITEM will be created (hidden)

Example of passing 2 parameters with array values:

Passing parameters

[ {"code":"HEART_RATE", "value":[87, 97]}, {"code":"HEART_RATE_TIME", "value":["12:00:00","16:00:00"]} ]
  • An array of ITEMs with ITEM_CODE = "HEART_RATE" will be created, the ITEM in row 1 will be assigned with the value 87, and the ITEM in row 2 will be assigned with the value 97

  • An array of ITEMs with ITEM_CODE = "HEART_RATE_TIME" will be created, the ITEM in row 1 will be assigned with the value "12:00:00", and the ITEM in row 2 will be assigned with the value "16:00:00"

If the TEMPLATE of the new ACTIVITY already contains an array of ITEM with ITEM_CODE that match the parameter names, then the necessary rows will be added to fit as many values as provided.

Otherwise, a new array of ITEMs will be created (hidden) for each parameter with multiple values