Oracle® Health Sciences Mobile Clinical Research Associate Server

Application Programming Interface Guide

Release 2.0

E61218-01

November 2015

This document contains information on public Application Programming Interfaces (APIs) that can be used to interface with Oracle Health Sciences Mobile Clinical Research Associate Server (Mobile CRA).

It contains the following topics:

- Section 1, "Using Application Programming Interfaces"

- Section 2, "RESTful Application Programming Interfaces"

1 Using Application Programming Interfaces

This section describes how to use open Site-at-a-Glance (SAAG) Service Representational State Transfer (REST) APIs. It contains the following topics:

- Section 1.1, "About Application Programming Interfaces"

- Section 1.2, "Calling APIs from Outside the Mobile Clinical Research Associate Server"

1.1 About Application Programming Interfaces

Mobile CRA includes a set of APIs that lets you do most things through the user interface, including creating, modifying, and installing objects.

You can call Oracle Mobile CRA APIs from source code in a defined program in Mobile CRA. In this case, no additional security or setup is required.

You can let people in your company perform actions on Mobile CRA objects from an external system.

1.2 Calling APIs from Outside the Mobile Clinical Research Associate Server

There are two kinds of APIs created in the system, that is, admin APIs and non-admin APIs. The admin APIs and non-admin APIs can be authenticated using the basic authentication.

2 RESTful Application Programming Interfaces

REST is a software architecture for distributed hypermedia systems such as the World Wide Web. An API is described as RESTful when it conforms to the tenets of REST.

This section contains the following topics:

- Section 2.1, "Administration Application Programming Interfaces"

- Section 2.2, "Non-Administration Application Programming Interfaces"

2.1 Administration Application Programming Interfaces

This section contains the following topic:

- Section 2.1.1, "Create Client"

2.1.1 Create Client

This API is used to create a new client. You cannot create the client in the Administration User Interface (UI). Only one client must be created. You must create the client before creating sources. The client name must be the same as mentioned in WebLogic Security Realm under client Role.

URL

http://server:port/mobilecraservices/rest/clients

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Admin user name.

Password: Adaptive SAAG Admin password.

Request Parameters

clientName: Name of the client to be created.

clientDesc (optional): Short description.

numKpiToStore: Number of KPIs that are used to display in the trending graph. By default, the value is 6. This value is the number of bars shown in the SAAG UI, that is, the three trending graphs shown in the site selection slide. You cannot change this value once it is set.

Response Parameters

clientId: ID of the client created.

Error Code: Indicates success or failure.

2.2 Non-Administration Application Programming Interfaces

This section contains the following topics:

- Section 2.2.1, "Source"

- Section 2.2.2, "KPI Definition"

- Section 2.2.3, "KPI Data"

- Section 2.2.4, "User"

- Section 2.2.5, "Alert Definition"

- Section 2.2.6, "Alert Subscription"

- Section 2.2.7, "Alert Message"

- Section 2.2.8, "Alert Message Data"

2.2.1 Source

This section contains the following APIs:

- Section 2.2.1.1, "Create Source"

- Section 2.2.1.2, "List All Sources"

2.2.1.1 Create Source

This API is used to create a source for a client. You can create the source in the Administration UI. One source must be created for each external data source. Sources are subordinate to a client, which requires a client ID when calling the API. The source name must be the same as mentioned in the WebLogic Security Realm under source Role.

URL

http://server:port/mobilecraservices/rest/sources

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

sourceName: Name of the source to be created.

sourceDesc (optional): Short description.

sourceType: Indicates a KPI source or alert source.

Response Parameters

Source ID: ID of the source created. This should be used for registering and populating the KPI.

Error Code: Indicates success or failure.

2.2.1.2 List All Sources

This API is used to list all sources for a Client.

URL

http://server:port/mobilecraservices/rest/sources

Request Type HTTP GET

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Response Parameters

List of sources: List of Sources registered for a client (ID, name, description, and type).

Error Code: Indicates success or failure.

2.2.2 KPI Definition

This section contains the following APIs. You can create KPIs manually in the Administration UI. These APIs lets you create scripts and replicate setup in different instances (that is, test, QC, validation, and production).

Note:
The order of the KPIs in the KPI Administration screen impacts the display of the KPIs items. You cannot change the order through API.

- Section 2.2.2.1, "Create KPI Definition"

- Section 2.2.2.2, "List All KPI Definition"

- Section 2.2.2.3, "Update KPI Definition"

- Section 2.2.2.4, "Delete KPI Definition"

2.2.2.1 Create KPI Definition

This API is used to create a new KPI Definition for a particular source.

URL

http://server:port/mobilecraservices/rest/kpidefs

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

sourceId: The source for which the KPI needs to be created.

kpiName: KPI Name.

kpiDisplayName: Display Name to be used by Client.

kpiScope: Scope of KPI (GENERIC, STUDY, or STUDY-SITE).

kpiDesc (optional): Description of the KPI

kpiDataType (optional): Data type of the KPI (INTEGER or FLOAT). By default, the data type is FLOAT.

kpiSeqNo: Sequence number of KPI

Note:
KpiScope and kpiDataType must always be entered in capital letters.

Response Parameters

kpiId: ID of the KPI definition created. It is used to populate the KPI data.

Error Code: Indicates success or failure.

2.2.2.2 List All KPI Definition

This API is used to register all KPIs for a client.

URL

http://server:port/mobilecraservices/rest/kpidefs?sourceType=KPI

Request Type

HTTP GET

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Response Parameters

List of KPI: List of KPI registered for the client (ID, name, description, or data type).

Error Code: Indicates success or failure.

2.2.2.3 Update KPI Definition

This API is used to update an existing KPI definition for a Client.

URL http://server:port/mobilecraservices/rest/kpidefs/{kpiid}

Request Type

HTTP PUT

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

kpiSeqNo: Sequence number of KPI.

kpiDisplayName: Display Name to be used by client UI.

kpiDesc: Description of the KPI.

Response Parameters

Error Code: Indicates success or failure.

2.2.2.4 Delete KPI Definition

This API is used to delete an existing KPI definition for a client.

URL

http://server:port/mobilecraservices/rest/kpidefs/{kpiid}

Request Type

HTTP DELETE

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Response Parameters

Error Code: Indicates success or failure.

2.2.3 KPI Data

This section contains the following APIs. These APIs lets you submit data to display in SAAG and retrieve information for the display.

- Section 2.2.3.1, "Post KPI Data"

- Section 2.2.3.2, "Get SAAG KPI Data"

- Section 2.2.3.3, "Get Trending Graph KPI Data"

2.2.3.1 Post KPI Data

This API is used to post KPI data. Data can be submitted at the client or source level (which does not impact the display), and at the study or study-site level. Study KPIs display the same data regardless of the study-site selected.

URL

http://server:port/mobilecraservices/rest/kpidata

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Source user name

Password: Adaptive SAAG Source password

Type: Access Type (Source)

ID: Source ID

Request Parameters

List< KPIData>: List of KPI data having the following fields.

kpiInfoId: KPI ID

studyId: Required in case of study or study-site KPI.

siteId: Required in case of study site kpi.

kpiValue: KPI value (float or integer).

kpiName: Required along with source ID in case the KPI ID is not entered.

sourceId: Required in case of client only.

Response Parameters

Error Code: Indicates Success or Failure.

2.2.3.2 Get SAAG KPI Data

This API is used to get the SAAG KPI data.

URL

http://server:port/mobilecraservices/rest/kpidata/saag?studyId={Study Id}&siteId={Site Id}

Request Type

HTTP GET

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

studyId: Study ID

siteId: Site ID

Response Parameters

Error Code: Indicates success or failure.

studyData

{

"kpiId":,

"kpiName": "",

"kpiValue": "",

"kpiDisplayName":,

"kpiSeqNo":

}

genericData

{

"kpiId":,

"kpiName": "",

"kpiValue": "",

"kpiDisplayName":,

"kpiSeqNo":

}

siteListData

{

"siteId": "A",

"siteData": [{

"kpiId":,

"kpiName": "",

"kpiValue": "",

"kpiDisplayName":,

"kpiSeqNo":

}]

}

2.2.3.3 Get Trending Graph KPI Data

This API is used to get trending graph KPI data.

URL

http://server:port/mobilecraservices/rest/kpidata/graph?studyId={Study Id}&siteId={Site Id}&count=1

Request Type

HTTP GET

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

studyId: Study ID

siteId (Optional): Site ID

Count (Optional): Number of KPIs to be used for graph. By default, the value is 3.

Response Parameters

Error Code: Indicates success or failure.

studyId

siteDataList:

[

{

"studyId": "A",

"siteId": "Site A",

"kpiList": []

}]

kpiList:

[

{

"data": [ ],

"kpiId": 1,

"kpiName": "A",

"kpiDisplayName:"Display""

}

]

Data:

{

"kpiData": "1"

}

2.2.4 User

This section contains the following user level APIs. For an implementation that involves Adaptive SAAG server, the server code handles the user registration automatically during login.

- Section 2.2.4.1, "Registering the User"

- Section 2.2.4.2, "Update User"

2.2.4.1 Registering the User

This API is used to register a user.

URL

http://server:port/mobilecraservices/rest/user

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

userName: Name of the user to be created.

deviceId: Device ID of the device on which user has logged.

regToken: Registration token from Health Sciences Push Notification Service (HSPNS).

Response Parameters

userId: ID of registered user.

Error Code: Indicates success or failure.

2.2.4.2 Update User

This API is used to update user details.

URL

http://server:port/mobilecraservices/rest/user/{userId}

Request Type

HTTP PUT

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

deviceId: Device ID of the device on which user has logged.

registrationToken: Registration token from HSPNS.

Response Parameters

Error Code: Indicates success or failure.

2.2.5 Alert Definition

This section contains the following APIs. Alerts can be manually created in the Administration UI. These APIs lets you create scripts and replicate setup in different instances (that is, test, QC, validation, and production).

Note:
These alerts on the UI is displayed in a separate section called the 3rd Party Alerts.

- Section 2.2.5.1, "Create Alert Definition"

- Section 2.2.5.2, "List All Alert Definition"

- Section 2.2.5.3, "Update Alert Definition"

- Section 2.2.5.4, "Delete Alert Definition"

2.2.5.1 Create Alert Definition

This API is used to create a new alert definition for a particular source.

URL

http://server:port/mobilecraservices/rest/alertdefs

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

sourceId: The source for which the alert needs to be created.

alertName: Alert name.

alertDesc (optional): Description of the alert.

alertDisplayName: Display name of the alert.

Response Parameters

alertId: ID of the alert definition that is used to populate the alert data.

Error Code: Indicates success or failure.

2.2.5.2 List All Alert Definition

This API is used to get all the alerts registered for a client.

URL

http://server:port/mobilecraservices/rest/alertdefs

Request Type

HTTP GET

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

Client ID: ID of the client for listing alert definitions.

Response Parameters

List of Alerts: List of alerts registered for the client (ID, source ID, name, description, displayName, and isSubscribed).

Error Code: Indicates success or failure.

2.2.5.3 Update Alert Definition

This API is used to update an existing alert definition.

URL

http://server:port/mobilecraservices/rest/alertdefs/{alertId}

Request Type

HTTP PUT

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Request Parameters

alertName: Name of the KPI.

alertDesc (optional): Description of the alert.

alertDisplayName: Display name of the alert.

Response Parameters

Error Code: Indicates success or failure.

2.2.5.4 Delete Alert Definition

This API is used to delete an existing alert definition for a Client.

URL

http://server:port/mobilecraservices/rest/alertdefs/{alertId}

Request Type

HTTP DELETE

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (Client)

Response Parameters

Error Code: Indicates success or failure.

2.2.6 Alert Subscription

When you subscribe to 3rd party alerts, the system automatically registers you for such alerts. The following APIs are involved during the subscription process that uses the user ID.

- Section 2.2.6.1, "Subscribe Alert"

- Section 2.2.6.2, "Unsubscribe Alert"

2.2.6.1 Subscribe Alert

This API is used to subscribe an alert for a user.

URL

http://server:port/mobilecraservices/rest/alertsub

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (User)

Id: User ID

Request Parameters

alertSubId: The alert subscription ID for which the alert is subscribed.

Response Parameters

SubscriptionId: Subscription ID of subscribed alert.

Error Code: Indicates success or failure.

2.2.6.2 Unsubscribe Alert

This API is used to unsubscribe an alert for a user.

URL

http://server:port/mobilecraservices/rest/alertsub/{alertSubId}

Request Type

HTTP DELETE

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (User)

Id: User ID

Response Parameters

Error Code: Indicates success or failure.

2.2.7 Alert Message

This section contains the following APIs. The post alert message API sends alert to the Alerts repository.

- Section 2.2.7.1, "Post Alert Message"

2.2.7.1 Post Alert Message

This API is used to post alert messages.

URL

http://server:port/mobilecraservices/rest/asaagnotifications

Request Type

HTTP POST

Request Header Parameters

Username: Adaptive SAAG Source user name

Password: Adaptive SAAG Source password

Type: Access Type (Source)

Id: SourceId

Request Parameters

List< AlertMessage> contains: List of alert data having the following fields:

alertInfoId: AlertInfoId is Alert ID.

alertName: Required in case alert ID is not present.

sourceId: Required in case of client only.

alertMessage: Alert message.

Response Parameters

Error Code: Indicates success or failure.

2.2.8 Alert Message Data

This section contains the following APIs:

- Section 2.2.8.1, "Get Alert Message Data"

- Section 2.2.8.2, "Update Alert Message Data"

2.2.8.1 Get Alert Message Data

This API is used to post alert messages.

URL

http://server:port/mobilecraservices/rest/asaagnotifications?startid=5&limit=10

Request Type

HTTP GET

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (User)

Id: User ID

Request Parameters

List< AlertMessage> contains: List of alert data having the following fields:

startId (optional): Start ID of the next batch of notification. Defaults to the first notification.

limit (optional): Number of messages to be retrieved. By default, the value is 50.

Response Parameters

List of Notifications: Notification list with the following data:

{

"date": "2013-06-21T16:57:06+0530",

"userId": null,

"header": "Display Name",

"notificationId": 54,

"read": true,

"important": true,

"notificationText": "Test Message 1"

}

nextPageStartId: Start ID to be used to get the next batch.

Error Code: Indicates success or failure.

2.2.8.2 Update Alert Message Data

This API is used to post alert messages.

URL

http://server:port/mobilecraservices/rest/asaagnotifications/{notificationId}

Request Type

HTTP PUT

Request Header Parameters

Username: Adaptive SAAG Client user name

Password: Adaptive SAAG Client password

Type: Access Type (User)

Id: User ID

Request Parameters

read: Flag to mark as read.

important: Flag to mark important (either read or important needs to be present as part of request). The accepted value is true or false.

Response Parameters

Error Code: Indicates success or failure.

3 Documentation Accessibility

For information about Oracle's commitment to accessibility, visit the Oracle Accessibility Program website at http://www.oracle.com/pls/topic/lookup?ctx=acc&id=docacc.

Access to Oracle Support

Oracle customers that have purchased support have access to electronic support through My Oracle Support. For information, visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=info or visit http://www.oracle.com/pls/topic/lookup?ctx=acc&id=trs if you are hearing impaired.

Oracle® Health Sciences Mobile Clinical Research Associate Server Application Programming Interface Guide, Release 2.0

E61218-01

Copyright © 2013, 2015, Oracle and/or its affiliates. All rights reserved.

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

This software or hardware and documentation may provide access to or information about content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services unless otherwise set forth in an applicable agreement between you and Oracle. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services, except as set forth in an applicable agreement between you and Oracle.

Oracle Legal Notices

Copyright Notice

Copyright © 1994-2015, Oracle and/or its affiliates. All rights reserved.

Trademark Notice

Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Intel and Intel Xeon are trademarks or registered trademarks of Intel Corporation. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. AMD, Opteron, the AMD logo, and the AMD Opteron logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

License Restrictions Warranty/Consequential Damages Disclaimer

This software and related documentation are provided under a license agreement containing restrictions on use and disclosure and are protected by intellectual property laws. Except as expressly permitted in your license agreement or allowed by law, you may not use, copy, reproduce, translate, broadcast, modify, license, transmit, distribute, exhibit, perform, publish, or display any part, in any form, or by any means. Reverse engineering, disassembly, or decompilation of this software, unless required by law for interoperability, is prohibited.

Warranty Disclaimer

The information contained herein is subject to change without notice and is not warranted to be error-free. If you find any errors, please report them to us in writing.

Restricted Rights Notice

If this is software or related documentation that is delivered to the U.S. Government or anyone licensing it on behalf of the U.S. Government, the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, delivered to U.S. Government end users are "commercial computer software" pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, use, duplication, disclosure, modification, and adaptation of the programs, including any operating system, integrated software, any programs installed on the hardware, and/or documentation, shall be subject to license terms and license restrictions applicable to the programs. No other rights are granted to the U.S. Government.

Hazardous Applications Notice

This software or hardware is developed for general use in a variety of information management applications. It is not developed or intended for use in any inherently dangerous applications, including applications that may create a risk of personal injury. If you use this software or hardware in dangerous applications, then you shall be responsible to take all appropriate fail-safe, backup, redundancy, and other measures to ensure its safe use. Oracle Corporation and its affiliates disclaim any liability for any damages caused by use of this software or hardware in dangerous applications.

Third-Party Content, Products, and Services Disclaimer

This software or hardware and documentation may provide access to or information on content, products, and services from third parties. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to third-party content, products, and services. Oracle Corporation and its affiliates will not be responsible for any loss, costs, or damages incurred due to your access to or use of third-party content, products, or services.

Alpha and Beta Draft Documentation Notice

If this document is in preproduction status:

This documentation is in preproduction status and is intended for demonstration and preliminary use only. It may not be specific to the hardware on which you are using the software. Oracle Corporation and its affiliates are not responsible for and expressly disclaim all warranties of any kind with respect to this documentation and will not be responsible for any loss, costs, or damages incurred due to the use of this documentation.