/
TASK_INSERT()

TASK_INSERT()

Owned by RaulP (Unlicensed)
Last updated: Mar 07, 2025 by Pedro Jose Sanchez Luling
TASK_INSERT(TASK_CODE, [DATE_TIME] , [N_DAYS], [HOUR[, [CONDITION], [ASSIGNTO_ROLE], [ASSIGNTO_USER], [ASSIGNTO_TEAM], [CLOSED], [RECURSIVE], [PARAMETERS]})

API Version

All

Inserts a TASK  as an instance of a TASK TEMPLATE identified by its TASK_CODE in a specified date.

The new TASK will also belong to the same STAGE thant the TASK where the FORMULA is executed.

If the admission belongs to a TRIAL PROGRAM, then the same TASK CODE may exist either for the 'Control' or 'Intervention' groups. In that case, the function takes into account to which group belongs the ADMISSION to insert the appropriate TASK. If the TASK CODE has not been defined for an specific trial group, then the function will try to find the TASK TEMPLATE that has no trial group assigned

NOTE: The function does not allow to insert the TASK in a past date. If an specific insertion date has been specified and it is a past date, then it will be increased to the next valid date from now (the time part is preserved)

Input Parameters

Parameters

Type

Default

Required

Description

Parameters

Type

Default

Required

Description

task_code

String

 

Yes

TASK CODE of the TASK TEMPLATE that will be inserted. From API Version 2.7.21 it is possible to prepend the name of a PROGRAM separated from the TASK_CODE by a semicolon. For example if TASK_CODE="PRG:MY_TASK", then the TASK with TASK CODE = "MY_TASK" will be inserted in another ADMISSION of the active CASE in the PROGRAM with PROGRAM CODE="PRG".

The rules to find the TASK TEMPLATE are:

  • If a TASK_TEMPLATE with the indicated TASK_CODE exists in the PROGRAM and VERSION of the target ADMISSION, then it will be used to generate the new TASK

  • If no TASK_TEMPLATE with the indicated TASK_CODE exists in the PROGRAM and VERSION of the target ADMISSION, then the most recent TASK_TEMPLATE with that TASK_CODE will be used (regardless of the PROGRAM and VERSION)

date_time

Datetime

Current datetime

No

date of schedule of the task in format 'yyyy-mm-dd'. It is also supported to provide the following 'human named' dates:

  • NOW: date of the session (active user) in his timezone

  • MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY: The date corresponding to the specified day name.

Dates that are in the past are not allowed. If necessary the date will be increased until it a 'yet to come' date

n_days

Number

NULL

No

if parameter is set will be scheduled in N days after DATE_TIME if DATE_TIME is set or after today if DATE_TIME is not set.

hour

Time

NULL

No

Can be one of the following values:

  • NULL: The task will be inserted at the default hour specified in the WORKPLAN or at the current time if no default hour has been specified in the WORKPLAN

  • Hour in format hh:mm

  • NOW: The task will be inserted at the current time

  • UNSCHEDULED: The inserted TASK is not scheduled for any specific time of the day

condition

Boolean

true

No

If true the task insert will be executed

assignto_role

Number

NULL

No

the ROLE that will be assigned to the TASK by default. Check MEMBERSHIP OBJECT for role-id description.

See Assignation considerations below for more information about EVENT assignation

assignto_user

String

NULL

No

User assigned to the TASK by default. This value can be:

  • An string representing a USERNAME

  • A numeric expression representing a USER reference

See Assignation considerations below for more information about EVENT assignation

assignto_team

String

NULL

No

A TEAM CODE of the TEAM that will be assigned to the TASK

See Assignation considerations below for more information about EVENT assignation

closed

Boolean

false

No

if not null, close task after insert (YES), or keep open (NO) otherwise (null) use the "CLOSED" property in the TASK template

recursive_freq

String

SINGLE

No

Defines the frequency of the repetitive TASK. The value for this property has the format:

FREQUENCY{MODIFIER}[:MODE]

Where FREQUENCY must be one of the following values

  • SINGLE: normal TASK that will be executed only once. If another TASK with the same TASK_CODE is inserted on the same day, the FORMULA will do nothing (only one TASK per day allowed)

  • MULTIPLE: normal TASK that will be executed only once. It is allowed to insert more  than one TASK with the same TASK_CODE per day

  • EVERYHOUR: recursive TASK that will be replicated each hour

  • 4ADAY: recursive TASK that will be replicated each 6 hours

  • 3ADAY: recursive TASK that will be replicated each 8 hours

  • 2ADAY: recursive TASK that will be replicated each 12 hours

  • DAY: recursive TASK that will be replicated every day

  • WEEK: recursive TASK that will be replicated every week. Since API Version 2.7.21 it is possible provide a modifier to indicate in which days of the week the TASK should be re-scheduled (e.g, weekly on Mondays and Fridays)

  • BEWEEK: recursive TASK that will be replicated every 2 weeks

  • MONTH: recursive TASK that will be replicated every month

  • MONTH3: recursive TASK that will be replicated every 3 months (Available since API Version 2.7.28)

  • MONTH6: recursive TASK that will be replicated every 6 months (Available since API Version 2.7.28)

  • YEAR: recursive TASK that will be replicated every year

Frequency modifier

The :MODIFIER part is available since API Version 2.7.21.Currently it is only used when frequency = "WEEK", otherwise it will be ignored.

The value of the:MODIFIER allow to specify some days of the week where the TASK will be re-scheduled on a weekly basis. For example, it is possible to indicate that the TASK is recursive weekly on Mondays and Fridays. In this case, when a TASK scheduled for Monday is finished or expires, it will be rescheduled for the friday of the same week, and then for the Monday of the next week... etc.

The desired days of the week are specified by a concatenation of the initials of each day of the week (M: Monday, T: Tuesday, W: Wednesday, R: Thursday, F: Friday, S: Saturday, U: Sunday). Example: WEEK{MF} 

If no modifier is specified, then the TASK will be re-scheduled each week on the same day where it was created.

Recursion mode

The :MODE part (optional) defines how to apply the recursion: When a TASK is recursive, by default the next iteration will be calculated when the TASK is closed. Nevertheless it is possible to force the calculation of the next iteration automatically even when the TASK is not closed but the expected period to complete it has finished. The allowed values for MODE are:

  • (empty): default mode. The next iteration will be calculated when the TASK is closed

  • MOVE: When the estimated time for the next iteration arrives but the TASK is not closed yet, a system daemon will change automatically the scheduled hour to the one that corresponds to the next iteration

  • ADD: When the estimated time for the next iteration arrives but the TASK is not closed yet, a system daemon will create a new TASK but the original one will remain open

  • DEPRECATE: When the estimated time for the next iteration arrives but the TASK is not closed yet, a system daemon will expire it automatically and create a new TASK

parameters

JSON

NULL

No

Array of JSON strings with initial values that will be applied to the TASK inner ACTIVITIES. Each array item must be a JSON with 2 properties:

  • code: name of the ITEM_CODE to which the value will be assigned. NOTE: API Versions before 2.8.1 used the DATA_CODE instead of the ITEM_CODE

  • 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 each ACTIVITY inserted do 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 each ACTIVITY inserted already contains an array of ITEM with ITEM_CODES 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

 

Return value

Returns a reference to the TASK inserted

Execution

On closing the form. The ITEM containing this FORMULA must be defined as type 'ACTION' (which are always executed when a FORM is closed)

Examples

Formula

Description

Formula

Description

TASK_INSERT("SPIROS1", "2014-07-23", , ,$1)

A new TASK created form the TASK TEMPLATE with TASK_CODE="SPIROS1" will only be inserted if the value of ITEM $1 is true

TASK_INSERT( "PRESURG", $2,-7 ,"10:00", 1)

A new TASK created form the TASK TEMPLATE with TASK_CODE="PRESURG" will be inserted, the date will be set to the one specified in ITEM $2 and the date will be set to "10:00"

TASK_INSERT( "PRESURG", $2,,,, DAY)

A new TASK created form the TASK TEMPLATE with with TASK_CODE="PRESURG" will be inserted as a recursive TASK with frequency 'DAY'. The next iteration of the TASK will be calculated when it is closed

TASK_INSERT( "PRESURG", $2,,,, "DAY:MOVE")

A new TASK created form the TASK TEMPLATE with with TASK_CODE="PRESURG" will be inserted as a recursive TASK with frequency 'DAY'. The next iteration of the TASK will be create when it is closed, but the TASK will be automatically moved to the next time if it is not close within the expected period

TASK_INSERT( "ACTIVITY_STEPS", "MONDAY", , "NOW", 1, 39, , , , [{"code: "STEPS" , "value": 3421}])

A new TASK created form the TASK TEMPLATE with with TASK_CODE="ACTIVITY_STEPS" will be inserted assigned to ROLE "CASE" (39). The ITEM with ITEM_CODE="STEPS" will be initialized to 3241

TASK TEMPLATES with repeated TASK CODES

It is not reccomended to use the same TASK_CODE in different TASK TEMPLATES. Otherwise, the formula TASK_INSERT() will not know which is the good one and will return an error indicating that the TASK_CODE provided is ambiguous.

Nevertheless, since API Version 2.7.21, in some circumstances, it is possible to select the appropriate TASK TEMPLATE applying the following the rules:

  • If only one TASK TEMPLATE exists with the indicated TASK_CODE then proceed as now (insert normally)

  • Otherwise select only the TASK TEMPLATES defined in the same stage than the TASK being inserted

    • If only one template has been found, use it to insert the TASK normally

    • If more than one template has been found generate an error "AMBIGUOUS TASK CODE"

  • Otherwise select the TASK TEMPLATES defined in the stage "OPTIONAL"

    • If only one template has been found, use it to insert the TASK normally

    • If more than one template has been found generate an error "AMBIGUOUS TASK CODE"

Inserting a TASK in a different ADMISSION

By default, a TASK inserted with this FORMULA will belong to the ADMISSION from the context in which the FORMULA is executed.

From API Version 2.7.21 it is possible to insert a TASK in another PROGRAM of the same CASE by prepending the name of the PROGRAM to the TASK_CODE and separated by a semicolon (e.g. "PRG:CODE"). This is only possible under the following conditions:

  • There must exist an active ADMISSION (not discharged, paused or rejected) of the CASE in the selected PROGRAM (the PROGRAM and the SUBSCRIPTION of the ADMISSION must be active)

  • The active USER is a CASE or an ASSOCIATE of the CASE

  • The active USER is a PROFESSIONAL that is member of the target SUBSCRIPTION

Task assignment considerations

A TASK can be assigned to:

  • ROLE

  • ROLE and TEAM: It is not possible to assign an EVENT to a TEAM without specifying a ROLE

  • ROLE, TEAM and USER: It is not possible to assign an EVENT to a USER without specifying a TEAM and ROLE. Nevertheless it is allowed to leave the ASSIGNTO_TEAM parameter empty if it is possible to infer the TEAM from the ASSIGNTO_USER and ASSIGNTO_ROLE as explained below

ASSIGNTO_TEAM inference

As it was explained before, a TASK inserted using TASK_INSERT() always belongs to an ADMISSION, which was created for a specific SUBSCRIPTION.

When invoking TASK_INSERT() specifying values for ASSIGNTO_USER and ASSIGNTO_ROLE parameters, but leaving ASSIGNTO_TEAM empty, the system will try to infer the TEAM inspecting the SUBSCRIPTION members using the following RULES:

  • If ASSIGNTO_USER is direct member of the SUBSCRIPTION with the ROLE indicated in ASSIGNTO_ROLE, then the TEAM OWNER of the SUBSCRIPTION will be used as ASSIGNTO_TEAM

  • If ASSIGNTO_USER has ASSIGNTO_ROLE in a TEAM that is member of the SUBSCRIPTION with ASSIGNTO_ROLE, then it will be used as ASSIGNTO_TEAM

If no valid TEAM is found, then the inserted TASK will only be assigned to the specified ROLE