4 Web Services

This section includes the following topics:

Setting Up Web Services
Available Web Services

Java Web services are available to create object metadata in Oracle Clinical using information from another system.

The Web services are installed in OPA_HOME\webservices\11g\OracleClinical.ear.

Setting Up Web Services

You must apply the Oracle Clinical Web Services to a computer running Oracle Fusion Middleware 11g. You can use the Service Oriented Architecture (SOA) Suite 11g server for this purpose or you can use another computer running 11g.

Configuring Web Services

To configure Oracle Clinical 11g services:

Log in to the Weblogic 11g server console as the Weblogic user.
In the Domain Configurations panel, under the Deployed Resources section, select Deployments. The system displays all of the applications deployed currently on this server.
Click Install to deploy all of the options.
If the Web services .ear file is on your local system, click the Upload your file(s) option.
Click Next.
Click Next and then choose the option, "Install this deployment as an application."
Click Next.
Choose from the available targets, such as soa_server1, and click Next.
Choose OracleClinical-WS as the name of the application. Do not change any other default values. Then click Next. The system displays your configuration details. You can edit the details by navigating back through the screens.
Click Finish.

To confirm that the Web services deployed successfully:

Go to the list of Deployments and verify whether OC Webservices is present.
Click on the application and select the Testing tab. There should be three Test Points available to check the three Web services: InvestigatorService, Site Service, and StudySite Service.

To test any of these Web services, you must create a Data Source, as described in the following section. Once the Data Source is created, select the link Test Client under Test Point and check whether each Web service is working properly.

Continue in this session to complete the instructions in the following section.

Setting Up a Data Source

To create a data source:

In the same console screen from the previous steps, under Domain Structure (in the left part of the screen), click Services, then then click Data Sources. The system displays all existing data sources. The New button becomes active.
Click New. The screen displays three options.
Select the Generic Data Source option.
In the Create Screen, name the Datasource:

OracleClinicalCoreDS
In the JNDI Name column, enter:

jdbc/OracleClinicalCoreDS

Do not change any other values from their default values.
Click Next.
Click Next.
Click Next and enter the database name, host name, and port of your Oracle Clinical database. You must enter rxa_ws as the username and enter the password for rxa_ws user.
Click Next.
Select your SOA server as the target. For example, select soa_server1.
Click Finish. The Data Source is created and deployed on the target server.
Check in the list of the Data Sources whether this Data Source created successfully. Click on the Data Source and go to the Monitoring tab.
Select the Testing subtab to Test the Datasource.

Available Web Services

The following Web services are available:

Investigator Service
Site Service
Study Site Service

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.

Investigator Service

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

InvestigatorService has the following methods:

Create Investigator
Update Investigator
Request Investigator
Delete Investigator

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 Create Investigator 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.

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 Update Investigator 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.

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 Request Investigator 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.

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 Delete Investigator 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.

Site Service

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

SiteService has the following methods:

Create Site
Update Site
Request Site
Delete Site

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 Create Site 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.

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 Update Site 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.

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 Request Site 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.

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 Delete Site 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.

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:

Create Study Site
Update Study Site
Assign Investigator
Request Current Investigator Assignment
Request Investigator Assignment
Delete Investigator Assignment
Request Study Site
Delete Study Site

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 Create Study Site 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.

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 Update Study Site 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.

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 Assign Investigator 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.

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 Request Current Investigator Assignment 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.

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 Request Investigator Assignment 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.

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.

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 Request Study Site 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.

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.