getVisitWndw( )

Retrieve visit window and schedule details for one or more visits. Options include: a specified visit, the next visit (based on current dynamic and branching calculations for the subject), the current visit, or all previous visits as designed in the study.

Note:

Unscheduled visits, Withdrawal, Study Completion, Screen Fail, Rescreen visits, and Adverse Events aren't supported as they're unscheduled by nature. If next or previous visit is used, any unscheduled visits will be ignored and the first scheduled visit that is encountered when moving in the specified direction (next or previous) will be returned. If current or visit information is used then null would be returned.

For example, you can use this rule helper function for the following use cases:

• If a subject is due for dispensation today and the next visit window is more than 21 days away, the site user should be notified that an unscheduled dispensation visit will be required before the next visit.
• If there's an unscheduled visit, the number of days until the next scheduled visit should be considered to determine the number of kits to dispense, so investigational product isn't wasted.
• You can configure an email notification to be sent to specific users if a visit occurs outside of the configured visit window.

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

getVisitWndw(referenceVisit, eventInstanceNumber)

Parameters

You can pass one of the following parameters to specify the context of the visit window you want returned:

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: current: Returns the window of the current visit based on the rule target. next: Returns the window of the next expected visit based on the rule target. If part of a branch, this visit is determined dynamically. Next visit values are based on the current branching logic at rule runtime. all previous: Returns the window of all the previous visits, even if a previous visit was skipped. variable name: Enter the name of the variable, as defined in the variables section, to return the visit window 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.
eventInstanceNumber	Optional	Required if you passed a variable as the referenceVisit that references a cycling branch visit. An integer value that represents the instance number for a cycle visit when a visit variable name is provided. Otherwise, the rule uses the eventInstanceNumber of the target. This parameter can also accept a null value.

Return values

Note:

Consider the following:

• When using next or all previous, unscheduled visits are ignored. Instead, the system returns the first scheduled visit in the specified direction (next or previous). If current or the Visit Information variable is used, a null value is returned.
• If the specified visit is within a cycle, all instances are returned as an array.
• All dates are calculated based on the information entered by the site. However, in the Debug window, dates display with a GMT timestamp to support accurate time-based calculations and mathematical operations.

Returns array of objects, with an object for each applicable visit, depending on the provided parameter. Each object contains the following information in the following format:

 {         
"visitName": "visitName",
"eventInstanceNumber":"eventInstanceNumber",   
"scheduledDate":"scheduledDate",         
"scheduledWndwStartDate":"scheduledWndwStartDate", 
"scheduledWndwEndDate":"scheduledWndwEndDate",  
"isSkipped":"T/F"     
}

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

Attribute	Description
visitName	Name of the visit. To get the actual visit date, you must retrieve that separately using other variables. For more information, see Define rule variables.
eventInstanceNumber	Instance number of the unscheduled visit or cycle number.
scheduledDate	Indicates the calculated scheduled visit date, even if an actual visit occurred earlier or later ("Scheduled Date"). The scheduledDate object represents the calculated date based on the anchor visit date as specified in the Scheduled From field when a study designer defines the visit schedule.
scheduledWndwStartDate	Visit window's start ("From Date"), based on the number of days specified by the study designer, as the Before Days in the Visit Window.
scheduledWndwEndDate	Visit window's end ("To Date"), based on the number of days specified by the study designer, as the After Days in the Visit Window.
isSkipped	Indicates True if the visit was skipped; False if otherwise.

Example 3-94 Get visit window information for a subject visit

var vWnd = getVisitWndw('vVar', null);
if(vWnd) 
{
   logMsg(vWnd[0].scheduledWndwStartDate);
   var today = new Date();
   logMsg("diff vWnd: " + dateDiffInDays(today, vWnd[0].scheduledWndwStartDate));
}