getDispensationInfo( )

Retrieves detailed information about a subject's dispensation history. For example, last doses, dispensation dates, and kit information.

WARNING:

Consider the following:

• This helper function may return unblinding information. Therefore, use the returned information carefully to preserve the study's blind.
• When using this helper function, the target and rule variables must be derived from a non-repeating (flat) form. The rule doesn't save if the target or variable references a repeating form, two-section form, or lab form.

You can use this rule helper function for the following use cases:

• For forced titration studies, knowing the last dose is crucial to determine the next dose or kit type. The system captures information on a subject's last dose, aiding advanced dispensation processes.
• Before dispensing the planned next dose (for example, 20 mg of Ibuprofen), the system checks that the subject has been on their current dose for the required number of days. If this minimum duration hasn't been met, the subject will not receive the next dose. This process uses helper functions to track the last dispensation date and administered dose.

Rules are triggered by data submit. Performing system actions will not trigger rules to run. All data returned by the helper functions described here will be as of the time that the rule is run. If the information changes after the rule is run, this will not cause the rule to re-run.

Syntax

getDispensationInfo(referenceVisit, eventInstanceNumber, includeUnscheduleVisits, includeReplacementKit)

Parameters

Tip:

Locally sourced kits and dosing information recorded by site staff is excluded. For dosing information collected directly by the site staff (for example, dispensation observations collected as text), you must retrieve the data separately using the getQuestionValue( ) helper function.

Parameter	Required or optional	Description
referenceVisit	Required	A string value or variable name that specifies the visit context. It can have one of the following values: The current visit for the target is used to determine the appropriate last or next dose, or the starting point for dispensation visits. last: Returns the most recent dose, kit information, dispensed date, quantity, and hold status based on the rule target. The last parameter is determined by visit date. This includes unscheduled and replacement visits, unless they are excluded using the optional parameters. If the unscheduled visit isn't completed, the information for the last dispensation completed in the system will be returned for the last parameter. all previous: Returns all previously dispensed doses in reverse chronological order, with the most recent dose first. If an unscheduled visit isn't completed, all dispensation information for that visit will be returned for the all previous parameter. variable name: Enter the name of the variable, as defined in the Variables section, to return the dose dispensed for a specific visit. This would be the visit selected in the given variable definition. This requires creating a Visit Information global variable that points to the specified visit. See Define rule variables. Note - If you pass in a variable name, you must specify the eventInstanceNumber. See below.
eventInstanceNumber	Optional	Required if you passed in a variable as the referenceVisit. An integer value representing the instance number for an unscheduled or cycle visit when a visit variable name is provided. If the referenced visit is part of a cycle or is an unscheduled visit, the helper function returns multiple instances. Therefore, you must pass an eventInstanceNumber object to identify which occurrence to retrieve.
includeUnscheduleVisits	Optional	If set to Y, unscheduled visits are included. By default, unscheduled visits are considered. If set to N, unscheduled visits are ignored. Returns boolean (true or false) values: True for included unscheduled visits, False for excluded unscheduled visits. Unscheduled visits are considered chronologically based on visit date (as opposed to instance number), unless excluded from the rule helper function.
includeReplacementKit	Optional	If set to Y, replacement kits are included. By default, replacement kits are considered. If set to N, replacement kits are ignored. Returns boolean (true or false) values: True if replacement kits are included, False if replacements kits are excluded.

Return value

Note:

Consider the following:

• When needing data from multiple visits, use the all previous parameter. Then, use getValues() to find values for specific visits. This improves rule efficiency.
• If multiple kit types are dispensed during a visit, the helper function includes a return for each kit.
• For dose holds specified under the last parameter:
  • Returns the most recent dispensed dose if all doses at that visit are held.
  • If at least one dose was dispensed, it returns those doses, and "Dose Held" for held doses.
  • Dosing information recorded by the site will not be included in the return. This will need to be retrieved by the rule designer from the question directly.
  • For non-dispensation visits, the all previous parameter will return all completed dispensations, while the last parameter will return the last dispensation completed in the system.
• Although visit and dispensed dates are returned in the site's local time zone and system date format, they display with a GMT timestamp in the Debug window to support mathematical operations.
• For non-dispensation visits, the all previous parameter will return all completed dispensations and the last parameter will return the last dispensation completed in the system.

Returns an array of objects including each drug dispensed at the applicable visit (depending on the provided parameter). Each object contains the following information in the following format:

    {         
"visitName": "visitName",     
"eventInstanceNumber":"eventInstanceNumber",  
"kitType":"kitType",  
"kitDescriptione":"kitDescription",  
"dateDispensed":"dateDispensed", 
"dosage":"dosage",  
"quantity":"quantity", 
"isHeld":"true/false"     
}

The information for each object is included as the following attributes:

Attribute	Description
visitName	Name of the visit. Will include the cycle or unscheduled number, as well.
eventInstanceNumber	Instance number of the unscheduled visit or cycle number. Can return null.
kitType	Indicates the kit type, as specified by the study designer Create Investigational Product Kit Type dialog.
kitDescription	Description of the kit, including the drug name as specified by the designer on the Create Investigational Product Kit Type dialog.
dateDispensed	Indicates the date the kit was dispensed. For the next parameter, no dispensation date or kit information is returned if it hasn't occurred yet.
dosage	Dosage of the drug dispensed. If the dose is held, this will return "null".
quantity	Quantity of the drug dispensed. If the dose is held, this will return "null".
isHeld	Returns boolean (true or false values): "true" if dose is held, "false" if was dispensed.

Example 3-95 Get dispensation and kit details for a subject visit

var aDesc = null;
function useDispResult(dItem)
{
    logMsg('visitName: '+ dItem.visitName);
    logMsg('eventInstanceNumber: '+ dItem.eventInstanceNumber);
    logMsg('kitType: '+ dItem.kitType);
    logMsg('kitDescription: '+ dItem.kitDescription);
    logMsg('dateDispensed: '+ dItem.dateDispensed);
    logMsg('dosage: '+ dItem.dosage);
    logMsg('quantity: '+ dItem.quantity);
    logMsg('isHeld: '+ dItem.isHeld);
    aDesc = dItem.kitDescription;
    var today = new Date();
    if(dItem.dateDispensed!=null)
    {
       logMsg("diff: " + dateDiffInDays(today, dItem.dateDispensed));
    }
}
var resDisp=getDispensationInfo('vVar', null, 'Y', 'Y');
if(resDisp)
{ 
    resDisp.forEach(useDispResult);
}
return aDesc;