how to build and deploy openclinicacrf data service...

HowtoBuildandDeployOpenClinicaCRFDataServiceVersion1.21OverviewThisdocumentdescribestheprocesstofollowforsettinguptheOpenClinicaCRFDataService.TheOpenClinicaCRFDataServiceprovidesgrid‐enabledaccesstoclinicaldatastoredinOpenClinicathroughtheinformationmodelshowninFigure1.TheinformationmodelcorrespondstoasubsetoftheOpenClinicadatabaseschemaanddescribestherelationshipofstudies,subjects,andcasereportforminformation.TheOpenClinicaCRFDataServiceallowsuserstonavigatethismodelbysubject,study,ortypeofcasereportformdata.2RequiredSoftwareName VersionJava 1.5(Note:1.6willnotwork)Ant 1.6.5Tomcat 5.0.28PostgreSQL 8.1.11Subversionclient 1.4.2OpenClinica 2.0caGrid 1.2caCORESDK 4.0(modified;seesection3.1)3BuildingtheOpenClinicaCRFDataService3.1BuildingandDeployingtheOpenClinicacaCORESDKApplicationTheOpenClinicacaCORESDKapplicationisbuiltwithcaCORE4.0,modifiedtosupportthePostgreSQLdatabasesystem–datainOpenClinicaisstoredinaPostgreSQLdatabase,butcaCOREdoesnotitsupportitbydefault.PleasecontacttheCVRGteamtoobtainthemodifiedcaCORESDKinstance.ThemodificationsareconfigurationchangestoenableacaCORESDKgeneratedapplicationtoaccessaPostgreSQLdatabasebackend.NomodificationshavebeendonetothecorecaCORESDKsystem.Inthisdocument,$CACORE_SDK_HOMEreferstothepathofthecaCORESDKapplicationdirectory.BeforebuildingthecaCORESDKapplication,youmustperformtwopreparationsteps:

1. InstallPostgreSQLandcreatetheOpenClinicadatabase.InstructionsfordoingthiscanbefoundontheOpenClinicawebsite:http://www.openclinica.org/.

2. InstallaTomcatcontainer.

a. ThisTomcatcontainerinstancewillhosttheOpenClinicacaCORESDKapplication.

b. ThelocationofthisTomcatinstancewillbereferredtoas$CACORE_SDK_CATALINA_HOMEinthisdocument.

c. Instructionsforinstallinganon‐secureTomcatcontainerviathecaGridinstallercanbefoundat:http://wiki.cagrid.org/display/caGrid12/caGrid+Installer+User%27s+Guide#caGridInstallerUser%27sGuide‐ConfigureContainer.

3. YoumustconfigurethecaCORESDKpropertiesfiletoproperlybuildthe

application.a. Openthefile$CACORE_SDK_HOME/conf/deploy.properties.b. FindthesectionlabeledAPPLICATIONSERVERPROPERTIES.c. SetSERVER_TYPEto“other”,andsetSERVER_URLtothepathtotheTomcat

instancethatwillcontaintheapplication.Forexample,ifTomcatisrunningonlocalhostonport8081,thetwolinesinthissectionwouldreadasfollows:

SERVER_TYPE=other SERVER_URL=http://localhost:8081/${PROJECT_NAME}

Figure1.OpenClinicainformationmodel

4. FindthesectionlabeledMODELPROPERTIES,andsettheMODEL_FILEand

MODEL_FILE_TYPEvariablestomatchthepropertiesofyourmodelfile.a. Forexample,ifyourmodelXMIfileiscalledopenclinica‐model.xmiandit

wasgeneratedbyEnterpriseArchitect,thevariableswouldbesetasfollows:

MODEL_FILE=openclinica-model.xmi MODEL_FILE_TYPE=EA

Note:Themodelfilemustbestoredin$CACORE_SDK_HOME/models.

5. FindthesectionlabeledDATABASECONNECTIONPROPERTIESandmodifyittoreflectyourPostgreSQLdatabasesettings.Forexample:

# A database named “openclinica” running on localhost DB_CONNECTION_URL=jdbc:postgresql://localhost/openclinica

# Database user that owns the openclinica database DB_USERNAME=clinica

# No password needed for the clinica user to access the database DB_PASSWORD=

# JDBC PostgreSQL driver DB_DRIVER=org.postgresql.Driver

# Hibernate dialect value DB_DIALECT=org.hibernate.dialect.PostgreSQLDialect

6. NowyouarereadytobuildtheOpenClinicacaCORESDKapplication.Dosousing

Ant:

cd $CACORE_SDK_HOME ant build-system

Theresultofthisbuildprocessisafilecalledopenclinica.warin$CACORE_SDK_HOME/output/openclinica/package/webapp.CopythisfiletoyourTomcatinstance:

cp $CACORE_SDK_HOME/output/openclinica/package/webapp/openclinica.war $CACORE_SDK_CATALINA_HOME/webapps/

7. Toverifythatthebuildanddeploymentweresuccessful,navigatetotheURLofyourapplicationinaWebbrowser.

a. Usingtheexamplesettingsdefinedearlier,theURLwouldbe:http://localhost:8081/openclinica.

3.2GeneratingandDeployingtheOpenClinicaCRFDataServiceTheOpenClinicaCRFdataserviceisgeneratedusingthecaGridIntroducetoolkit.Tobegin,navigateto$CAGRID_LOCATIONandloadIntroduce.

cd $CAGRID_LOCATION ant introduce

WhenthemainIntroducescreencomesup,clickCreatecaGridServiceSkeleton.

ThiswillstartthecaGridServiceSkeletoncreationwizard.Thefirstwindowasksyoutodefinetheservice;thereare4stepstodoingso:

Step1:Selectadirectorytoyourservice.Thiscanbewhateveryoulike.Step2:Nameyourservice.Itshouldbenamed:OpenClinicaCRF.Step3:SpecifyaJavapackageforthegeneratedcode.Thiscanalsobewhateveryoulike,butsomethinglikeorg.cvrgrid.openclinicacrfworkswell.Step4:SpecifythenamespacefortheWSDL.Thisfieldisautomaticallyfilledinbasedontheprevioussteps.

Under“CustomizetheService”,selectDataService.ClickCreate.Sincethisisadataservice,theDataServiceConfigurationwizardappears.ItfirstasksyouselectaServiceStyle.Select“caCORESDKv4.0”andclickOK.ThiswillstarttheCreatecaCORESDKBackendcaGridDataServicewizard.Thefirstwindowwilldisplayadescriptionofthewizard.Click“Next:Configuration”.Intheconfigurationstep,selectSimpleandclickBrowsetoselecttheSDKOutputDirectory.Inthefilechooserdialog,navigateintothecaCORESDKdirectoryandselecttheoutputdirectory.Thiswillautomaticallyfillinseveralotherfields.

FortheAPI,selectRemoteAPI.ThiswillrequireyoutoenterthehostnameandportofwhereyoudeployedtheOpenClinicacaCOREapplicationto.

Note:Thehostnamemustbeginwith“http://”.ThenextwindowallowsyoutospecifywhetherornotthecaCORESDKapplicationusessecurity.Leavethe“UseSecurity”boxunchecked.Step4istospecifythedomainmodel.Selectthe“DomainModelFromFile”option,thenclicktheBrowsebuttontoselectthedomainmodelfile.Inthefileselectiondialog,navigatetotheOpenClinicadomainmodelXMIfile.

Note:BesuretochangethefileselectionfiltertoXMLMetadataInterchangeFiles(*.xmi).

ThisbringsuptheGenerateDomainModelwindow,withtheXMIFilefieldprefilled.ForXMIType,selectSDK4.0XMIfromEA.ForProjectShortNameandProjectVersion,enterOpenClinicaCRFand1.0,respectively,andclickOK.

OncecontrolreturnstotheDomainModelSelectionwindow,clickNext:Schemas.InthePackagetoSchemaMappingwindow,clickMapFromConfig,thenclickDone.Introducewillnowcompletethecreationprocessoftheservice.

TheModifyServiceInterfaceappears.

3.3SecuringtheServiceSelecttheServicestab.SelectOpenClinicaCRF(MainService).

ClickModifyService.TheModifyServiceContextwindowcomesup.

WithintheSecureCommunicationtab,underSecurityConfiguration,selecttheCustomradiobuttonthenchecktheTransportLayerSecuritybox(leavetheSecureConversationandSecureMessageboxesunchecked).LeavetheTLSCommunicationMethodsettoPrivacy.Next,selecttheAuthorizationtab.KeepAnonymousClientssettoNo,butsetAuthorizationMechanismtoGridGrouper.Atwo‐paneinterfacenowappears.

IntheGridGrouperBrowserpane,clickLoad.Thiswillloadtheavailablegroupsforthetargetgrid.Findthegroupyouwanttograntserviceaccesstoandselectit.IntheGridGrouperExpressionEditorpane,selecttheANDexpression,andclicktheAddGroupbutton.ThenclickDonetoreturntotheModifyServiceInterfacewindow.ClickSavetosaveyourchanges.3.4DeployingtheServiceFromaterminal,navigatetothedirectoryoftheOpenClinicaCRFserviceyoujustcreated.Setthe$CATALINA_HOMEenvironmentvariabletothelocationofyoursecureTomcatinstancethatwillhosttheservice.(YoucanfindinstructionsforinstallingasecureTomcatcontainerusingthecaGridInstallerat:http://wiki.cagrid.org/display/caGrid12/caGrid+Installer+User%27s+Guide#caGridInstallerUser%27sGuide‐ConfigureContainer).Forexample,inbash,export CATALINA_HOME=~/tomcat-secure/jakarta-tomcat-5.0.28

RuntheAnttasktodeploytheservicetotheTomcatinstancespecifiedby$CATALINA_HOME:ant deployTomcat Theserviceisnowdeployed.YoucanverifythisbynavigatingtotheserviceURLinaWebbrowser.Forexample,ifthesecureTomcatcontainerisrunningonlocalhostonport8443,theURLwouldbe:https://localhost:8443/wsrf/services/cagrid/OpenClinicaCRF.4OpenClinicaCRFClientAPITheservicecreatedinSection3isastandardcaGriddataservice.Itprovidesthestandardqueryinterface.TheinformationmanagedbytheservicecanbequeriedusingCQLandtheOpenClinicainformationmodel.Wehavedevelopedasetofclient‐sidehelperclassesfortheimplementationoftheOpenClinicadataservicethatisdistributedwiththeCVRGsoftwarestack.ThesehelperclassesenableadevelopertoperformcommonquerieswithoutdealingwiththespecificsofCQL(althoughthisfunctionalityisstillavailable).Notethatthesehelperclassesarenotautomaticallygenerated,whenthedataserviceiscreatedasdescribedinSection3.4.1HelperClassesforNavigatingtheOpenClinicaInformationModelThefollowinghelperclassesandmethodsareincludedintheCVRGimplementationoftheOpenClinicadataservice:

‐ SubjectQueryHelpero FacilitatesnavigationoftheOpenClinicainformationmodelfroma

particularsubjecttothestudiesitisassociatedwith.o Methods

Constructor• public SubjectQueryHelper(Subject subject,

OpenClinicaCRFClient client)

o CreatesanewSubjectQueryHelperusingthegivenSubjectasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters subject–theSubjectthatwillserveasthe

sourceofnavigation client–theOpenClinicaCRFClientthatis

invokingtheservice

public List<Study> getStudies()

• Retrievesthestudiesassociatedwiththespecifiedsubject• Parameters:None• Return:alistofStudyobjectsassociatedwiththespecified

Subject• Throws:java.rmi.RemoteExceptionifthereisaproblem

contactingtheservice

‐ StudyQueryHelper

o FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularstudytothesubjects,studyeventdefinitions,andcasereportformsassociatedwithit.

o Methods Constructor

• public StudyQueryHelper(Study study, OpenClinicaCRFClient client)

o CreatesanewStudyQueryHelperusingthegivenStudyasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters study–theStudythatwillserveasthesource

ofnavigation client–theOpenClinicaCRFClientthatis

invokingtheservice

public List<Subject> getSubjects()

• Retrievesthesubjectsbelongingtothespecifiedstudy• Parameters:None• Return:alistofSubjectobjectsassociatedwiththegiven

Study• Throws:java.rmi.RemoteExceptionifthereisaproblem


public List<CaseReportForm> getCaseReportForms()

• Retrievesthecasereportformsrelatedtothegivenstudy• Parameters:None• Return:alistofCaseReportFormobjectsassociatedwiththe

givenStudy• Throws:java.rmi.RemoteExceptionifthereisaproblem


public List<StudyEventDefinition> getStudyEventDefinitions()

• Retrievesthestudyeventdefinitionsthatincludethegivenstudy

• Parameters:None• Return:alistofStudyEventDefinitionobjectsassociated

withthegivenStudy• Throws:java.rmi.RemoteExceptionifthereisaproblem


‐ StudyEventQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularstudyeventtothestudyeventdefinition,casereportformversions,subjects,andstudyassociatedwithit.


• public StudyEventQueryHelper(StudyEvent studyEvent, OpenClinicaCRFClient client)

o CreatesanewStudyEventQueryHelperusingthegivenStudyEventasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters studyEvent–theStudyEventthatwillserveas

thesourceofnavigation client–theOpenClinicaCRFClientthatis

invokingtheservice

public StudyEventDefinition getStudyEventDefinition()

• Retrievesthestudyeventdefinitionthatdefinesthespecifiedstudyevent

• Parameters:None• Return:theStudyEventDefinitionassociatedwiththegiven

StudyEvent• Throws:java.rmi.RemoteExceptionifthereisaproblem


public List<CRFVersion> getCRFVersions()

• Retrievesthecasereportformversiondataassociatedwiththegivenstudyevent

• Parameters:None• Return:alistofCRFVersionobjectsassociatedwiththegiven

StudyEvent• Throws:java.rmi.RemoteExceptionifthereisaproblem


public Subject getSubject()

• Retrievesthesubjectassociatedwiththegivenstudyevent• Parameters:None• Return:theSubjectassociatedwiththegivenStudyEvent• Throws:java.rmi.RemoteExceptionifthereisaproblem


public Study getStudy()

• Retrievesthestudyassociatedwiththegivenstudyevent• Parameters:None• Return:theStudyassociatedwiththegivenStudyEvent• Throws:java.rmi.RemoteExceptionifthereisaproblem


‐ StudyEventDefinitionQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularstudyeventdefinitiontothestudyeventsandcasereportformsassociatedwithit.


• public StudyEventDefinitionQueryHelper(StudyEventDefinition studyEventDefinition, OpenClinicaCRFClient client)

o CreatesanewStudyEventDefinitionQueryHelperusingthegivenstudyeventdefinitionasthenavigation

sourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters studyEventDefinition–the

StudyEventDefinitionthatwillserveasthesourceofnavigation

client–theOpenClinicaCRFClientthatisinvokingtheservice

public List<StudyEvent>getStudyEvents()

• Retrievesthestudyeventsbelongingtothegivenstudyeventdefinition

• Parameters:None• Return:AlistofStudyEventobjectsassociatedwiththegiven

StudyEventDefinition• Throws:java.rmi.RemoteExceptionifthereisaproblem


public List<CaseReportForm> getCaseReportForms()

• Retrievesthecasereportformsassociatedwithagivenstudyevent

• Parameters:None• Return:AlistofCaseReportFormobjectsassociatedwiththe

givenStudyEventDefinition• Throws:java.rmi.RemoteExceptionifthereisaproblem


‐ CaseReportFormQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularcasereportformtothestudyeventdefinitionsandcasereportformversionsassociatedwithit.


• public CaseReportFormQueryHelper(CaseReportForm crf, OpenClinicaCRFClient client)

o CreatesanewCaseReportFormQueryHelperusingthegivenCaseReportFormasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters crf–theCaseReportFormthatwillserveasthe


invokingtheservice

public List<StudyEventDefinition> getStudyEventDefinitions()

• Retrievesthestudyeventdefinitionsthatagivencasereportformbelongsto

• Parameters:None• Return:AlistofStudyEventDefinitionobjectsassociated

withthegivenCaseReportForm

• Throws:java.rmi.RemoteExceptionifthereisaproblemcontactingtheservice

public List<CRFVersion> getCRFVersions()

• Retrievestheversioninformationforagivencasereportform• Parameters:None• Return:AlistofCRVersionobjectsassociatedwiththegiven

CaseReportForm• Throws: java.rmi.RemoteExceptionifthereisaproblem


‐ CRFVersionQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularcasereportformversiontothecasereportform,casereportformsections,andstudyeventsassociatedwithit.


• public CRFVersionQueryHelper(CRFVersion version, OpenClinicaCRFClient client)

o CreatesanewCRFVersionQueryHelplerusingthegivenCRFVersionasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters version–theCRFVersionthatwillserveasthe


invokingtheservice

public List<CRFSection> getCRFSections()

• Retrievesthesectioninformationassociatedwithagivencasereportformversion

• Parameters:None• Return:alistofCRFSectionobjectsassociatedwiththegiven

CRFVersion• Throws:java.rmi.RemoteExceptionifthereisaproblem


public CaseReportForm getCaseReportForm()

• Retrievesthecasereportformthatagivenversionbelongsto• Parameters:None• Return:theCaseReportFormassociatedwiththegiven

CRFVersion• Throws:java.rmi.RemoteExceptionifthereisaproblem


public List<StudyEvent> getStudyEvents()

• Retrievesthestudyeventsassociatedwithagivencasereportformversion

• Parameters:None• Return:alistofStudyEventobjectsassociatedwiththegiven

CRFVersion

• Throws:java.rmi.RemoteExceptionifthereisaproblemcontactingtheservice

‐ CRFSectionQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularcasereportformsectiontothecasereportformitemsandcasereportfromversionassociatedwithit.


• public CRFSectionQueryHelper(CRFSection section, OpenClinicaCRFClient client)

o CreatesanewCRFSectionQueryHelperusingthegivenCRFSectionasthesourceofnavigationandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters section–theCRFSectionthatwillserveasthe


invokingtheservice

public List<CRFItem> getCRFItems()

• Retrievestheitemsassociatedwithagivencasereportformsection

• Parameters:None• Return:alistofCRFItemobjectsassociatedwiththegiven

CRFSection• Throws:java.rmi.RemoteExceptionifthereisaproblem


public CRFVersion getCRFVersion()

• Retrievestheversioninformationassociatedwithagivencasereportformsection

• Parameters:None• Return:theCRFVersionassociatedwiththegivenCRFSection• Throws:java.rmi.RemoteExceptionifthereisaproblem


‐ CRFItemQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularcasereportformitemtotheitemdata,itemdatatypeandcasereportformsectionassociatedwithit.


• public CRFItemQueryHelper(CRFItem item, OpenClinicaCRFClient client)

o CreatesanewCRFItemQueryHelperusingthegivenCRFItemasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters item–theCRFItemthatwillserveasthesource

ofnavigation

client–theOpenClinicaCRFClientthatisinvokingtheservice

public CRFItemDataType getCRFItemDataType()

• Retrievesthedatatypeofagivencasereportformitem• Parameters:None• Return:theCRFItemDataTypeassociatedwiththegiven

CRFItem• Throws:java.rmi.RemoteExceptionifthereisaproblem


public List<CRFItemData> getCRFItemDatas

• Retrievesthedatavaluesforagivencasereportformitem• Parameters:None• Return:alistofCRFItemDataobjectsassociatedwiththis



public List<CRFSection> getCRFSections()

• Retrievesthecasereportformsectionswhereagivenitemappears

• Parameters:None• Return:alistofCRFSectionobjectsassociatedwiththegiven



‐ CRFItemDataQueryHelper:FacilitatesnavigationoftheOpenClinicainformationmodelfromaparticularcasereportformitemdatarecordtotheitemassociatedwithit.


• public CRFItemDataQueryHelper(CRFItemData itemData, OpenClinicaCRFClient client)

o CreatesanewCRFItemDataQueryHelperusingthegivenCRFItemDataasthenavigationsourceandthegivenOpenClinicaCRFClientastheclientinvokingtheservice

o Parameters itemData–theCRFItemDatathatwillserveas

thesourceofnavigation client–theOpenClinicaCRFClientthatis

invokingtheservice

public CRFItem getCRFItem()

• RetrievestheCRFitemthatagivendatavaluebelongsto• Parameters:None• Return:theCRFItemassociatedwiththegivenCRFItemData• Throws:java.rmi.RemoteExceptionifthereisaproblem


‐ CRFItemDataTypeQueryHelper:FacilitatesnavigationoftheOpenClinicadatamodelfromaparticularcasereportformitemdatatypetotheitemsassociatedwithit.

o Methods Contstructor

• public CRFItemDataTypeQueryHelper(CRFItemDataType itemDataType, OpenClinicaCRFClient client)

o CreatesanewCRFItemDataTypeQueryHelperusingthegivenCRFItemDataTypeasthenavigationsourceandthegivenOpenClinicaCRFClientastheclienttoinvoketheservice

o Parameters itemDataType–theCRFItemDataTypethatwill

serveasthesourceofnavigation client–theOpenClinicaCRFClientthatis

invokingtheservice

public List<CRFItem> getCRFItems()

• Retrievesthecasereportformitemsthatareofagivendatatype

• Parameters:None• Return:alistofCRFItemobjectsthatareofthegiven

CRFItemDataType• Throws:java.rmi.RemoteExceptionifthereisaproblem

contactingtheservice4.2ExampleQueryInthisexample,theuserwishestoretrieveallsubjectsinthedatabasewhosecasereportformscontainanitemwithacertainname(“LVEDV”).NotethataCQLquerymustbebuiltandsubmittedtoobtaintheinitiallistofCRFItemsthatwillbeiteratedthrough,butthatallnavigationbetweenobjectsinthedatamodelishandledthroughthehelperclasses.CQLQuery query = new CQLQuery(); gov.nih.nci.cagrid.cqlquery.Object target = new gov.nih.nci.cagrid.cqlquery.Object(); target.setName(org.cvrg.domain.CRFItem.class.getName()); Attribute itemNameAttr = new Attribute("name", Predicate.EQUAL_TO, "LVEDV"); target.setAttribute(itemNameAttr); query.setTarget(target); CQLQueryResults results = client.query(query); InputStream istream = OpenClinicaCRFClient.class.getResourceAsStream("client-config.wsdd"); // subjects with the requested CRFItem List<Subject> subjects = new ArrayList<Subject>(); Iterator<CRFItem> itemIter = new CQLQueryResultsIterator(results, istream); while (itemIter.hasNext()) { CRFItem item = itemIter.next(); System.out.println("Item name: " + item.getName()); CRFItemQueryHelper crfiqh = new CRFItemQueryHelper(item, client); List<CRFSection> sections = crfiqh.getCRFSections();

for (CRFSection section : sections) { System.out.println("Section ID: " + section.getId());

CRFSectionQueryHelper crfsqh = new CRFSectionQueryHelper(section, client);

CRFVersion version = crfsqh.getCRFVersion(); System.out.println("Version ID: " + version.getId());

CRFVersionQueryHelper crfvqh = new CRFVersionQueryHelper(version, client);

List<StudyEvent> studyEvents = crfvqh.getStudyEvents(); System.out.println("# Study events: " + studyEvents.size()); for (StudyEvent studyEvent : studyEvents) { System.out.println("StudyEvent ID: " + studyEvent.getId());

StudyEventQueryHelper seqh = new StudyEventQueryHelper(studyEvent, client); System.out.println("\tStudy ID: " + seqh.getStudy().getId()); System.out.println("\tSubject ID: " + seqh.getSubject().getId());

} } }

how to build and deploy openclinicacrf data service...

Documents