Oracle® Health Sciences Mobile Clinical Research Associate Server Application Programming Interface Guide Release 2.0 E61218-01 |
|
PDF · Mobi · ePub |
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:
This section describes how to use open Site-at-a-Glance (SAAG) Service Representational State Transfer (REST) APIs. It contains the following topics:
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.
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.
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"
This section contains the following topic:
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.
http://server:port/mobilecraservices/rest/clients
HTTP POST
Username: Adaptive SAAG Admin user name.
Password: Adaptive SAAG Admin password.
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.
clientId: ID of the client created.
Error Code: Indicates success or failure.
This section contains the following topics:
This section contains the following APIs:
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.
http://server:port/mobilecraservices/rest/sources
HTTP POST
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
sourceName: Name of the source to be created.
sourceDesc (optional): Short description.
sourceType: Indicates a KPI source or alert source.
Source ID: ID of the source created. This should be used for registering and populating the KPI.
Error Code: Indicates success or failure.
This API is used to list all sources for a Client.
http://server:port/mobilecraservices/rest/sources
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
List of sources: List of Sources registered for a client (ID, name, description, and type).
Error Code: Indicates success or failure.
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.This API is used to create a new KPI Definition for a particular source.
http://server:port/mobilecraservices/rest/kpidefs
HTTP POST
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
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.kpiId: ID of the KPI definition created. It is used to populate the KPI data.
Error Code: Indicates success or failure.
This API is used to register all KPIs for a client.
http://server:port/mobilecraservices/rest/kpidefs?sourceType=KPI
HTTP GET
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
List of KPI: List of KPI registered for the client (ID, name, description, or data type).
Error Code: Indicates success or failure.
This API is used to update an existing KPI definition for a Client.
URL http://server:port/mobilecraservices/rest/kpidefs/{kpiid}
HTTP PUT
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
kpiSeqNo: Sequence number of KPI.
kpiDisplayName: Display Name to be used by client UI.
kpiDesc: Description of the KPI.
Error Code: Indicates success or failure.
This API is used to delete an existing KPI definition for a client.
http://server:port/mobilecraservices/rest/kpidefs/{kpiid}
HTTP DELETE
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
Error Code: Indicates success or failure.
This section contains the following APIs. These APIs lets you submit data to display in SAAG and retrieve information for the display.
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.
http://server:port/mobilecraservices/rest/kpidata
HTTP POST
Username: Adaptive SAAG Source user name
Password: Adaptive SAAG Source password
Type: Access Type (Source)
ID: Source ID
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.
Error Code: Indicates Success or Failure.
This API is used to get the SAAG KPI data.
http://server:port/mobilecraservices/rest/kpidata/saag?studyId={Study Id}&siteId={Site Id}
HTTP GET
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
studyId: Study ID
siteId: Site ID
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":
}]
}
This API is used to get trending graph KPI data.
http://server:port/mobilecraservices/rest/kpidata/graph?studyId={Study Id}&siteId={Site Id}&count=1
HTTP GET
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
studyId: Study ID
siteId (Optional): Site ID
Count (Optional): Number of KPIs to be used for graph. By default, the value is 3.
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"
}
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.
This API is used to register a user.
http://server:port/mobilecraservices/rest/user
HTTP POST
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
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).
userId: ID of registered user.
Error Code: Indicates success or failure.
This API is used to update user details.
http://server:port/mobilecraservices/rest/user/{userId}
HTTP PUT
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
deviceId: Device ID of the device on which user has logged.
registrationToken: Registration token from HSPNS.
Error Code: Indicates success or failure.
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.This API is used to create a new alert definition for a particular source.
http://server:port/mobilecraservices/rest/alertdefs
HTTP POST
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
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.
alertId: ID of the alert definition that is used to populate the alert data.
Error Code: Indicates success or failure.
This API is used to get all the alerts registered for a client.
http://server:port/mobilecraservices/rest/alertdefs
HTTP GET
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
Client ID: ID of the client for listing alert definitions.
List of Alerts: List of alerts registered for the client (ID, source ID, name, description, displayName, and isSubscribed).
Error Code: Indicates success or failure.
This API is used to update an existing alert definition.
http://server:port/mobilecraservices/rest/alertdefs/{alertId}
HTTP PUT
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
alertName: Name of the KPI.
alertDesc (optional): Description of the alert.
alertDisplayName: Display name of the alert.
Error Code: Indicates success or failure.
This API is used to delete an existing alert definition for a Client.
http://server:port/mobilecraservices/rest/alertdefs/{alertId}
HTTP DELETE
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (Client)
Error Code: Indicates success or failure.
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.
This API is used to subscribe an alert for a user.
http://server:port/mobilecraservices/rest/alertsub
HTTP POST
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (User)
Id: User ID
alertSubId: The alert subscription ID for which the alert is subscribed.
SubscriptionId: Subscription ID of subscribed alert.
Error Code: Indicates success or failure.
This API is used to unsubscribe an alert for a user.
http://server:port/mobilecraservices/rest/alertsub/{alertSubId}
HTTP DELETE
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (User)
Id: User ID
Error Code: Indicates success or failure.
This section contains the following APIs. The post alert message API sends alert to the Alerts repository.
This API is used to post alert messages.
http://server:port/mobilecraservices/rest/asaagnotifications
HTTP POST
Username: Adaptive SAAG Source user name
Password: Adaptive SAAG Source password
Type: Access Type (Source)
Id: SourceId
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.
Error Code: Indicates success or failure.
This section contains the following APIs:
This API is used to post alert messages.
http://server:port/mobilecraservices/rest/asaagnotifications?startid=5&limit=10
HTTP GET
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (User)
Id: User ID
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.
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.
This API is used to post alert messages.
http://server:port/mobilecraservices/rest/asaagnotifications/{notificationId}
HTTP PUT
Username: Adaptive SAAG Client user name
Password: Adaptive SAAG Client password
Type: Access Type (User)
Id: User ID
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.
Error Code: Indicates success or failure.
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
.
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.