Oracle® Health Sciences mHealth Connector Cloud Service

Cloud-to-Cloud Connector Framework for Data Ingestion from a Third-Party Cloud Service

Release 1.4

F19304-01

June 2019

Contents

- Introduction

- Connector Framework Components

- Typical Workflow

- Create and Configure an HTTP Connector

- On-boarding a Device Cloud

- Documentation Accessibility

Introduction

The Cloud Connector framework allows customers to import data collected and managed by a third-party or device vendor's cloud platform to Oracle mHealth Connector Cloud. This document explains how device cloud vendors and the Oracle services team can use a set of standard connectors, including the standard HTTP connector, which accepts messages in JSON format from an external service.

If you are interested in connecting to mHealth Connector, please contact your Oracle sales representative or email Oracle Health Sciences at: healthsciences_ww_grp@oracle.com.

You can also visit the Oracle Health Sciences website at: https://www.oracle.com/industries/health-sciences/index.html">>https://www.oracle.com/industries/health-sciences/index.html

Connector Framework Components

The four components of the connector framework are the connector, the interpreter, the mapper, and the messenger.

Figure 1 mHealth Connector Cloud-to-Cloud Connector framework components

- Connector—This provider-specific code manages connection and communication with the provider's devices and services. It's responsible for device discovery, connection management, and communication of data from the external devices or cloud services, including the processing of any provider-specific communication metadata, known as the envelope. The three types of connectors are generic, specialized, and custom.

- Interpreter—The interpreter parses device payloads and extracts data and telemetry information. Interpreters can be categorized as JSON or binary. Binary interpreters support additional payload grammars which can be used to parse device-native binary payloads.

- Mapper—The device model mapper takes data extracted from incoming device data and processes it into messages that are compatible with the mHealth Connector cloud message format. You can create a mapping between the fields extracted from the incoming data parsed by the interpreter, to the fields of mHealth Connector device model format. The mapping docCloud-to-Cloud Connector Framework for Data Ingestion from a Third-Party Cloud Serviceument associates a grammar and a device model.

- Messenger—The messenger communicates information about the device registration, device metadata, and device message to the Oracle Internet of Things service instance embedded within the mHealth Connector platform.

Typical Workflow

In a typical workflow, a device cloud vendor calls a REST endpoint published by the mHealth Connector. The mHealth Cloud Service framework invokes a series of mappings and transformation steps, configured for each clinical study, to create a new data message and stores the message in the mHealth Cloud Service.

Table 1 Typical workflow

Task

More Information

Description

Create an HTTP connector and configure it.

Give a name and credentials for authentication.

Create and configure HTTP Connector.

Verify that the connector has stared.

Once the connector configuration is saved, it is automatically started by the framework.Review status and messages on the connector screen.

Create and configure HTTP Connector.

Create/upload device models.

Device models define the structure of a transformed message.Once a message is received, the interpreter transforms or maps incoming messages to a message format defined in the device model.

Create a new device model.

Create an interpreter.

The interpreter transforms or maps a message to an mHealth Connecter message format.

From the Interpreter screen, configure an interpreter specifying selection criteria, a device model, and the payload processing information. Create an interpreter for each device message format.

Configure interpreter.

Review device registration.

Send sample data from calling published mHealth Connector REST endpoint and verify that the virtual device instance and message created per the structure specified in the mapping screen of the interpreter.

Manage a virtual device.

Create and Configure an HTTP Connector

Connectors manage the connection and communication with devices or with third-party cloud services. They also process the metadata and telemetry data from the devices or the services. HTTP Connector hosts a set of HTTP servers that are front-ended with a load balancer. The HTTP Connector must be configured for basic authentication. For authentication configuration, create a user account with the administrator role in the embedded IoT cloud service console and configure the same in the Connector screen.

1. Open the Internet of Things Cloud Service management console.

2. Click Menu . Click Devices, and then click Connectors.

3. On the Connectors page, click Create New Connector .

4. Enter values in the Name and Description fields.

5. If you need only one instance of the connector, select 1 in the Scale Factor field.

6. In the Type field, select Generic.

7. In the Telemetry section, select the appropriate values.

- Protocol: Select HTTP Server.

- Authentication: Select Basic authentication, and then enter your user name and password. You must have administrative access to perform this step.

- Envelope: Click Add Grammar, and add the details in the Grammar window. Use the Map field to map the required device metadata fields with the values of the interpreted envelope data.

- Payload encoding: If your payload is in JSON, select asciihex. if your payload is in base64-encoded binary, select base64.

8. Click Save. When you receive the message, Saved successfully, click Back.
The generic connector is listed on the Connectors page and the State field displays the status of the connector. The five states are STARTING, STARTED, FAILED, STOPPING, and STOPPED. STARTED indicates that the connector is ready to accept device data.

- To modify your generic connector, click Edit .

- To remove the generic connector, click Delete .

- To create an instance of your generic connector, click Start .

Note:
The Edit, Delete, and Start buttons are enabled only when the connector is in STOPPED state.

- To view the device notifications that the connector receives, click connectors_messageALERT .

Note:
On the Notifications page, click the data under Content to view the device information. You can also create an interpreter from this page when device data is received for the first time. See Configure an Interpreter.

- To view the details of your generic connector, click View .

Figure 2 View the Cloud-to-Cloud Connector framework details

Note:
Depending on the volume, frequency of the data, etc., it is possible for a single connector to serve multiple clinical studies at the sane time. When a connector supports more than one study, make sure that a unique study identifier or a combination of attributes are included in the data payload so the framework can route the message to the correct mHealth study datastore.

Create an Interpreter

An interpreter parses the payload and extracts the device telemetry data. The framework then uses the data to form a device message in the mHealth Cloud. You create interpreters on the embedded IoT cloud service Devices configuration screen.

To create an interpreter you need the following:

- Selection criteria: The framework uses the selection criteria to decide which interpreter(s) to use to process the message received by a connector. If multiple interpreters are created with same selection criteria, the input messages will be processed by all those Interpreters. See Configure an Interpreter to define selection criteria.
Example: If the "type" attribute in the message payload contains string "E1," the Interpreter associated with this selection criterion will be used to process the message.

Figure 3 Selection criteria for creating an interpreter

- Device model: Identify the device model. The device model's attributes are used for mapping the message attributes.

- Sample payload: Provide a sample JSON payload data so that the mapping tool can start creating a source message-to-device model attributes mapping.

- Device metadata: Map the standard metadata fields such as Name, Hardware ID, or custom fields from parsed sample data (for example, Hardware ID mapped to KEY_UID (as per sample)).

Configure an Interpreter

To create an Interpreter from the management console:

1. Open the Oracle Internet of Things Cloud Service management console.

2. Click Menu .

3. Click Devices, and then click Interpreters.

4. On the Interpreters page, click Create New Interpreter .

5. Enter values in the Name and Description fields.

6. In the Selection Criteria field, select an attribute and map it to a pattern or value. The connector uses the selection criteria to select the interpreter.

Figure 4 Selection criteria for configuring an interpreter

7. Select the Device Model, and click Add Grammar.

1. Do one of the following:
For a JSON payload, enter the payload data in Sample Data and click Validate. The interpreted values are listed.

For a binary payload, enter the payload in Sample Data, enter the binary grammar in Grammar, and click Validate.

The interpreted values are listed.

2. From the Map list box, select an attribute of the device model.

3. From the adjacent combo box, select Property, ATTRIBUTE, and then the field of one of the interpreted values. Values can also be combined or manipulated using the Formula menu.

4. To select another attribute, click Add.

5. Repeat steps c and d to map the attributes of the device model that you need in the device message.

Figure 5 Map the attributes of the device model

8. In the Device Metadata section, select a field from the list box and map it to an attribute.

9. Click Add, and repeat the step for all the fields that you wish to map. These fields appear as metadata in the device record when the device is registered in Oracle Internet of Things Cloud Service.

10. Click Save.

11. When you receive a message, Saved successfully, click Back.
On the Interpreters page, your interpreter is listed and its Device Model is displayed.

- To modify any of the fields of your interpreter, click Edit .

- To remove the interpreter, click Delete .

On-boarding a Device Cloud

To send data to mHealth Cloud Service, a device cloud needs POST device messages for JSON format to a HTTP connector REST resource created in the mHealth Cloud Service. The entities within a JSON payload must be accessible using JSONPath notation. Although a data message can have an array of entities, it is expected that every POST message includes the same number of entities.

If one HTTP Connector handles data messages across multiple clinical studies, make sure that each message includes a study identifier field. Similarly, it is assumed that a subject identifier (a non-PII value) and a physical or virtual device identifier and /or serial number is included in every message. For example:

No

Payload

Comment

1

{
"deviceId" : "abcs-1234",
"deviceSerialNumber" : "serial#",
"studyname" : "clinical study",
"subjectId" : "patient identifier (non-PII)",
"event_timestamp" : "UTC time in ISO date format yyyy-mm-ddTHH:mi:ssZ",
"attribute_1" : "attribute_1_value",
"attribute_2" : attribute_2_value
}

Vendor cloud sends device messages in JSON format. One message per HTTP POST request.

2

{
"deviceId" : "abcs-1234",
"deviceSerialNumber" : "serial#",
"studyname" : "clinical study",
"subjectId" : "patient identifier (non-PII)",
"event_timestamp" : "UTC time in ISO date format yyyy-mm-ddTHH:mi:ssZ",
"attribute_1" : ["attribute_1_value_1", "attribute_1_value_2", "attribute_1_value_3" ],
"attriibute_2" : attribute_2_value
}

In this example, one of the JSON attribute values is an array. Payload from vendor cloud contains a message entity per POST request. In the 1.4 version, mHealth only supports a bounded array. It is expected that all POST requests include an array with the same number of elements.

3

{
"deviceId" : "abcs-1234",
"deviceSerialNumber" : "serial#",
"studyname" : "clinical study",
"subjectId" : "patient identifier (non-PII)",
"event_timestamp" : "UTC time in ISO date format yyyy-mm-ddTHH:mi:ssZ",
"attribute_1" : {
"attr1": "attribute_1_value",
"attr2": "attribute_2_value"
}
"attribute_2" : attribute_2_value
}

In this example, the HTTP POST request includes a message payload with complex JSON objects (except array) as values.

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.

Cloud-to-Cloud Connector Framework for Data Ingestion from a Third-Party Cloud Service, Release 1.4

Part Number F19304-01

Copyright © 2019, 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, 2019, Oracle and/or its affiliates.

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, then the following notice is applicable:

U.S. GOVERNMENT END USERS: Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs) and Oracle computer documentation or other Oracle data delivered to or accessed by U.S. Government end users are "commercial computer software" or “commercial computer software documentation” pursuant to the applicable Federal Acquisition Regulation and agency-specific supplemental regulations. As such, the use, reproduction, duplication, release, display, disclosure, modification, preparation of derivative works, and/or adaptation of i) Oracle programs (including any operating system, integrated software, any programs embedded, installed or activated on delivered hardware, and modifications of such programs), ii) Oracle computer documentation and/or iii) other Oracle data, is subject to the rights and limitations specified in the license contained in the applicable contract. The terms governing the U.S. Government’s use of Oracle cloud services are defined by the applicable contract for such services. 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.

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 Inside 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, Epyc, and the AMD logo are trademarks or registered trademarks of Advanced Micro Devices. UNIX is a registered trademark of The Open Group.

Third-Party Content, Products, and Services Disclaimer

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.

Pre-General Availability Draft Label and Publication Date

Pre-General Availability: 2019-01-15

Pre-General Availability Draft Documentation Notice

If this document is in public or private pre-General Availability status:

This documentation is in pre-General Availability 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.

Oracle Confidential Label

ORACLE CONFIDENTIAL. For authorized use only. Do not distribute to third parties.

Revenue Recognition Notice
If this document is in private pre-General Availability status:
The information contained in this document is for informational sharing purposes only and should be considered in your capacity as a customer advisory board member or pursuant to your pre-General Availability trial agreement only. It is not a commitment to deliver any material, code, or functionality, and should not be relied upon in making purchasing decisions. The development, release, and timing of any features or functionality described in this document remains at the sole discretion of Oracle.

This document in any form, software or printed matter, contains proprietary information that is the exclusive property of Oracle. Your access to and use of this confidential material is subject to the terms and conditions of your Oracle Master Agreement, Oracle License and Services Agreement, Oracle PartnerNetwork Agreement, Oracle distribution agreement, or other license agreement which has been executed by you and Oracle and with which you agree to comply. This document and information contained herein may not be disclosed, copied, reproduced, or distributed to anyone outside Oracle without prior written consent of Oracle. This document is not part of your license agreement nor can it be incorporated into any contractual agreement with Oracle or its subsidiaries or affiliates.

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.