This service provides API methods for manipulating subjects in OpenClinica. The WSDL file associated with this service can be found here: http://${your instance}/OpenClinica-ws/ws/studySubject/v1/studySubjectWsdl.wsdl.

2.2.1 create (Creates a new studySubject)

Create Method generates a new Study Subject.

Usage

Creates a study subjects in a target study/site. Required and optional fields will be determined by the configuration of the study and site the subject is being created in.

SOAP XML Request and Response Template

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:v1="http://openclinica.org/ws/studySubject/v1"
xmlns:bean="http://openclinica.org/ws/beans">
${insert header}
<soapenv:Body>
<v1:createRequest>
<!--1 or more repetitions:-->
<v1:studySubject>
<bean:label>?</bean:label>
<!--Optional:-->
<bean:secondaryLabel>?</bean:secondaryLabel>
<bean:enrollmentDate>?</bean:enrollmentDate>
<bean:subject>
<!--Optional:-->
<bean:uniqueIdentifier>?</bean:uniqueIdentifier>
<!--Optional:-->
<bean:gender>?</bean:gender>
<!--You have a CHOICE of the next 2 items at this level-->
<bean:dateOfBirth>?</bean:dateOfBirth>
<bean:yearOfBirth>?</bean:yearOfBirth>
</bean:subject>
<bean:studyRef>
<bean:identifier>?</bean:identifier>
<!--Optional:-->
<bean:siteRef>
<bean:identifier>?</bean:identifier>
</bean:siteRef>
</bean:studyRef>
</v1:studySubject>
</v1:createRequest>
</soapenv:Body>
</soapenv:Envelope>


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<createResponse>
<result>success</result>
<label>?</label>
</createResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Parameters

Request Parameters

 
ParameterUIDomainDBValidationsDatatypesExamplesRequired
labelStudy Subject IDStudySubjectBean:labelstudy_subject:label– cannot be longer than 30 charactersString

<label>SSID001</label>

 

Note: The OID of the study subject is truncated if the label contains 9 or more characters. For example, if you create a subject with a Study Subject ID # ALC5000001 –> the Study Subject OID saved in the database is: SS_ALC50000 instead of SS_ALC5000001

If there is another study subject containing the same first 8 characters as the first study subject,the second study subject will have the same OID as the first study subject with an appended 4 randomly assigned digits to ensure uniqueness. For example, if after you submitted a request to create a Study subject of  ALC5000001, you submit a request to create a  Study Subject ID # ALC5000002, the Study Subject OID saved in the database is: SS_ALC50000_5363 instead of SS_ALC5000002

 

Y – if “Study Parameter Configuration – Generate the Study Subject ID” is set to Manual Entry.

N – if “Study Parameter Configuration – Generate the Study Subject ID” is set to Auto-generated and Editable or Auto-generated and Non-editable.

secondaryLabelSecondary IDStudySubjectBean:secondaryLabelstudy_subject:secondary_label– cannot be longer than 30 charactersString<secondaryLabel>?</secondaryLabel>N
enrollmentDateDate of EnrollmentStudySubjectBean:enrollmentDatestudy_subject:enrollment_date

– should be a valid date in the ISO 8601 format

– date should be in the past

Date<enrollmentDate>2008-12-12</enrollmentDate>Y
subject:uniqueIdentifierPerson IDSubjectBean:uniqueIdentifiersubject:unique_identifier– cannot be longer than 255 charactersString <uniqueIdentifier>PID001</uniqueIdentifier>

Y – if “Study Parameter Configuration – Person ID Required” is set to Required.

N – if “Study Parameter Configuration – Person ID Required” is set to Optional or Not Used.

subject:genderSexSubjectBean:gendersubject:gender– should be ‘m’ or ‘f’ char <gender>m<gender>

Y – if “Study Parameter Configuration – Sex Required” is set to Yes.

N – if “Study Parameter Configuration – Sex Required” is set to No.

subject:dateOfBirthDate of BirthSubjectBean:dateOfBirthsubject:date_of_birth– should be a valid date in the ISO 8601 format Date<dateOfBirth>2008-12-12</dateOfBirth>

 Y – if “Study Parameter Configuration – Collect Subject Date of Birth” is set to Yes.

N – if “Study Parameter Configuration – Collect Subject Date of Birth” is set to Not Used or Only Year of Birth.

subject:yearOfBirthDate of BirthSubjectBean:dateOfBirthsubject:date_of_birth– should be a valid year Date <yearOfBirth>2008</yearOfBirth>

 Y – if “Study Parameter Configuration – Collect Subject Date of Birth” is set to Only Year of Birth.

N – if “Study Parameter Configuration – Collect Subject Date of Birth” is set to Not Used or Yes.

studyRef:identifierUnique Protocol IDStudyBean:identifierstudy:unique_identifier

– should be a valid study identifier

 String <identifier>StudyA</identifier> Y
siteRef:identifierUnique Protocol IDStudyBean:identifierstudy:unique_identifier– should be a valid site identifier String <identifier>SiteA</identifier> N

 

 Response Parameters

 
ParameterUIDomainDBResult on successResult on fail
labelStudy Subject IDStudySubjectBean:labelstudy_subject:label<label>SSID001</label><label/>
resultn/an/an/a<result>Success</result><result>Fail</result>
warningn/an/an/an/an/a
errorn/an/an/an/a<error>An error message indicating reason of failure</error>

2.2.2 listAllByStudy (List studySubjects in a study)

Lists studySubjects in a study regardless of its state (i.e It also includes a removed studySubject in a study).

Usage

Lists study subjects that are a part of an OpenClinica study or site.

SOAP XML Request and Response Template

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://openclinica.org/ws/studySubject/v1" xmlns:bean="http://openclinica.org/ws/beans">
${insert header}
<soapenv:Body>
<v1:listAllByStudyRequest>
<bean:studyRef>
<bean:identifier>?</bean:identifier>
<!--Optional:
<bean:siteRef>
<bean:identifier>?</bean:identifier>
</bean:siteRef>--!>
</bean:studyRef>
</v1:listAllByStudyRequest>
</soapenv:Body>
</soapenv:Envelope>


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<ns4:listAllByStudyResponse xmlns:ns4="http://openclinica.org/ws/studySubject/v1" xmlns:ns2="http://openclinica.org/ws/beans" xmlns:ns3="http://openclinica.org/ws/crf/v1">
<ns4:result>Success</ns4:result>
<ns4:studySubjects>
<ns2:studySubject>
<ns2:label>label</ns2:label>
<ns2:secondaryLabel/>
<ns2:enrollmentDate>2010-03-31</ns2:enrollmentDate>
<ns2:subject>
<ns2:uniqueIdentifier/>
<ns2:gender>m</ns2:gender>
</ns2:subject>
<ns2:events>
<ns2:event>
<ns2:location>Boston</ns2:location>
<ns2:startDate>2010-03-31</ns2:startDate>
<ns2:startTime>00:00:00</ns2:startTime>
</ns2:event>
</ns2:events>
</ns2:studySubject>
</ns4:studySubjects>
</ns4:listAllByStudyResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Parameters

Request Parameters

 
ParameterUIDomainDBValidationsDatatypesExamplesRequired
studyRef:identifierUnique Protocol IDStudyBean:identifierstudy:unique_identifierN/AString<identifier>study identifier</identifier>Y
siteRef:identifierUnique Protocol IDStudyBean:identifierstudy:unique_identifierN/AString<identifier>site identifier</identifier>N

Response Parameters

 
ParameterUIDomainDBResult on successResult on fail
resultn/an/an/a<result>Success</result><result>Fail</result>
warningn/an/an/a<warning>A warning message</warning>n/a
errorn/an/an/an/a<error>An error message indicating reason of failure</error>
studySubject:labelStudySubject IDStudySubjectBean:labelstudy_subject:label<label>label</label>n/a
studySubject:secondaryLabelSecondary IDStudySubjectBean:secondaryLabelstudy_subject:secondary_label<secondaryLabel/> or <secondaryLabel>label</secondaryLabel>n/a
subject:uniqueIdentifierPerson IDSubjectBean:uniqueIdentifiersubject:unique_identifier<uniqueIdentifier/> or <uniqueIdentifier>uId</uniqueIdentifier>n/a
subject:genderSexSubjectBean:gendersubject:gender<gender>m</gender> or <gender>f</gender>n/a
subject:dateOfBirthDate of BirthSubjectBean:dateOfBirthsubject:date_of_birth<dateOfBirth>2008-12-12</dateOfBirth>n/a
subject:yearOfBirthDate of BirthSubjectBean:dateOfBirthsubject:date_of_birth<yearOfBirth>2008</yearOfBirth>n/a
event:locationLocationStudyEvent:locationstudy_event:location<location>Boston</location>n/a
event:startDateStart Date/TimeStudyEvent:dateStartedstudy_event:date_start<startDate>2010-08-16</startDate>n/a
event:startTimeStart Date/TimeStudyEvent:dateStartedstudy_event:date_start<startTime>12:00:00</startTime>n/a
event:endDateEnd Date/TimeStudyEvent:dateEndedstudy_event:date_end<endDate>2010-08-16</endDate>n/a
event:endTimeEnd Date/TimeStudyEvent:dateEndedstudy_event:date_ended<endTime>15:00:00</endTime>n/a

2.2.3 isStudySubject (Queries OpenClinica if studySubject exists in a Study)

Queries OpenClinica if Study Subject exists.

Usage

Queries OpenClinica if a study subjects is assigned to a target study/site. Study Subject is looked up by Label (aka Study Subject ID) only.
If only the Study ID is provided (and not the Site ID), the web service will check for the Study Subject across all sites in the study and, if found, return a result of ‘Success’. If a Site Identifier is also provided the scope of the query will be limited to subjects in that study and site.

SOAP XML Request and Response Template

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:v1="http://openclinica.org/ws/studySubject/v1"
xmlns:bean="http://openclinica.org/ws/beans">
${insert header}
 <soapenv:Body>
<v1:isStudySubjectRequest>
<v1:studySubject>
<bean:label>?</bean:label>
<!--Lines selected in grey can be deleted from envelope. This information is NOT used by WS-->
<!--Optional:-->
<bean:secondaryLabel>?</bean:secondaryLabel>
<bean:enrollmentDate>?</bean:enrollmentDate>
<bean:subject>
<!--Optional:-->
<bean:uniqueIdentifier>?</bean:uniqueIdentifier>
<!--Optional:-->
<bean:gender>?</bean:gender>
<!--You have a CHOICE of the next 2 items at this level-->
<bean:dateOfBirth>?</bean:dateOfBirth>
<bean:yearOfBirth>?</bean:yearOfBirth>
</bean:subject>
<bean:studyRef>
<bean:identifier>?</bean:identifier>
<!--Optional:-->
<bean:siteRef>
<bean:identifier>?</bean:identifier>
</bean:siteRef>
</bean:studyRef>
</v1:studySubject>
</v1:isStudySubjectRequest>
</soapenv:Body>

</soapenv:Envelope>


<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<createResponse>
<result>success</result>
<label>?</label>
</createResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

 

Parameters

Request Parameters

 
ParameterUIDomainDBValidationsDatatypesExamplesRequired
labelStudy Subject IDStudySubjectBean:labelstudy_subject:label– cannot be longer than 30 charactersString<label>Sub A 101</label>

 Y

studyRef:identifierUnique Protocol IDStudyBean:identifierstudy:unique_identifier

– should be a valid study identifier

 String <identifier>StudyA</identifier> Y
siteRef:identifierUnique Protocol IDStudyBean:identifierstudy:unique_identifier– should be a valid site identifier String <identifier>SiteA</identifier> N

 

 Response Parameters

 
ParameterUIDomainDBResult on successResult on fail
studySubject:oc_oidStudy Subject OIDstudySubjectOIDstudy_subject:oc_oid<label>SSID001</label><label/>
resultn/an/an/a<result>Success</result><result>Fail</result>
warningn/an/an/an/an/a
errorn/an/an/an/a<error>An error message indicating reason of failure</error>