Available Web Services

Web services are available in Oracle Clinical to automatically create and update Sites, Investigators, Study Sites, and Investigator assignments from information passed from an external system. These services were developed for use in the Oracle Clinical integration with Siebel Clinical, but they are available for use in integrating Oracle Clinical with other systems as well.

For more information, see:

Parent topic: Web Services

Investigator Service

The Investigator service allows you to create, update, request and delete Investigators.

InvestigatorService has the following methods:

Parent topic: Available Web Services

Create Investigator

This method creates a new Investigator in Oracle Clinical.

Web Service Name: InvestigatorService

Method Name: CreateInvestigator

Return Type: Investigator object set to Active and with INVESTIGATOR_ID and other autopopulated values populated.

Arguments: The following table displays the method's arguments.

Table 4-1 CreateInvestigator Method Arguments

Argument Name	Type	Description
Investigator	String	INVESTIGATOR_ID; the unique numeric database code for the Investigator. If the code is greater than ten characters, the system uses the generated Investigator ID instead.
Title	String	The Investigator's title; for example, `Dr`.
First Name	String	The Investigator's given name.
Initials	String	The Investigator's initials.
Last Name	String	The Investigator's family name.
Phone Number	String	The Investigator's telephone number.
Address Name	String	The Investigator's institution.
AddressLine1	String	The first line of the address of the Investigator.
AddressLine2	String	The second line of the address of the Investigator, if any.
AddressLine3	String	The third line of the address of the Investigator, if any.
City	String	The city in the Investigator's address.
State	String	The state must be a valid region code defined in the Regions form in Oracle Clinical.
Country	String	The country must be a valid region code defined in the Regions form in Oracle Clinical.
Postal Code	String	The postal code in the Investigator's address.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Investigator Service

Update Investigator

This method updates an existing Investigator in Oracle Clinical. If no current Investigator matches, the method returns an error. If you pass the Oracle Clinical Investigator ID, Oracle Clinical uses that to identify the correct Investigator. If not, the system uses the Investigator code, which may have originated in the source system.

Web Service Name: InvestigatorService

Method Name: UpdateInvestigator

Return Type: Investigator object.

Arguments: The following table displays the method's arguments.

Table 4-2 UpdateInvestigator Method Arguments

Argument Name	Type	Description
InvestigatorId	Double	INVESTIGATOR_ID; the unique numeric database code for the Investigator.
Investigator	String	A code for the Investigator; up to ten characters.
Title	String	The Investigator's title; for example, `Dr`.
First Name	String	The Investigator's given name.
Initials	String	The Investigator's initials.
Last Name	String	The Investigator's family name.
Phone Number	String	The Investigator's telephone number.
Address Name	String	The Investigator's institution.
AddressLine1	String	The first line of the address of the Investigator.
AddressLine2	String	The second line of the address of the Investigator, if any.
AddressLine3	String	The third line of the address of the Investigator, if any.
City	String	The city in the Investigator's address.
State	String	The state must be a valid region code defined in the Regions form in Oracle Clinical.
Country	String	The country must be a valid region code defined in the Regions form in Oracle Clinical.
Postal Code	String	The postal code in the Investigator's address.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Investigator Service

Request Investigator

This method returns the attributes of an Investigator in Oracle Clinical. If you pass the Oracle Clinical Investigator ID, Oracle Clinical uses that to identify the correct Investigator. If not, the system uses the Investigator code, which may have originated in the source system.

Web Service Name: InvestigatorService

Method Name: RequestInvestigator

Return Type: Investigator object.

Arguments: The following table displays the method's arguments.

Table 4-3 RequestInvestigator Method Arguments

Argument Name	Type	Description
InvestigatorId	Double	INVESTIGATOR_ID; the unique numeric database code for the Investigator.
Investigator	String	A code for the Investigator; up to ten characters.

Parent topic: Investigator Service

Delete Investigator

This method deletes an Investigator from Oracle Clinical. If you pass the Oracle Clinical Investigator ID, Oracle Clinical uses that to identify the correct Investigator. If not, the system uses the Investigator code, which may have originated in the source system.

If the Investigator is assigned to a study site or if any patient data has been entered against the Investigator, the method does not delete the Investigator and returns an error.

Web Service Name: InvestigatorService

Method Name: DeleteInvestigator

Return Type: No return value. Raises an exception if there is an error.

Arguments: The following table displays the method's arguments.

Table 4-4 DeleteInvestigator Method Arguments

Argument Name	Type	Description
InvestigatorId	Double	INVESTIGATOR_ID; the unique numeric database code for the Investigator.
Investigator	String	A code for the Investigator; up to ten characters.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The hostname of the source database.

Parent topic: Investigator Service

Site Service

The Site service allows you to create, update, request or delete a study site in Oracle Clinical.

SiteService has the following methods:

Parent topic: Available Web Services

Create Site

This method creates a new study site in Oracle Clinical. The study site is created as Active.

Web Service Name: SiteService

Method Name: CreateSite

Return Type: Site object with autopopulated values populated.

Arguments: The following table displays the method's arguments.

Table 4-5 CreateSite Method Arguments

Argument Name	Type	Description
Site	String	A unique code for the study site of ten characters or less. If the code is greater than ten characters, the system uses the generated Site ID instead.
Name	String	The name of the study site; up to 60 characters.
Phone Number	String	The study site's telephone number.
AddressLine1	String	The first line of the address.
AddressLine2	String	The second line of the address, if any.
AddressLine3	String	The third line of the address, if any.
City	String	The city in the address.
State	String	The state must be a valid region code defined in the Regions form in Oracle Clinical.
Country	String	The country must be a valid region code defined in the Regions form in Oracle Clinical.
Postal Code	String	The postal code in the address.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The hostname of the source database.

Parent topic: Site Service

Update Site

This method updates an existing study site in Oracle Clinical. The study site is set to Active. This method uses SiteId to identify the study site or, if that value is not passed in, it uses the value of study site. If no current study site matches, it raises an exception.

Web Service Name: SiteService

Method Name: CreateSite

Return Type: Site object.

Arguments: The following table displays the method's arguments.

Table 4-6 UpdateSite Method Arguments

Argument Name	Type	Description
SiteId	Double	SITE_ID; the unique numeric database code for the study site.
Site	String	The unique site code; up to ten characters.
Name	String	The name of the study site; up to 60 characters.
Phone Number	String	The study site's telephone number.
AddressLine1	String	The first line of the address.
AddressLine2	String	The second line of the address, if any.
AddressLine3	String	The third line of the address, if any.
City	String	The city in the address.
State	String	The state must be a valid region code defined in the Regions form in Oracle Clinical.
Country	String	The country must be a valid region code defined in the Regions form in Oracle Clinical.
Postal Code	String	The postal code in the address.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The hostname of the source database.

Parent topic: Site Service

Request Site

This method returns the attributes of a study site in Oracle Clinical. This method uses SiteId to identify the study site or, if that value is not passed in, it uses the value of study site.

Web Service Name: SiteService

Method Name: RequestSite

Return Type: Site view object.

Arguments: The following table displays the method's arguments.

Table 4-7 RequestSite Method Arguments

Argument Name	Type	Description
SiteId	Double	SITE_ID; the unique numeric database code for the study site.
Site	String	The unique site code; up to ten characters.

Parent topic: Site Service

Delete Site

This method deletes a study site from Oracle Clinical. If the study site is assigned to a study or if any patient data has been entered against it, the method does not delete the study site and returns an error.

Web Service Name: SiteService

Method Name: DeleteSite

Return Type: Void. Raises an exception if there is an error.

Arguments: The following table displays the method's arguments.

Table 4-8 DeleteSite Method Arguments

Argument Name	Type	Description
SiteId	Double	SITE_ID; the unique numeric database code for the study site.
Site	String	The unique site code; up to ten characters.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Site Service

Study Site Service

The Study Site service allows you to create, request, update or delete a study site. It also allows you to create, request, or delete the Investigator assignment for a study site.

InvestigatorService has the following methods:

Parent topic: Available Web Services

Create Study Site

This method creates a new study site in Oracle Clinical.

Web Service Name: StudySiteService

Method Name: CreateStudySite

Return Type: StudySite object with autopopulated values populated.

Arguments: The following table displays the method's arguments.

Table 4-9 CreateStudySite Method Arguments

Argument Name	Type	Description
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.
StudySite	String	The unique code to identify the site within the study; must be 10 characters or less.
StartDate	Date	The date the study site started participating in the study.
EndDate	Date	The date the study site stopped participating in the study.
FreezeFlag	Boolean	Frozen study sites cannot have data entered or changed. However, setting this flag through this Web service has no effect. To freeze data, use the batch job in Oracle Clinical under Conduct, Security, then Freeze.
OktoShipFlag	Boolean	If True, the site is approved for the shipment of drug supplies.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Study Site Service

Update Study Site

This method updates an existing study site in Oracle Clinical, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception.

Web Service Name: StudySiteService

Method Name: UpdateStudySite

Return Type: StudySite object.

Arguments: The following table displays the method's arguments.

Table 4-10 UpdateStudySite Method Arguments

Argument Name	Type	Description
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the study site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.
StudySite	String	The unique code to identify the site within the study; must be 10 characters or less.
StartDate	Date	The date the study site started participating in the study.
EndDate	Date	The date the study site stopped participating in the study.
FreezeFlag	Boolean	Frozen study sites cannot have data entered or changed. However, setting this flag through this Web service has no effect. To freeze data, use the batch job in Oracle Clinical under Conduct, Security, then Freeze.
OktoShipFlag	Boolean	If True, the site is approved for the shipment of drug supplies.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Study Site Service

Assign Investigator

This method assigns an existing Investigator to a study site in Oracle Clinical, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception. If an Investigator is already assigned to the study site, the existing Investigator assignment is terminated with a termination date of sysdate.

Web Service Name: StudySiteService

Method Name: AssignInvestigator

Return Type: StudySiteRole object.

Arguments: The following table displays the method's arguments.

Table 4-11 AssignInvestigator Method Arguments

Argument Name	Type	Description
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the Site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.
InvestigatorId	Double	INVESTIGATOR_ID; the unique numeric database code for the Investigator.
StartDate	Date	The date the Investigator was assigned to the study.
TerminationDate	Date	The date the Investigator was removed from the study.
ContractDate	Date	The date the Investigator's contract began.
DiscontinuationLetterDate	Date	The date the Investigator's letter of discontinuation was sent, if any.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Study Site Service

Request Current Investigator Assignment

This method returns the attributes of the current Investigator assignment to a study site in Oracle Clinical, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception.

Web Service Name: StudySiteService

Method Name: RequestCurrentInvestigatorAssignment

Return Type: StudySiteRole object.

Arguments: The following table displays the method's arguments.

Table 4-12 RequestCurrentInvestigatorAssignment Method Arguments

Argument Name	Type	DescriptionDescription
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the Site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.

Parent topic: Study Site Service

Request Investigator Assignment

This method returns the attributes of an existing Investigator assignment to a study site in Oracle Clinical, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception.

Web Service Name: StudySiteService

Method Name: RequestInvestigatorAssignment

Return Type: StudySiteRole object.

Arguments: The following table displays the method's arguments.

Table 4-13 RequestInvestigatorAssignment Method Arguments

Argument Name	Type	Description
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the study site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.
InvestigatorId	Double	INVESTIGATOR_ID; the unique numeric database code for the Investigator.
StartDate	Date	The date the Investigator was assigned to the study.

Parent topic: Study Site Service

Delete Investigator Assignment

This method terminates the assignment of an Investigator to a study site in Oracle Clinical, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception.

Web Service Name: StudySiteService

Method Name: DeleteInvestigatorAssignment

Return Type: No return value. Raises an exception if there is an error.

Arguments: The following table displays the method's arguments.

Table 4-14 DeleteInvestigatorAssignmentMethod Arguments

Argument Name	Type	Description
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the study site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.
InvestigatorId	Double	INVESTIGATOR_ID; the unique numeric database code for the Investigator.
TerminationDate	Date	The date the Investigator was removed from the study.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Study Site Service

Request Study Site

This method returns the attributes of a study site in Oracle Clinical, including past and present Investigators assigned, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception.

Web Service Name: StudySiteService

Method Name: RequestStudySite

Return Type: StudySite with all StudySiteRoles.

Arguments: The following table displays the method's arguments.

Table 4-15 RequestStudySite Method Arguments

Argument Name	Type	Description
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the Site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.

Parent topic: Study Site Service

Delete Study Site

This method deletes a study site in Oracle Clinical, using the ClinicalStudyId and SiteId to find the correct row. If those values are not passed in, it uses the values of ClinicalStudy and Site. If no matching row exists, the method raises an exception. If an Investigator is assigned to the study site or if any patient data has been entered against it, the method does not delete the study site and returns an error.

Web Service Name: StudySiteService

Method Name: DeleteStudySite

Return Type: No return value. Raises an exception if there is an error.

Arguments: The following table displays the method's arguments.

Table 4-16 DeleteStudySite Method Arguments

Argument Name	Type	Description
ClinicalStudyId	Double	CLINICAL_STUDY_ID; the unique numeric database code for the study.
SiteId	Double	SITE_ID; the unique numeric database code for the Site.
ClinicalStudy	String	The unique study code; up to ten characters.
Site	String	The unique site code; up to ten characters.
SourceApplication	String	The name of the application sending the message.
UserName	String	The user name of the person sending the message.
DatabaseInstance	String	The database instance ID of the system creating the investigator.

Parent topic: Study Site Service

Partial Source Data Verification Web Service

You can use the Partial Source Data Verification (PSDV) web service to create a new patient SDV draft plan for a study site, update an existing draft plan, as well as publish the new plan immediately or defer publishing by saving it as a draft. Through this web service, you can update patient SDV plans in real time for a study site, rather than going through the RDC Onsite user interface.

Note:

Oracle recommends that you test the web service in Oracle Enterprise Manager (OEM) or by building a web service proxy before using it in a production environment. See Testing the PSDV Web Service for instructions to test this web service using OEM.

Web Service Name: DataPushService

Method Name: populateStudySiteDefaults

Return Type: PSDVResult object, with two fields:

Result: 0 if successful, or -1 if an error occurred
Error: contains error details, if an error occurred, otherwise blank.

Arguments: The following table displays the method's arguments.

Table 4-17 PopulateStudySiteDefaults Method Arguments

Argument Name	Type	Description
Study	String	The name of the study for which the patient SDV plan is being created or updated.
StudySite	String	The name of the site within the study for which the patient SDV plan is being created or updated.
PatInitCount	Integer	The initial count of patients to be selected for SDV.
PatAutoSelRate	Integer	The percentage of patients to be automatically selected for SDV.
Datasource	String	Optional. The name of the datasource to be used by the web service. The name should be that of the default datasource defined in rdcConfig.properties. The file is in the OPA_CONFIG_FOLDER, whose location is specified in the opa51 registry under HKEY_LOCAL_MACHINE > Software > Oracle.
User	String	The application username that the web service uses to perform updates. The audit trail reflects changes made by the web service as being performed by the user provided here.
PublishAction	String	Indicates if the new or updated plan should be published or saved as a draft. The accepted values are: `P` to publish the plan `D` to save the plan as a draft. See Table 4-18 for details on how the value you set for this argument interacts with the planAction argument value.
PlanAction	String	Indicates which action is taken in relation to the plan, depending on its in-application status. The accepted values are: `NA` to take no action if the plan already exists `UD` to update the draft with the values passed, if the plan already exists `RD` to recreate the already existing draft with the values passed. See Table 4-18 for details on how the value you set for this argument interacts with the publishAction argument value.

The combined use of the two action arguments, publishAction and planAction, can produce multiple outcomes, as shown in the following table.

Table 4-18 Outcomes of the Different Combinations of Publish and Plan Actions

#	Publish Action	Plan Action	Outcome If Draft Plan Exists	Outcome If Draft Plan Does Not Exist
1	D	NA	The existing draft plan is not changed.	A new draft plan is created with the values passed by the web service.
2	D	UD	The existing draft plan is updated with the new values passed by the web service.	A new draft plan is created with the values passed by the web service.
3	D	RD	A new draft plan is created as a copy of the published plan. The values for the initial patient count and auto-selection rate are passed by the web service. The entity level selection (patient or CRF) is inherited from the published plan. If no published plan exists, entity level selection is not defined for the new draft plan.	A new draft plan is created with the values passed by the web service.
4	P	NA	The web service makes no changes.*	A new plan is created with the values passed by the web service and the plan is published.
5	P	UD	The existing draft plan is updated with the new values passed by the web service and the plan is published.	A new plan is created with the values passed by the web service, and then published.
6	P	RD	A new draft plan is created as a copy of the published plan and is then published. The values for the initial patient count and auto-selection rate are passed by the web service. The entity level selection (patient or CRF) is inherited from the existing published plan. If no published plan exists, entity level selection is not defined for the new plan.	A new plan is created with the values passed by the web service, and then published.

* To publish an existing draft plan, use the RDC Onsite user interface. See Creating a New SDV Plan for instructions from Oracle Clinical Remote Data Capture Onsite User's Guide.

For more information, see:

Testing the PSDV Web Service

Parent topic: Available Web Services

Testing the PSDV Web Service

You can test the PSDV method of the Data Push Service using the web services test UI in Oracle Enterprise Manager (OEM). Before you proceed, make sure that the OPA server is running on the server where the Java Key Store is configured and that RDC Onsite is deployed and running.

Note:

This section provides instructions to test web service and security implementation without generating a web service client, which is required to use the web service in a live environment.

You can generate a web service client for deployment using a published WSDL. To locate the URL of the WSDL for the PSDV web service in the deployment, go to http://appserver:7221/rdcservice/DataPushService?wsdl, where appserver is replaced with the name of the server you are using.

Open OEM on the server where the Java Key Store is configured.

The address for OEM is of the form http://appserver:7101/em, where appserver is replaced by the name of the application server you are using.
Log in to OEM using your credentials.
In the tree menu on the left, expand the WebLogic Domain option by clicking on the plus icon to its left. The OPADomain option is now visible beneath.
Right-click on OPADomain in the tree menu and go to Web Services, then select Test Web Service.
In the WSDL field, add the address of the web service WSDL file. The URL is of the form http://appserver:7221/rdcservice/DataPushService?wsdl, where appserver is replaced with the name of the server you are using.

Note:
To identify the URL of the WSDL file for the Data Push Service, go to http://appserver:7221/rdcservice/DataPushService, where appserver is replaced with the name of the server you are using.
Click Parse WSDL. The details of the identified web service are retrieved and you should see the value populateStudySiteDefaults in the Operation drop-down list if you used the correct WSDL file.
In the Security section, select the OWSM Security Policies radio button.
From the Compatible Client Policies list, select oracle/wss11_x509_token_with_message_protection_client_policy.
Provide the location where the Java Key Store is configured in the JKS Keystore Location field. For example, C:\wss11_x509\client\client_keystore.jks.
In the JKS Keystore Password field, enter the password for the keystore above.
Click on Load Keys to the right of the fields to import signature key information from the keystore.
Select the Advanced Options box.
Select the webservice option from the Signature Key Alias drop-down list and then fill in the Signature Key Password field beneath with the password for the webservice alias.
In the Input Arguments section, set values for the arguments of the web service. All arguments are mandatory, except for Datasource.

See Table 4-17 for information on each of the arguments.
Click on Test Web Service in the lower right corner of the screen to test the web service with the current settings.

Once the test runs, the Response tab opens. The result of the test is shown in the two fields, result and error. The result field contains the value 0 if the test was successful, or -1 if an error occurred. If an error occurred, the details are shown in the error field.

Parent topic: Partial Source Data Verification Web Service