Oracle® Health Sciences Mobile Clinical Research Associate Server Application Programming Interface Guide Release 1.3 E47797-02 |
|
PDF · Mobi · ePub |
Application Programming Interface Guide
Release 1.3
E47797-02
March 2014
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. Both have different authentication mechanisms. The admin APIs can be authenticated using the basic authentication and non-admin APIs can be called by a token mechanism. For more information, see Section 1.3.
There is a Token jar file available with the package. You can use this to generate the token.
Tokens are available at the following levels:
Client level - The company using this installation. You can create multiple clients (companies), however, this is not necessary in most cases.
Source level - Lets you create separate keys for separate source of information. Once the keys are generated, you can create tokens and distribute them to the sources.
User level - Lets you build the site-at-a-glance KPIs, subscriptions, and alerts at the application level.
You can generate tokens using the ID and key, based on the required level and details mentioned in the API. For example, if you want to generate a client token, you need the client ID and client key.
The following is an example on how to generate a token:
TokenService service =
TokenServiceFactory.getInstance().withServiceUrl("http://<hostname>:<port>”).getTokenService();
String tokenString = service.createToken(<Id>, <Key>, <userId>, <Level>);
tokenString
returns the created Token to the caller.
Where, hostname
and port
is the configuration where Adaptive SAAG server is hosted.
userID
is applicable only for generating token at the user level. You must set this to null for all cases.
Key
is the value generated when the client or source is established. You can view the value in the Mobile CRA Administration Configuration screen.
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). After the APIs are called, you can view the key assigned to the client in the Administration UI. Only one client must be created.You must create the client before creating sources.
http://server:port/{app_root_context}/v1/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.
clientKey: Used to obtain tokens for authentication, which can be viewed in the Administration UI.
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 and client token when calling the API.
http://server:port/{app_root_context}/v1/sources
HTTP POST
Type: Access Type (Client)
Token: Generated Token
ID: ClientId
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.
sourceKey: Used for authentication for future REST APIs.
Error Code: Indicates success or failure.
This API is used to list all sources for a Client.
http://server:port/{app_root_context}/v1/sources
Request Header Parameters Type: Access Type (Client)
Token: Generated Token
ID: ClientId
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/{app_root_context}/v1/kpidefs
HTTP POST
Type: Access Type (Client)
Token: Generated Token
ID: ClientId
sourceId: The source for which the KPI needs to be created.
kpiName: KPI Name.
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 value is Float.
kpiId: ID of the KPI definition created. It is used to populate the KPI data.
kpiName: KPI name.
Error Code: Indicates success or failure.
This API is used to register all KPIs for a client.
http://server:port/{app_root_context}/v1/kpidefs?sourceType=KPI
HTTP GET
Type: Access type (Client)
Token: Generated token
ID: ClientId
Client ID: The ID of the client for listing the KPI definition.
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/{app_root_context}/v1/kpidefs/{kpiid}
HTTP PUT
Type: Access type (Client)
Token: Generated token
ID: ClientId
kpiName: KPI Name.
kpiDesc: Description of the KPI.
kpiDataType: Data type of the KPI.
kpiScope: Scope of KPI (generic, study, or study-site).
Error Code: Indicates success or failure.
This API is used to delete an existing KPI definition for a client.
http://server:port/{app_root_context}/v1/kpidefs/{kpiid}
HTTP DELETE
Type: Access type (Client)
Token: Generated token
ID: ClientId
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. You must submit a token that matches the Access type and the ID. That is, if the source is equal to the client, token must be generated using the client, and the ID must be equal to the client ID.
http://server:port/{app_root_context}//v1/kpidata
HTTP POST
Type: Access type (Source or Client)
Token: Generated token
ID: Client ID or 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.
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 /{app_root_context}/v1/kpidata/saag?studyId="<Study_ID>"&siteId="<Site_id>"
HTTP GET
Type: Access type (Client)
Token: Generated token
ID: Client ID
studyId: Study ID
siteId: Site ID
Error Code: Indicates success or failure.
studyData
{
"creationDate":,
"kpiDataType":,
"kpiId":,
"kpiName": "",
"kpiValue": "",
"kpiDisplayName":,
"kpiSeqNo":
}
genericData
{
"creationDate":,
"kpiDataType":,
"kpiId":,
"kpiName": "",
"kpiValue": "",
"kpiDisplayName":,
"kpiSeqNo":
}
siteListData
{
"siteId": "A",
"siteData": [{
"creationDate":,
"kpiDataType":,
"kpiId":,
"kpiName": "",
"kpiValue": "",
"kpiDisplayName":,
"kpiSeqNo":
}]
}
This API is used to get trending graph KPI data.
http:// server:port /{app_root_context}//v1/kpidata/graph?studyId="<Study_ID>"&siteId="<Site_ID>"&count=1
HTTP GET
Type: Access Type (Client)
Token: Generated Token
ID: Client ID
kpiInfoId: KPI ID
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:
{
"creationDate": 1,
"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/{app_root_context}/v1/user
HTTP POST
Type: Access Type (Client)
Token: Generated Token
ID: Client ID
userName: Name of the user to be created.
deviceId: Device ID of the device on which user has logged.
registrationToken: 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/{app_root_context}/v1/user/{userId}
HTTP PUT
Type: Access type (Client)
Token: Generated token
ID: Client ID
deviceId: Device ID of the device on which user has logged.
registrationToken: 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/{app_root_context}/v1/alertdefs
HTTP POST
Type: Access type (Client)
Token: Generated token
ID: Client ID
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/{app_root_context}/v1/alertdefs
HTTP POST
Type: Access type (User or Client)
Token: Generated token
ID: User ID or Client ID
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/{app_root_context}/v1/alertdefs/{alertId}
HTTP PUT
Type: Access type (Source)
Token: Generated token
ID: Source ID
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/{app_root_context}/v1/alertdefs/{alertId}
HTTP DELETE
Type: Access type (Source)
Token: Generated token
ID: Source ID
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/{app_root_context}/v1/alertsub
HTTP POST
Type: Access type
(User) Token: Generated token
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/{app_root_context}/v1/alertsub/{alertSubId}
HTTP DELETE
Type: Access type
(User) Token: Generated token
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/{app_root_context}//v1/notifications
HTTP POST
Type: Access type (Source or Client)
Token: Generated token
ID: Client ID or Source ID
List< AlertMessage> contains: List of alert data having the following fields:
alertId: Alert ID.
alertName: Required in case alert ID is not present.
sourceId: Required in case of client only.
Message: Alert message.
Error Code: Indicates success or failure.
This API is used to get all the alert messages for a user.
http://server:port/{app_root_context}/v1/alertmessage
HTTP GET
Type: Access type (User)
Token: Generated token
ID: User ID
List of Alert messages: List of alerts registered for the client (ID, message, and readFlag).
Error Code: Indicates success or failure.
This section contains the following APIs:
This API is used to post alert messages.
http://server:port/{app_root_context}//v1/notifications?startid=5&limit=10
HTTP GET
Type: Access type (User)
Token: Generated token
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/{app_root_context}//v1/{notificationId}
HTTP PUT
Type: Access type (User)
Token: Generated token
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).
limit (optional): Number of messages to be retrieved. By default, the value is 50.
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 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 1.3
E47797-02
Copyright © 2013, 2014, 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, 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 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.