Cancer Trials Support Unit...1.0 08/26/2013 Phoebe Whitefield Initial Version 1.1 08/29/2013 Mark Stauffer Updated the MS Word styles, added figure 1. 1.2 08/30/2013 Kasi Perumal Review

CTSU Cancer Trials Support Unit

March 13, 2014

OPEN-Enrollment Loading Web

Service Specification Revision 1.9

OPEN-Enrollment Loading Web Service Specification Revision 1.9 March 13, 2014 Page ii

Document Information

Revision Information for the OPEN-Enrollment Loading Web Service Specification

Revision History

# Date By Description

1.0 08/26/2013 Phoebe Whitefield Initial Version

1.1 08/29/2013 Mark Stauffer Updated the MS Word styles, added figure 1.

1.2 08/30/2013 Kasi Perumal Review and updated WS content and XSD

1.3 11/11/2013 Smita Pande Updated version to support future updates

1.4 11/13/2013 Kasi Perumal Updated XSDs and reviewed content

1.5 11/15/2013 Jayan Nair Reviewed and updated the document

1.6 01/08/2014 Kasi Perumal Updated the CDEs for the registration object

1.7 01/22/2014 Kasi Perumal/Max Lin Updated the request and response as per the framework Added .NET client

1.8 01/24/2014 Siva Katta Tested the .NET client and reviewed the instructions

1.9 03/13/2014 Kasi Perumal Addition of the CEWS error codes

Last Saved By Kasi Perumal on 3/13/2014 2:51:00 PM

File Location: \\westat.com\DFS\CTSU6181\TO2\6181.06_OPEN\03_Elaboration\LegacyWebService\CTSU-OPEN-EnrollmentLoadSpecification.docx

This document was prepared by:

WESTAT, Cancer Trials Support Unit 1600 Research Boulevard Rockville, Maryland 20850

OPEN-Enrollment Loading Web Service Specification Revision 1.9 March 13, 2014 Page iii

Table of Contents 1. REFERENCES .................................................................................................................... 1

2. INTRODUCTION ............................................................................................................... 2

2.1 BACKGROUND ........................................................................................................................ 2 2.2 SCOPE .................................................................................................................................. 2 2.3 TARGET AUDIENCE .................................................................................................................. 2 2.4 ASSUMPTIONS ........................................................................................................................ 2 2.5 ACRONYMS ............................................................................................................................ 2

3. IMPLEMENTATION .......................................................................................................... 4

3.1 OVERVIEW............................................................................................................................. 4 3.2 OPEN ENROLLMENT DATA POINTS ............................................................................................ 5

3.2.1 Registration ............................................................................................................................. 5 3.2.2 Demography ............................................................................................................................ 9

4. CEWS WEB SERVICE ....................................................................................................... 13

4.1 CEWS OVERVIEW ................................................................................................................ 13 4.2 OPEN DATA UPDATE SERVICE ................................................................................................ 13 4.3 CEWS REQUEST INPUT PARAMETER: ....................................................................................... 13

4.3.1 CEWS Request XML Structure ............................................................................................... 13 4.3.2 Example of the LOAD_ENROLLMENT Request XML .............................................................. 15 4.3.3 Example of the RELOAD_ENROLLMENT Request XML .......................................................... 16

4.4 CEWS RESPONSE OUTPUT PARAMETER .................................................................................... 18 4.4.1 Example of the Load/Reload Response XML......................................................................... 21 4.4.2 Example of Failure Response XML ........................................................................................ 21 4.4.3 CEWS Fault ............................................................................................................................ 22

4.5 CEWS VALIDATIONS AND ERROR CODES ................................................................................... 22 4.5.1 Registration Validations ........................................................................................................ 22 4.5.2 Demography Validations ....................................................................................................... 23 4.5.3 Error Codes ............................................................................................................................ 23

4.6 URL ................................................................................................................................... 24

5. CEWS CLIENT ................................................................................................................. 25

5.1 .NET CLIENT ........................................................................................................................ 25 5.2 IMPLEMENTATION ................................................................................................................. 25

5.2.1 Add Service Reference .......................................................................................................... 25 5.2.2 Include and Reference SecurityHeader.cs file ...................................................................... 26

5.2.2.1 SoapSecurityHeader class .............................................................................................. 26 5.2.2.2 ClientMessageInspector class ........................................................................................ 27 5.2.2.3 CustomEndPointBehavior class ..................................................................................... 27

5.2.3 Implement Service Consumption Code ................................................................................. 27

OPEN-Enrollment Loading Web Service Specification Revision 1.9 March 13, 2014 Page iv

5.2.3.1 Create an instance of OpenDataServiceClient ............................................................... 27 5.2.3.2 Add a custom endpoint behavior to the client .............................................................. 28 5.2.3.3 Switch endpoint address ................................................................................................ 28 5.2.3.4 Create an instance of the Request object ...................................................................... 28 5.2.3.5 Passing Request object to the service and receiving Response .................................... 28 5.2.3.6 Handle the Response accordingly .................................................................................. 28

OPEN-Enrollment Loading Web Service Specification Revision 1.9 March 13, 2014 Page v

List of Figures FIGURE 1: PROPOSED ENROLLMENT LOADING WORKFLOW .......................................................................... 4 FIGURE 2: ENROLLMENT OBJECT ............................................................................................................. 5 FIGURE 3: REGISTRATION DATA POINTS ................................................................................................... 6 FIGURE 4: DEMOGRAPHY DATA POINTS ................................................................................................... 9 FIGURE 5: CEWS OPENDATASERVICE ................................................................................................... 13 FIGURE 6: LOAD ENROLLMENT REQUEST FORMAT .................................................................................... 14 FIGURE 7: REQUEST MESSAGE STRUCTURE WITH EXAMPLE DATA ................................................................ 16 FIGURE 8: RELOAD_ENROLLMENT REQUEST MESSAGE STRUCTURE ....................................................... 18 FIGURE 9: LOAD ENROLLMENT RESPONSE MESSAGE ................................................................................. 19 FIGURE 10: CEWS REQUEST/RESPONSE ENUMERATIONS ......................................................................... 20 FIGURE 11: OPEN LOAD/RELOAD ENROLLMENT SUCCESS RESPONSE WITH SAMPLE DATA ............................... 21 FIGURE 12: LOAD OPEN ENROLLMENT FAILURE RESPONSE WITH SAMPLE DATA ............................................ 22 FIGURE 13: LOAD OPEN ENROLLMENT FAILURE RESPONSE WITH SAMPLE DATA ............................................ 22 FIGURE 14: CEWS SERVICE REFERENCE ................................................................................................. 25 FIGURE 15: SERVICE REFERENCE ADDITION DIALOG ................................................................................... 26 FIGURE 16: SERVICE REFERENCE AFTER ADDITION ..................................................................................... 26

References

OPEN-Enrollment Loading Web Service Specification Rev. 1.9 Page 1 of 29

1. References Table 1: References

# Name Location (Intranet) Location (Internet)

1 CEWS https://www.ctsu.org/cews/

2 .NET Client https://www.ctsu.org/cews/default.asp?fName=cews/OPENDataUpdate/

3 Java Client

https://www.ctsu.org/cews/

https://www.ctsu.org/cews/default.asp?fNa

Introduction


2. Introduction 2.1 Background OPEN (Oncology Patient Enrollment Network) is a patient enrollment system used for enrolling patients to NCI funded clinical trials. During the enrollment process, OPEN collects enrollment data such as patient demographics, patient eligibility information and enrollment credentialing information such as the enrollment site, treating physician etc. This patient information is carried over to the next study step for multi-step studies.

Beginning March 2014, NCI requires all LPOs (Lead Protocol Organizations) to use OPEN for all CTEP studies for patient enrollment. Due to some study specific requirements, the NCI has given exceptions to certain studies to remain in the LPO system after March 2014 as long as the LPO is able to push the enrollment data to OPEN for meeting the NCI reporting needs.

To meet this requirement, the OPEN team has developed a CEWS (CTSU Enterprise Web Service) method to enable the LPOs to load the enrollment data in near real-time after the enrollment is completed. This service will load the enrollment data received from the LPO system to OPEN.

2.2 Scope The scope of this document is to provide details about the technical interface for sending the patient enrollment information to OPEN from the study lead group.

2.3 Target Audience This document is being developed for the LPO and the CTSU IT teams.

2.4 Assumptions • It is assumed that this web service will only collect the Registration and Demography details of the

enrollment.

• Eligibility checklist forms are not collected.

• The initial version of the web service will only accept initial step accruals. Subsequent step loads will need to be coordinated with CTSU.

• This web service will support loading of any number of patient enrollments in an iterative loop by loading one patient enrollment record at a time. This granular approach is designed to support real-time as well as batch processes for loading the patient enrollment data.

• The client system should have the ability to store the tracking number which is sent in the response when the patient enrollment is loaded in OPEN for the initial step. This tracking number will be used to uniquely identify the enrollment data when the user wants to update the enrollment.

2.5 Acronyms The following acronyms will be used in this document

Introduction


Table 2: Acronyms

Acronym Description

OPEN Oncology Patient Enrollment Network

CEWS CTSU’s suite of web services is called CTSU Enterprise Web Services

CTEP Cancer Therapy Evaluation Program

CTSU The Cancer Trials Support Unit (CTSU) supports national network of physicians to participate in NCI-sponsored cancer treatment trials, cancer prevention and control trials, and correlative science studies.

RSS The Regulatory Support System (RSS) is an application created within the CTSU Enterprise system to create and manage institution, person, and regulatory data for CTEP-supported Cooperative Groups, contractors, and grantees. It is also used to manage CTSU-specific enrollment and delinquency tracking data.

Implementation


3. Implementation 3.1 Overview A new web service as part of the CEWS will be added to handle the patient enrollment data. This section identifies the OPEN enrollment load data points, web service method name, the web service message structure that transfers the enrollment data and the web service response message structure.

Figure 1: Proposed Enrollment Loading Workflow

Implementation


3.2 OPEN Enrollment Data Points The OPEN load enrollment service is grouped into two data point objects as show below:

Figure 2: Enrollment Object

3.2.1 Registration This Registration object has the enrollment credential and the randomization result. Table 3 describes the data points.

Implementation


Figure 3: Registration Data Points

Implementation


Table 3: Registration Data Points

XML Tag CDE Public ID Description Data Type Size Reqd? Example

trackingNumber 3302859_V1_0 The enrollment tracking number that was generated by OPEN NUMBER 10 No* Required for RELOAD else optional for LOAD

protocolNumber 2003300_V4_0 The study/protocol number against which the enrollment is created.

CHARACTER 35 Yes ANBL00B1

step 2002093_V4_0 Registration Step. CHARACTER 5 Yes 1

patientId 2003301_V4_0 The patient identifier assigned by the group. Capable of holding alpha numeric characters if desired.

CHARACTER 20 Yes 859123

regSiteCtepId 3314243_V1_0 Registering institution's CTEP identifier. CHARACTER 24 Yes MN008

treatingInvCtepId 2740424_V1_0 Treating Investigator’s CTEP identifier. NUMBER 10 Yes 12585 *

creditingInvCtepId 2002224_V4_0 Crediting Investigator's CTEP identifier.

NUMBER 10 Yes 12585 *

creditRecipient 2152_V3_0 The group which gets the credit for this enrollment. CHARACTER 7 Yes COG

randomizedDate 2746541_V1_0 Date Time of enrollment. Uses XML DateTime data type. The format is YYYY-MM-DDThh:mm:ss

• YYYY indicates the year

• MM indicates the month • DD indicates the day • T indicates the start of the required time section • hh indicates the hour • mm indicates the minute • ss indicates the second

The timestamp is optional.

DATE Yes 2013-12-10T19:58:01 OR 2007-11-27

Implementation


XML Tag CDE Public ID Description Data Type Size Reqd? Example

treatmentAssignment 2001626_V3_0 Treatment Arm. CHARACTER 25 Yes A

registrarCtepId PID2172_V3_0 Registrar's CTEP identifier. The person who completed the enrollment.

NUMBER 10 Yes 527631 Should have an IAM account

prevStepTrackingNumber 3302859_V1_0 The enrollment tracking number that was generated by OPEN for the previous step in case it needs to be linked in OPEN

NUMBER 10 No* Required for subsequent steps

otherValues N/A Placeholder tag for future use if required CHARACTER 4000 No

* NOTE: Treating Investigator can be same as Crediting Investigator.

Implementation


3.2.2 Demography The Demography object has the patient’s demographic data. Table 4 describes the data points. OPEN standard forms use caDSR approved CDEs.

Figure 4: Demography Data Points

Implementation


Table 4: Demography Data Points

XML Tag Description CDE Public

ID CDE

Version CDE Valid Values Data Type Size Required? Example

lastInitial 2658183 1.0 CHARACTER 1 NO A

firstInitial 2658182 1.0 CHARACTER 1 NO M

middleInitial 2658163 1.0 CHARACTER 1 NO A

patientDateOfBirth Date of Birth. The format is YYYY-MM-DD

793 4.0 DATE YES 1990-12-01

ethnicity Ethnicity 2192217 2.0 • Hispanic or Latino

• Not Hispanic or Latino • Not Reported

• Unknown

CHARACTER 22 YES Hispanic or Latino

gender Gender 2200604 2.0 • Female Gender

• Male Gender • Unknown

CHARACTER 13 YES Female Gender

countryOfResidence Country of Residence

315 3.0 Note: there are 247 country codes as per the CDE permissible values

CHARACTER 5 YES US

zipCode Zip Code 2179606 2.0 CHARACTER 15 YES 06415

Implementation



ID CDE


raceList Race 2192199 1.0 • American Indian or Alaska Native

• Asian • Black or African American • Native Hawaiian or other Pacific

Islander • White • Not Reported

• Unknown

CHARACTER 41 YES Asian

methodOfPaymentList

Method of payment

2003309 3.0 • PRIVATE INSURANCE

• MEDICARE • MEDICARE AND PRIVATE

INSURANCE

• MEDICAID • MEDICAID AND MEDICARE • MILITARY OR VETERANS

SPONSORED NOS

• MILITARY SPONSORED (INCLUDING CHAMPUS &TRICARE)

• VETERANS SPONSORED • SELF PAY (NO INSURANCE) • NO MEANS OF PAYMENT (NO

INSURANCE) • OTHER • Unknown

CHARACTER 50 YES PRIVATE INSURANCE

Note: Method of payment is mandatory field, if it is not known send it as ‘Unknown’

Implementation



ID CDE


otherValues Placeholder tag for future use if required

N/A CHARACTER 4000 NO

CEWS WEB SERVICE


4. CEWS WEB SERVICE 4.1 CEWS Overview CTSU Enterprise Web Services (CEWS) is a suite of web services to support various regulatory and patient data integrations between the CTSU systems and the LPO and other systems which are integrated with CTSU Enterprise systems. CEWS consists of a number of general purpose web service and few business process specific web services.

4.2 OPEN Data Update Service The CEWS system supports a set of web service methods called OPEN Data Update Web Services to support OPEN functionalities. These Web Service methods support inserting and updating of the LPO specific Data in OPEN. This was primarily developed to support OPEN’s Group lookup feature to be updated with data sent by the LPOs via a web service.

A new operation “loadOpenEnrollment” will be added to the existing OpenDataUpdate WSDL.

Figure 5: CEWS OpenDataService

The LPOs consuming this service should construct a CEWS Request XML to communicate with CEWS. CEWS would synchronously respond with a Response XML regarding the status of the request.

Based on the specification described in this document, a new web service method namely, loadOpenEnrollment will be developed for loading the patient enrollment data to OPEN. To load the data into OPEN, you can set the request type as LOAD_ENROLLMENT. The web service will respond based on the loading result. If the loading is successful, the web service will return the tracking number. This tracking number will be used to identify the enrollment when the user wants to update the enrollment data in future. Data can be updated later by sending the request type as RELOAD_ENROLLMENT. When the user wants to change any field for a particular enrollment, the complete enrollment information must be sent. This web service accepts a single enrollment data at a time as illustrated below. Please refer to the assumptions in section 2.4 for more information.

4.3 CEWS Request Input Parameter: 4.3.1 CEWS Request XML Structure The structure of the CEWS Request XML is depicted below. CEWS request message has message header and message payload.

CEWS WEB SERVICE


Figure 6: Load Enrollment Request Format

More explanation of the specific nodes in the input XML is given in the table below.

Table 5: Request Message Header Elements

Tag Data Type Size Description Comments

requestBy CHARACTER 30 The external application that is requesting the load.

Ex: COG

requestType CHARACTER 30 String that describes the type of the request

Ex: LOAD_ENROLLMENT RELOAD_ENROLLMENT

requestId CHARACTER 30 Unique identifier to track a request

This REQUEST_ID will be empty for the request from LPO to. CTSU. CTSU returns a REQUEST_ID when generating a response xml.

groupRequestId CHARACTER 30 Group Id to track the group whose action resulted in loading patient data to OPEN.

Group ID to track a request. It is an optional data element.

CEWS WEB SERVICE


4.3.2 Example of the LOAD_ENROLLMENT Request XML Figure 7 shows the CEWS XML request specification for loading enrollment data into OPEN.

<soapenv:Envelope xmlns:open="http://opendata.cews.ctsu.westat.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"> <wsse:UsernameToken wsu:Id="UsernameToken-2"> <wsse:Username>ECOG</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">passwordText</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soapenv:Header> <soapenv:Body> <open:loadOpenEnrollmentRequest>  <cewsRequest>  <messageHeader>  <requestId></requestId>   <groupRequestId></groupRequestId>  <requestType>LOAD_ENROLLMENT</requestType>  <requestBy>ECOG</requestBy> </messageHeader> <messagePayload> <enrollment> <registration>   <trackingNumber>0</trackingNumber>  <protocolNumber>S1115</protocolNumber>  <step>1</step>  <patientId>PID-12345</patientId>  <regSiteCtepId>MN008</regSiteCtepId>  <treatingInvCtepId>11134</treatingInvCtepId>  <creditingInvCtepId>11134</creditingInvCtepId>  <creditRecipient>ECOG</creditRecipient>  <randomizedDate>2013-12-10T19:58:01</randomizedDate>  <treatmentAssignment>X</treatmentAssignment>  <registrarCtepId>508681</registrarCtepId>   <prevStepTrackingNumber>0</prevStepTrackingNumber> 

http://opendata.cews.ctsu.westat.com

http://schemas.xmlsoap.org/soap/envelope/

http://docs.oasis-

http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-

http://docs.oasis-open.org/wss/2004/01/oasis-200401-

CEWS WEB SERVICE


 <otherValues></otherValues> </registration> <demography>  <lastInitial>J</lastInitial>  <firstInitial>K</firstInitial>  <middleInitial>L</middleInitial>  <patientDateOfBirth>2000-09-14</patientDateOfBirth>  <ethnicity>Not Hispanic or Latino</ethnicity>  <gender>Female Gender</gender>  <countryOfResidence>US</countryOfResidence>  <zipCode>12345</zipCode> <raceList>   <race>Asian</race> <race>White</race> </raceList> <methodOfPaymentList>   <methodOfPayment>PRIVATE INSURANCE</methodOfPayment> </methodOfPaymentList>   <otherValues></otherValues> </demography> </enrollment> </messagePayload> </cewsRequest> </open:loadOpenEnrollmentRequest> </soapenv:Body> </soapenv:Envelope>

Figure 7: Request Message Structure with Example Data

4.3.3 Example of the RELOAD_ENROLLMENT Request XML The Reload request updates all the data points received in the request. Even if only one data point needs to be updated, all the data points should be submitted again as part of the reload process. The previously issued tracking number should be provided which uniquely identifies the enrollment within OPEN.

Figure 8 shows the CEWS XML request specification for updating enrollment data into OPEN.

<soapenv:Envelope xmlns:open="http://opendata.cews.ctsu.westat.com" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Header> <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">



http://docs.oasis-


CEWS WEB SERVICE


<wsse:UsernameToken wsu:Id="UsernameToken-2"> <wsse:Username>ECOG</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">passworText</wsse:Password> </wsse:UsernameToken> </wsse:Security> </soapenv:Header> <soapenv:Body> <open:loadOpenEnrollmentRequest>  <cewsRequest>  <messageHeader>  <requestId></requestId>   <groupRequestId></groupRequestId>  <requestType>RELOAD_ENROLLMENT</requestType>  <requestBy>ECOG</requestBy> </messageHeader> <messagePayload> <enrollment> <registration>   <trackingNumber>167187</trackingNumber>  <protocolNumber>S1115</protocolNumber>  <step>1</step>  <patientId>PID-123456</patientId>  <regSiteCtepId>MN008</regSiteCtepId>  <treatingInvCtepId>11134</treatingInvCtepId>  <creditingInvCtepId>11134</creditingInvCtepId>  <creditRecipient>ECOG</creditRecipient>  <randomizedDate>2013-12-10T19:58:01</randomizedDate>  <treatmentAssignment>X</treatmentAssignment>  <registrarCtepId>508681</registrarCtepId>   <prevStepTrackingNumber>0</prevStepTrackingNumber>   <otherValues></otherValues> </registration> <demography>  <lastInitial>J</lastInitial>  <firstInitial>K</firstInitial>  <middleInitial>L</middleInitial>  <patientDateOfBirth>2000-09-14</patientDateOfBirth>


CEWS WEB SERVICE


 <ethnicity>Not Hispanic or Latino</ethnicity>  <gender>Male Gender</gender>  <countryOfResidence>US</countryOfResidence>  <zipCode>12345</zipCode> <raceList>   <race>Asian</race> <race>White</race> </raceList> <methodOfPaymentList>   <methodOfPayment>PRIVATE INSURANCE</methodOfPayment> </methodOfPaymentList>   <otherValues></otherValues> </demography> </enrollment> </messagePayload> </cewsRequest> </open:loadOpenEnrollmentRequest> </soapenv:Body> </soapenv:Envelope>

Figure 8: RELOAD_ENROLLMENT Request Message Structure

4.4 CEWS Response Output Parameter The structure of the CEWS Response XML is depicted below. CEWS response message has message header and message payload similar to the request XML.

CEWS WEB SERVICE


Figure 9: Load Enrollment Response Message

Note: CEWS generates response synchronously with request ID for tracking the request in future.

CEWS response will send a tracking number as the enrollment confirmation. The client should have the ability to store this tracking number. This tracking number will be used to uniquely identify the specific record when the caller wants to update the patient enrollment data later.

The Response status, response status text and tracking number values are shown in Table 8. Exception codes will be derived and added as needed.

CEWS WEB SERVICE


Table 6: Response Message Header Elements

Tag Data Type Size Description Comments

requestBy CHARACTER 30 The external application that is requesting the load.

Ex: COG

requestType CHARACTER 30 String that describes the type of the request

Ex: LOAD_ENROLLMENT RELOAD_ENROLLMENT

requestId CHARACTER 30 Unique identifier to track a request

This REQUEST_ID will be empty for the request from LPO to. CTSU. CTSU returns a request ID when generating a response xml.

groupRequestId CHARACTER 30 Group Id to track the group whose action resulted in loading patient data to OPEN.

Group ID to track a request. It is an optional data element.

responseBy CHARACTER 30 String that describes who has sent the response

Value will be CTSU

responseDate DATE When the response was sent

XML DateTime Format 2014-01-21T18:54:53.735-05:00

requestStatus CHARACTER 30 GOOD/BAD/WARN Indicates the request result

requestStatusText CHARACTER 500 It will have the corresponding message.

Figure 10: CEWS Request/Response Enumerations

Table 7: CEWS Request Status Details

Request Request Status Request Status Text

Success GOOD Empty or NULL

Failure BAD Details of Exception

Warning WARN Indicates the request result

CEWS WEB SERVICE


Table 8: CEWS Message Payload Response Status Details

Operation Response Status Response Status Text

Success SUCCESS Status for the request

Failure FAILURE Details of Exception

4.4.1 Example of the Load/Reload Response XML Figure 11 depicts the message response XML structure for successful patient loading/reloading to OPEN. This message indicates that all patients are loaded to OPEN without error. The response structure would be the same for both load and reloads except that the request type and status text wordings might differ.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns2:loadOpenEnrollmentResponse xmlns:ns2="http://opendata.cews.ctsu.westat.com"> <loadOpenEnrollmentResponse> <messageHeader> <requestId>RQT-95423906</requestId> <groupRequestId/> <requestType>LOAD_ENROLLMENT</requestType> <requestBy>ECOG</requestBy> <responseDate>2014-01-22T21:27:08.684-05:00</responseDate> <responseBy>OPEN</responseBy> <requestStatus>GOOD</requestStatus> <requestStatusText/> </messageHeader> <messagePayload> <responseStatus>SUCCESS</responseStatus> <responseStatusText>Patient PID-12345 loaded into OPEN</responseStatusText> <trackingNumber>167187</trackingNumber> </messagePayload> </loadOpenEnrollmentResponse> </ns2:loadOpenEnrollmentResponse> </soap:Body> </soap:Envelope>

Figure 11: OPEN Load/Reload Enrollment Success Response with sample data

4.4.2 Example of Failure Response XML Figure 12 illustrates the message response structure for the enrollment that failed loading to OPEN.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <ns2:loadOpenEnrollmentResponse xmlns:ns2="http://opendata.cews.ctsu.westat.com"> <loadOpenEnrollmentResponse> <messageHeader> <requestId>RQT-95424037</requestId> <groupRequestId/> <requestType>LOAD_ENROLLMENT</requestType> <requestBy>ECOG</requestBy> <responseDate>2014-01-22T21:41:54.953-05:00</responseDate> <responseBy>OPEN</responseBy>





CEWS WEB SERVICE


<requestStatus>BAD</requestStatus> <requestStatusText/> </messageHeader> <messagePayload> <responseStatus>FAILURE</responseStatus> <responseStatusText>CEWS-00005:Duplicate enrollment found</responseStatusText> <trackingNumber>0</trackingNumber> </messagePayload> </loadOpenEnrollmentResponse> </ns2:loadOpenEnrollmentResponse> </soap:Body> </soap:Envelope>

Figure 12: Load OPEN Enrollment Failure Response with sample data

4.4.3 CEWS Fault Figure 12 illustrates the message response structure for the CEWS fault that will be thrown for the following cases:

• CEWS-00001 – Authentication Failure

• CEWS-00002 – Authorization Failure

• CEWS-00008 – Credentials/Request Mismatch

• CEWS-00011 – Missing CTSU Configurations

• CEWS-00015 – Operation Not in Service

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <soap:Body> <soap:Fault> <faultcode xmlns:ns1="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">ns1:FailedAuthentication</faultcode> <faultstring>The security token could not be authenticated or authorized; nested exception is: CewsFault [code=CEWS-00011, message=Application XML is missing the CEWS authentication configuration]</faultstring> </soap:Fault> </soap:Body> </soap:Envelope>

Figure 13: Load OPEN Enrollment Failure Response with sample data

4.5 CEWS Validations and Error Codes CEWS incoming requests are validated against the domain specifications as well as against RSS/OPEN for data validations.

4.5.1 Registration Validations CEWS-00005 – Registration data validation failed will be raised for the following conditions and the corresponding field name will be displayed to indicate the same.

• Missing Registration object’s required fields



CEWS WEB SERVICE


o For additional information refer to Table 3: Registration Data Points

• Verification of Study/Site/Person CTEP IDs in RSS

• Verification of Registrar’s IAM account in RSS. The registrar will be logged as the [user] in OPEN.

• Verification of RSS site registration existence for study/site combination

• Invalid credit recipient

• Invalid previous step tracking number

• Invalid [tracking number] (for reloads)

• Duplicate enrollment check

4.5.2 Demography Validations CEWS-00005 – Demography data validation failed will be raised for the following conditions and the corresponding field name will be displayed to indicate the same.

• Missing Demography object’s required fields

o For additional information refer to Table 4: Demography Data Points

• Permissible values as per the OPEN Demography Form

o For additional information refer to Table 4: Demography Data Points

• Verification of Race and Payment list against the maximum allowed

• No OPEN form setup exists

4.5.3 Error Codes The table below lists out all the error codes supported for this Load Enrollment Service.

Table 9: CEWS Error Codes

Code Message Description

CEWS-00000 SUCCESSFUL Patient 1234 loaded/reloaded into OPEN

CEWS-00001 Authentication Failure Refer to CEWS Fault

CEWS-00002 Authorization Failure Refer to CEWS Fault

CEWS-00005 Data validation failed Refer to Section 4.5.1 and Section 4.5.2

CEWS-00008 Group name and credentials are not matching Refer to CEWS Fault

CEWS-00009 Invalid CEWS Request Type • LOAD_ENROLLMENT

• RELOAD_ENROLLMENT

CEWS-00010 Database Exception • Unable to parse request XML

• Other unhandled DB errors

CEWS-00011 Missing CTSU Configuration Refer to CEWS Fault

CEWS-00015 Operation not in service Operation has not yet been implemented

CEWS-99999 Generic Exception • Other unhandled WS errors

CEWS WEB SERVICE


4.6 URL

Table 10: CEWS and its corresponding OPEN URLs

Environment CEWS OPEN

TEST https://test-cews.ctsu.org/cews/services/OpenDataService?wsdl https://test-open.ctsu.org/

UAT https://uat-cews.ctsu.org/cews/services/OpenDataService?wsdl https://uat-open.ctsu.org/

PROD https://cews.ctsu.org/cews/services/OpenDataService?wsdl https://open.ctsu.org/

Username: (Will be provided in a separate email)

Password: (Will be provided in a separate email)

https://test-cews.ctsu.org/cews/services/OpenDataService?wsdl

https://test-open.ctsu.org/

https://uat-cews.ctsu.org/cews/services/OpenDataService?wsdl

https://uat-open.ctsu.org/

https://cews.ctsu.org/cews/services/OpenDataService?wsdl

https://open.ctsu.org/

CEWS Client


5. CEWS Client 5.1 .NET Client CEWS Client Demo is a sample application developed in Visual Studio 2010 which demonstrates how the CEWS OpenDataService can be consumed in .NET environment. Refer to the References section for the location of the starter kit.

5.2 Implementation The following steps describe the general process involved in consuming CEWS OpenDataService with WCF (Windows Communication Foundation), as demonstrated in the application; Assuming the demo application, or an existing client application, has already been open in Visual Studio.

5.2.1 Add Service Reference The first step of consuming the web service with WCF is to add a service reference. This can be done by right clicking the Service Reference node of the project in the solution explorer:

Figure 14: CEWS Service Reference

In the Add Service Reference dialog, enter the WSDL location and press Go button, and then click OK.

CEWS Client


Figure 15: Service reference addition dialog

The Service Reference CEWSService (renamed from ServiceReference1) added as shown in the demo application.

Figure 16: Service reference after addition

5.2.2 Include and Reference SecurityHeader.cs file The SecurityHeader.cs helper file (The file is with the starter kit, refer the References section for details) contains 3 classes that can be used to attach WSSE Security Header to the Request:

5.2.2.1 SoapSecurityHeader class This class contains serialization instruction which produce the following security header in XML.

CEWS Client


<wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">

<wsse:UsernameToken wsu:Id="UsernameToken-2">

<wsse:Username>ECOG</wsse:Username> <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">passwordText</wsse:Password> </wsse:UsernameToken> </wsse:Security>

It accepts username and password at runtime and gets added to the request header, by the ClientMessageInspector class which is described next. Enter the username and password as supplied.

5.2.2.2 ClientMessageInspector class This class implements IClientMessageInspector.BeforeSendRequest method which will be called just before the request is sent. This is where the SoapSecurityHeader is created and attached to the request.

public object BeforeSendRequest(ref Message request, IClientChannel channel) { SoapSecurityHeader header = new SoapSecurityHeader(_username,_password); request.Headers.Add(header); return header.Id; }

5.2.2.3 CustomEndPointBehavior class This classes implements IEndpiontBehavior.ApplyClientBehavior method which adds a ClientMessageInspector as the MessageInspector of the runtime client.

public void ApplyClientBehavior(ServiceEndpoint endpoint, ClientRuntime clientRuntime) { clientRuntime.MessageInspectors.Add(new ClientMessageInspector(_username,_password)); }

5.2.3 Implement Service Consumption Code After the Service Reference added and helper file included, the following steps describes how to implement the code that consume the service. The sample code resides in the button click event of the Windows form included with the source files.

5.2.3.1 Create an instance of OpenDataServiceClient The OpenDataServiceClient should be generated automatically when the Service Reference was added. Create an instance of the class as below:

OpenDataServiceClient client = new OpenDataServiceClient();

http://docs.oasis-



CEWS Client


5.2.3.2 Add a custom endpoint behavior to the client Add an instance of CustomEndpointBehavior as the endpoint behavior of the client. This will allow username and password to be passed through the behavior, then through the message inspector, and finally attached to SOAP message as security header.

client.Endpoint.Behaviors.Add(new CustomEndpointBehavior(tbUID.Text, tbPWD.Text));

5.2.3.3 Switch endpoint address The endpoint address can be switch at runtime. This will allow the application to consume Testing, UAT or Production service. Please refer to section 4.5 for all the service endpoints available.

client.Endpoint.Address = new System.ServiceModel.EndpointAddress(cbEndPoint.Text);

5.2.3.4 Create an instance of the Request object The loadEnrollmentRequest class should be generated automatically when the Service Reference was added. Create an instance of the class and populate it with the values representing the data to be loaded into OPEN. Refer to section 4.3 for specification details.

loadEnrollmentRequest req = new loadEnrollmentRequest(); req.messagePayload = new patientEnrollment(); enrollment en = new enrollment(); req.messagePayload.enrollment = en; demography dg = new demography(); en.demography = dg; dg.countryOfResidence = "US"; dg.ethnicity = "Not Hispanic or Latino"; dg.firstInitial = "B"; …

5.2.3.5 Passing Request object to the service and receiving Response After the loadEnrollmentRequest object is populated, passing the object to the loadOpenEnrollment service exposed by the client. The service will return an instance of loadEnrollmentResponse class which contains the result and status of the service execution.

loadEnrollmentResponse rsp = client.loadOpenEnrollment(req);

5.2.3.6 Handle the Response accordingly See section 4.4 of this document for Response detail. The follow code demonstrates how the Response attributes can be read.

tbStatus.Text = rsp.messagePayload.responseStatus.ToString(); tbStatusText.Text = rsp.messagePayload.responseStatusText; tbTrackingNo.Text = rsp.messagePayload.trackingNumber.ToString();

Documents

Cancer Trials Support Unit...1.0 08/26/2013 Phoebe Whitefield Initial Version 1.1 08/29/2013 Mark Stauffer Updated the MS Word styles, added figure 1. 1.2 08/30/2013 Kasi Perumal Review