Trial Data Solutions: script to run a rule

a script for scheduling a rule

In some situations you may want to execute a Rule not when the user hits the Save-button, but for example every night, or at the start of each working day. Suppose you have a trial where the StudySubjects should have a follow-up visit 6 months after the date of signing their Informed Consent.

fig. 1: the CRF

And based on the example of fig. 1, we would like to get an e-mail on December 1, to remind us that we must contact the StudySubject for a new Visit.

first the rule

The message will be send by a Rule and we will need the OIDs of the CRF, the Item Group and the Item. How to do this is explained here in detail.
Once we have them, we put them in the header of our Rule-file and we write the EMailAction

fig. 2: the EMailAction

Note the Run-tag, which states that the Action should only be executed on Batch: <Run AdministrativeDataEntry="false" InitialDataEntry="false" DoubleDataEntry="false" ImportDataEntry="false" Batch="true" />
Now we must create our expression which should look something like this:

fig. 3: the Expression

Now we can upload the Rule and receive the congratulations etc and our Rule is ready to be run, but the only way to do that is by going to the list of rules and click on the Run-icon. And do that every day.

fig. 4: running the Rule manually

surely there's an easier way

And yes, there is an easier way to do this than by logging in to OpenClinica, going to the list of Rules, browsing to our Reminder-mail-Rule, clicking on the Run-icon and finally confirming that we want to execute the Action. How? First click on the Run-icon and then look at the address-bar. In our case it says
http://www.tds-training.com/oc34/RunRuleSet?ruleSetId=6&ruleId=5
and when we look at the source of the page, we discover that clicking the button Submit is equal to requesting
http://www.tds-training.com/oc34/RunRuleSet?ruleSetId=6&dryRun=no
This means that we can make life easier by creating a book-mark in our browser for the second URL and by clicking on it we run the Rule. A step forward indeed, but it would be nicer to have this executed as a scheduled task.

fig. 5: the URL to run the Rule manually

a script to do all this

There is nothing wrong with the method described above, that is to make a book-mark of the link and to start each working day with clicking on the link, but it would be much nicer to have a script do that. We can do that by using a text-editor like Notepad++ and saving the following text as a vbs-file. The only thing that must be changed is the URL of your server plus the name of your OpenClinica- instance:
strURLStart = "http://www.tds-training.com/oc34/"


 
Option explicit
Dim objIEDebugWindow
Dim objHTTP
Dim strURLStart
Dim strURL 
Dim strReq 

If WScript.Arguments.Count <> 3 then
  WScript.Echo "Missing parameters. This script needs: "_
  & VbNewLine & "username, password and CRFID or RuleSetID"_
  & VbNewLine & "to run correctly."
Else
  Set objHTTP = CreateObject("MSXML2.XMLHTTP")
  'change this to match your situation
  strURLStart = "http://www.tds-training.com/oc34/"
  'j_spring_security_check
  strURL = strURLStart & "j_spring_security_check?j_username=" & WScript.Arguments(0) 
  strURL = strURL & "&j_password=" & WScript.Arguments(1)
  objHTTP.Open "POST", strURL, False
  objHTTP.send
  'uncomment the next line if you want to check if the authorization went OK
  'debug (objHTTP.responseText)

  'choose one of the following: 
  'this first line will run all Rules for a CRF, 
  'strURL = strURLStart & "RunRule?crfId=" & WScript.Arguments(2) & "&action=true"
  'this second line will run one RuleSet
  strURL = strURLStart & "RunRuleSet?ruleSetId=" & WScript.Arguments(2) & "&dryRun=no"

  objHTTP.Open "GET", strURL, False
  objHTTP.send

  'uncomment the next line if you want to check if the execution of the rule(s) went OK
  'debug (objHTTP.responseText)
  WScript.Echo "finished"
End if

'the following procedure is used to check the responses of the HTTP requests
'it opens a browser window and displays whatever is given as parameter myText
Sub Debug( myText )
  'open a browser window if it is not already open
  If Not IsObject( objIEDebugWindow ) Then
    Set objIEDebugWindow = CreateObject( "InternetExplorer.Application" )
    objIEDebugWindow.Navigate "about:blank"
    objIEDebugWindow.Visible = True
    objIEDebugWindow.ToolBar = False
    objIEDebugWindow.Width = 200
    objIEDebugWindow.Height = 300
    objIEDebugWindow.Left = 10
    objIEDebugWindow.Top = 10
    Do While objIEDebugWindow.Busy
      WScript.Sleep 100
    Loop
    objIEDebugWindow.Document.Title = "IE Debug Window"
    objIEDebugWindow.Document.Body.InnerHTML = "<b>" & Now & "</b></br>"
  End If
  'add the text from the parameter to what's already there
  objIEDebugWindow.Document.Body.InnerHTML = _
  objIEDebugWindow.Document.Body.InnerHTML _
  & myText & "<br>" & vbCrLf
End Sub

now what exactly happens here?

The script is not so hard to understand. First it counts the number of parameters, because it needs three: the OC-username, the OC-password and the RuleSetID. You may wonder where to get that last bit from, but that was in the URL, when we ran the Rule manually: RunRuleSet?ruleSetId=6.
We start with making a trusted connection, using j_spring_security_check: we POST our name and password.
Now we can execute the Rule-set, by making a GET for the URL with RunRuleSet in combination with the right ID and that is all.

To test this script we save it and then we open a command prompt and change to the folder with the script. We then start it with the three parameters. After completion a message-box appears, saying "finished".

There is also the option to "debug" whatever responses OpenClinica gives by using the procedure Debug.

fig. 6: testing the script (and no, my password is not XXXXXX)

And if we did everything the right way and the proper way, we should see a mail like this:

fig. 7: mail

schedule this, please

Can we make life easier still? Sure: by scheduling this script. And before you do that, comment out the WScript.Echo "finished". And don't forget to supply the parameters.

fig. 8: scheduling the script (look, I told you my password is not XXXXXX!)

so, what about the other URL?

You may have noticed that in the script you can choose between running a Rule-set and running all rules for a CRF. Where did that come from? Well, if we go to the list of CRFs and in it to the CRF Screening, we can click on the magnifier-icon of the original.

fig. 9

fig. 10

At the end of the following screen we can click on Run All Rules for this CRF which is
http://www.tds-training.com/oc34/RunRule?crfId=1&action=no
With this URL we must submit/confirm, but if we change the URL to
http://www.tds-training.com/oc34/RunRule?crfId=1&action=true
then the execution will be immediately.

By un-commenting the line starting with 'strURL = strURLStart & "RunRule?crfId=" and commenting out the line with strURL = strURLStart & "RunRuleSet?ruleSetId=" we change the script in such a way that it will run all Rules for this CRF. You may want to use this in a situation where you have many Validations in a CRF and you do not want to slow down the data-entry by running them all at time of entry.

Other how-to-pages can be found here.

this page was last reviewed December 2014