Summary

This article describes how to trigger inventory assignment with a script.

Table of Contents

Subject drug assignments are typically executed automatically upon subject randomization or manually through the use of the Assign Drug action. As an alternative, scripts can be used to automate the assignment based on entered data using the drugAssign command. Additional related functionality (such as automated resupply shipments and email notifications at the time of assignment) function as they typically would, regardless of the method used to trigger the assignment.

Note: The drug assignments triggered by scripts are not restricted by the user role’s drug assign permission; therefore, the user roles that can save the target question/form will be able to perform the drug assignment.


Sample Drug Assignment Script Structure

Below is an example of a script excerpt using the drugAssign command. The preceding elements (not included below) would set the conditions under which the drug assignment action should occur (for example, a specific response to a specific question), while the content of presented excerpt defines the details of the assignment such as the treatment type, the drug type and amount to be assigned, and the question to be updated with the assigned kit numbers.

<s:drugAssign 
     treatmentType="1" 
     overrideFreeze="true"     
     description="Visit 1">
    <s:question path="/visit1v.assignkits" />
    <s:drugType typeID="1">
        <s:drugAmount>
            <s:numberPath path=".assignAmount1:value" />
        </s:drugAmount>
    </s:drugType>
    <s:drugType typeID="2">
        <s:drugAmount>
            <s:numberPath path=".assignAmount2:value" />
        </s:drugAmount>
    </s:drugType>               
     <s:drugType typeID="3">
        <s:drugAmount>
            <s:numberPath path=".assignAmount3:value" />
        </s:drugAmount>
    </s:drugType>              
</s:drugAssign>

The treatmentType Attribute

If set, the treatmentType defines the matching ‘Treatment Type ID’ from the dataArchitect / configuration. The drugAssign command will perform an assignment of the drug type(s) associated with this treatmentType’s value as resolved from the configuration.

treatmentType Not Set and Subject is Randomized

The script will assign the drug associated with the treatment to which the subject is randomized/activated to, in quantity defined by the drugType / drugAmount matched parameters.

treatmentType Not Set and Subject is Not Randomized

No assignment will be performed.

treatmentType Set

The script will assign the treatment defined by the treatmentType attribute. The quantity of the drug type associated with this treatment type is the one defined by the matching drugType/drugAmount script’s pair of parameters. If drugType/drugAmount pair of parameters are not defined, the script will attempt next to resolve by matching to the treatment table rows from the configuration (see the ‘Treatment Table Row’ in the ‘Inventory’ tab of the dataArchitect); it will execute for the first treatment table match only. If no treatment table is defined, or there is no match the script will fail.

drugType and drugAmount

The drugType parameter’s typeID attribute defines the assignment’s drug type and must match one of the ‘Drug Type ID’ from the dataArchitect / configuration. While the most common implementation defines the drug type as an integer, a string is accepted as well.

The drugType parameter must be unique; if not, a compiler error will be shown. However, the compiler does not check if the script drugType matches the drug Type ID in the configuration.

The drugAmount parameter defines the quantity of drug associated with the command’s drugType and must resolve to an integer greater than zero.

The drug amount can be defined by using:

  • a static amount (Ex: <s:number value =”1”/>),
  • a path to a eCRF number variable, Ex: <s:numberPath path=”.assignAmmount1:value”/>)
  • a script expression/command that further calculates the drug amount
Note: If treatmentType is not set and the subject is not randomized/activated, the script will not perform.


Examples

Below are sample scenarios where the drugAssign command can be used.

Note: A drugAssign script cannot be triggered from a dependent path statement. Therefore, all questions that should trigger the reevaluation of the script should be listed as targets.


Example 1

Description

This example shows the assignment of a treatment type independent of the randomized treatment, specifying that treatment type 1 should be used (as defined by the treatmentType = “1” attribute.)

The script implements the following additional requirements:

  • treatmentType=”1” is associated with drugType=”1”
  • the drug quantity is 1 (see drugType/drugAmount).
  • the assignment will execute even if the question parameter is frozen (see overrideFreeze=”true”).
  • the Drug Assignment “Description” is “Visit 1″
<script scriptId="assignDrugVisit1">
    <body>
        <s:if>
            <s:and>
                <s:eq>
                    <s:numberPath path=":id" />
                    <s:numberPath path="/visit1v.assignyn:id" />
                </s:eq>
                <s:isSet />
                <s:eq>
                    <s:stringPath path=".assignyn:value" />
                    <s:string value="Y"/>
                </s:eq>
            </s:and>
            <s:drugAssign treatmentType="1" overrideFreeze="true" description="Visit1">
                <s:question path="/visit1v.assignkits" />
                <s:drugType typeID="1">
                    <s:drugAmount>
                        <s:number value="1" />
                    </s:drugAmount>
                </s:drugType>
            </s:drugAssign>
        </s:if>
    </body>
    <target action="update" shouldReconcile="false" typeId="assignyn" when="after"/>
</script>

Example 2

Description

This example shows the assignment of a treatment type based on the randomized treatment (treatmentType attribute is not configured).

The script implements the following additional requirements:

  • drug quantity is based on the existing treatment table row as defined in the Inventory worksheet (drugType/drugAmount parameters are not configured.
  • the assignment will not execute if the question parameter is frozen (see overrideFreeze not configured and default logic =”false”).
  • the Drug Assignment “Description” is “Visit 1″

In this configuration we assume the record is randomized to ‘treatment 3’; the script command will assign a quantity of 3 kits (as determined from the treatment table – see below the third treatment table row) of randomized matching treatment, which is ‘Drug Type ID = 3’ associated with ‘drug3’.

The treatment table for the Inventory configuration is:


<script scriptId="assignDrugVisit2">
    <body>
        <s:if>
            <s:and>
                <s:eq>
                    <s:numberPath path=":id" />
                    <s:numberPath path="/visit2v.assignyn:id" />
                </s:eq>
                <s:isSet />
                <s:eq>
                    <s:stringPath path=".assignyn:value" />
                    <s:string value="Y"/>
                </s:eq>
            </s:and>
            <s:drugAssign description="Visit2">
                <s:question path="/visit2v.assignkits" />
            </s:drugAssign>
        </s:if>
    </body>
    <target action="update" shouldReconcile="false" typeId="assignyn" when="after"/>
</script>


Example 3

Description

This example shows the assignment of a treatment type based on the randomized treatment (treatmentType attribute is not configured). The drug quantity is based on the drugType / drugAmount parameters.

The script implements the following additional requirements:

  • treatment type drug type configuration based on the image below
  • the assignment will execute if the question parameter is frozen (see overrideFreeze =”true”).
  • the Drug Assignment “Description” is “Visit 3″
  • drug amounts are configured with drugType / drugAmount parameters,
  • treatment 1 is drug 1, amount is 2. Therefore, if the record is randomized to treatment 1, it will assign 2 units of drug 1.
  • treatment 2 is drug 2, amount is calculated: 1 unit for each record’s full 50 Kg of weight. Therefore, if the record is randomized to treatment 2 and the record’s weight is 180Kg it will assign 3 units of drug 2.
  • treatment 3 is drug 3, amount is defined by the value resolved at path “.assignAmount3”. Therefore, if the record is randomized to treatment 3, and integer value at path “.assignAmount3” resolves to 4, it will assign 4 units of drug 3.

The treatment table for the Inventory configuration is:


<script scriptId="assignDrugVisit3">
    <body>
        <s:if>
            <s:and>
                <s:eq>
                    <s:numberPath path=":id" />
                    <s:numberPath path="/visit3v.assignyn:id" />
                </s:eq>
                <s:isSet />
                <s:eq>
                    <s:stringPath path=".assignyn:value" />
                    <s:string value="Y"/>
                </s:eq>
            </s:and>
            <s:drugAssign overrideFreeze="true" description="Visit3">
                <s:question path="/visit3v.assignkits" />
                <s:drugType typeID="1">
                    <s:drugAmount>
                        <s:number value="2" />
                    </s:drugAmount>
                </s:drugType>
                <s:drugType typeID="2">
                    <s:drugAmount>
                        <s:floor>
                            <s:divide>
                                <s:numberPath path=".assignWeight:value" />
                                <s:number value="50" />
                            </s:divide>
                        </s:floor>
                    </s:drugAmount>
                </s:drugType>
                <s:drugType typeID="3">
                    <s:drugAmount>
                        <s:numberPath path=".assignAmount3:value" />
                    </s:drugAmount>
                </s:drugType>
            </s:drugAssign>
        </s:if>
    </body>
    <target action="update" shouldReconcile="false" typeId="assignyn" when="after"/>

drugAssignCheck Command

In cases where a drug assignment could fail, the drugAssignCheck command can be used in a script to test if the assignment can be successfully performed; its return value should be used as a way to execute the drugAssign and/or to notify the user of a failure, and of course identify the reason if necessary.

Examples

Example 1

Description

This example shows how the drugAssignCheck command can be used in an alert script to determine if a drug assignment can successfully complete. If it cannot complete, the specified alert text will display.

<script scriptId="drugAssignCheckVisit3">
    <body>
        <s:alert>
            <s:expression>
                <s:or>
                    <s:ne>
                        <s:numberPath path=":id" />
                        <s:numberPath path="/visit3v.assignyn:id" />
                    </s:ne>
                    <s:not>
                        <s:isSet />
                    </s:not>
                    <s:ne>
                        <s:stringPath path=".assignyn:value" />
                        <s:string value="Y"/>
                    </s:ne>
                    <s:eq>
                        <s:drugAssignCheck               overrideFreeze="true">
                            <s:question path="/visit3v.assignkits" />
                            <s:drugType typeID="1">
                                <s:drugAmount>
                                    <s:number value="2" />
                                </s:drugAmount>
                            </s:drugType>
                            <s:drugType typeID="2">
                                <s:drugAmount>
                                    <s:floor>
                                        <s:divide>
                                            <s:numberPath path=".assignWeight:value" />
                                            <s:number value="50" />
                                        </s:divide>
                                    </s:floor>
                                </s:drugAmount>
                            </s:drugType>
                            <s:drugType typeID="3">
                                <s:drugAmount>
                                    <s:numberPath path=".assignAmount3:value" />
                                </s:drugAmount>
                            </s:drugType>
                        </s:drugAssignCheck>
                        <s:string value="" />
                    </s:eq>
                </s:or>
            </s:expression>
            <s:correction>
                <s:string value="optional"/>
            </s:correction>
            <s:text>
                <s:concat>
                    <s:string value="Drug assignment cannot complete. Please check stock and configuration. (Error: "/>
                    <s:drugAssignCheck overrideFreeze="true">
                        <s:question path="/visit3v.assignkits" />
                        <s:drugType typeID="1">
                            <s:drugAmount>
                                <s:number value="2" />
                            </s:drugAmount>
                        </s:drugType>
                        <s:drugType typeID="2">
                            <s:drugAmount>
                                <s:floor>
                                    <s:divide>
                                        <s:numberPath path=".assignWeight:value" />
                                        <s:number value="50" />
                                    </s:divide>
                                </s:floor>
                            </s:drugAmount>
                        </s:drugType>
                        <s:drugType typeID="3">
                            <s:drugAmount>
                                <s:numberPath path=".assignAmount3:value" />
                            </s:drugAmount>
                        </s:drugType>
                    </s:drugAssignCheck>
                    <s:string value=")."/>
                </s:concat>
            </s:text>
        </s:alert>
    </body>
    <target action="update" typeId="assignyn" when="preprocess"/>
    <dependent path="/visit3v.assignkits"/>
    <dependent path="/visit3v.assignWeight"/>
    <dependent path="/visit3v.assignAmount3"/>
</script>


Need more help?

Please visit the Fountayn Contact Information page.