Oracle® Health Sciences mHealth Connector Cloud Service

Initialization

Set the device bootstrap parameters required to onboard a device on the mHealth platform.

Once a virtual device is registered in the mHealth platform for a subject, a unique client access code and one-time passcode is created for the device to enable physical device onboarding. These two parameters need to be set to call the setBootstrapParams method on the HsmHealthDeviceManager instance.

Method:

HsmHealthDeviceManager.shared.setBootstrapParam(url: String, accessId: String?, oneTimePassword: String?)

Arguments:

• Url—mHealth cloud device bootstrap webservice URL.

• accessId—Unique access code created when a virtual device is created in the mHealth application for a specific subject and an eSource.

• OneTimePassword—One-time password provided for the device onboarding process.

Return type: Void

Activation

A device cannot send or receive data until activated in the mHealth Connector with its virtual device model. After setting the bootstrap parameters, a device can be activated by calling activate method on the HsmHealthDeviceManager instance. The activation process downloads device activation parameters from mHealth Connector and activates the device in the cloud, establishing a secure communication channel between the application running on the physical device and mHealth Connector.

Method:

HsmHealthDeviceManager.shared.activate(callback: (Bool, HsError?) --> Void ) --> Void)

Arguments:

• callback—This method returns the status of the activation process. On successful activation of the device, the Boolean value is set to true and HsError is nil. On error conditions, an HsError instance is returned with cause of error. Call the send API only when this callback indicates that a device has been activated successfully.

Return type: Void

Example:

let hsDeviceMgr = HsmHealthDeviceManager.shared
hsDeviceMgr.activate { (activated, hsError) in
    if activated {
       //send message 
    } else {
       // error
    }
}

Data Transmission

To send data from your mobile application to mHealth Connector, use the send method in the HsmHealthDeviceManager class.

The data must be in JSON format (key-value pairs) and conform to the message structure and message format for a message URN defined in a device model. When called, this method will transmit the message to mHealth Connector.

Any message not containing the key attributes listed below will result in a message format error.

• KEY_EVENT_DATETIME_UTC— Event timestamp in yyyy-mm-ddThh:mi:ssZ format (ISO 8601 datetime format).

• KEY_TRIALID —Subject/trial Id value set via device bootstrap process.

• KEY_UID—Surrogate patient/subject Id value set via device bootstrap process.

Method:

HsmHealthDeviceManager.shared.send(_ msg:String?, msgFormat:String?, msgType: HsMessageType = HsMessageType.Data, msgReliability: HsMessageReliability = HsMessageReliability.guaranteed_delivery, callback: @escaping (Bool, String?)->Void)

Arguments:

• msg—JSON payload as string.

• msgFormat —Message URN. This value must match the message URN specified in the device data model created in mHealth Connector for this study.

• msgType —Message type can be Data or Alert type. Default type is Data.

• msgReliability —Value can be guaranteed_delivery or best_effort. By default, the library caches the messages until it is successfully transmitted to mHealth Connector. Message reliability is guaranteed only on activated devices.

• Callback—The caller receives status of the message transfer via this method. The Boolean value, True, indicates successful transfer of the message to mHealth Connector.

If the message is missing key attributes, as indicated above, or does not conform to JSON syntax, the result string includes the error description. A nil value for the result string indicates that the message was sent successfully to mHealth Connector.

Return: Void

Example: The example shows a JSON message for a pulse oximeter medical device.

• msg:

  "{\"KEY_PULSE\":511,\"KEY_SP02\":\"127\",\"KEY_UID\":\"Myuid\",
  \"KEY_DID\":\"pulseoxy\",\"KEY_SN\":\"pulseoxy\",
  \"KEY_EVENT_DATETIME_UTC\":2018-09-30T22:01:30Z\",\"KEY_TRIALID\":\"mhealth\"}"
  

• msgFormat:

  "urn:oraclehs:iot:device:data:hsgbupulseoxystrm3:mhealth"
   
  let hsDeviceMgr = HsmHealthDeviceManager.shared
  hsDeviceMgr.activate {(activated, hsError) in
          
    if activated {
                       let msgFormat = 
              "urn:oraclehs:iot:device:data:hsgbupulseoxystrm3:attributes"
                       hsDeviceMgr.send(msg, 
                                      msgFormat: msgFormat, 
                              callback: { (sent, error) in
    if sent {
       print ("Message sent successfully")
   
    } else {
       print ("Message sent error \(error)")
    }           
   
          } else {
             // error
          }
    }
          
                
   
  

  For each device model defined in the mHealth Connector study container, a unique data/alert message URN is created for each message/data sent from a device application to the mHealth Connector. The one included here is the message URN.

Once the send method is called for a message, the Client Library will attempt to send the message to mHealth Connector. If the Client Library is not able to make an internet connection, send will return an error message in the callback method.

Uploading a Large Object

If the message payload needs to include a large object, such as an image or video file, upload the object calling the uploadObject method of the HsmHealthDeviceManager class. Once the file is uploaded, a URI of the object in mHealth Connector is returned. Insert this URI as the value of the data/alert message attribute of the message.

Method:

HsmHealthDeviceManager.shared.uploadObject(inputFile: URL, objectName: String?, contentType: String?, callback: (HsExternalObject?, HsError?))

Arguments:

• inputFile—Image or video file URL on the device.

• objectName—Name of the object if it needs to be different than the file name in the inputFile argument. Otherwise, set this value to nil.

• contentType—Mime-type of the file. If this value is nil, the mHealth platform will assign an appropriate value.

• callback—This method returns the status of the upload. If HsExternalObject is not null, the externalObjectURL property of this object returns the uploaded file URL in mHealth Connector. If the upload fails, the HsError object returns error description and potential cause of error.

Return type: Void

Example:

let hsDeviceMgr = HsmHealthDeviceManager.shared
hsDeviceMgr.uploadObject(inputFile: imgFileUrl, 
                objectName: nil, contentType: nil) { (hsObject, hsError) 
            in
         if hsObject != nil {
                        print("Object Url:\(hsObject?.externalObjectURL)")
         }
            }

Initialization

Set the device bootstrap parameters required to onboard a device on the mHealth platform.

Once a virtual device is registered in the mHealth platform for a subject, a unique client access code and one-time passcode is created for the device to enable physical device onboarding. These two parameters need to be set to call the setBootstrapParams method on the HsmHealthDeviceManager instance.

Method:

HsmHealthDeviceManager.getSharedInstance().deviceBootstrap(final String url, final String clientAccessId, final String oneTimePassword, final Context context)

Arguments:

1. • dthUrl—mHealth cloud device bootstrap webservice URL.

   • clientAccessID—Unique access code created when a virtual device is created in the mHealth application for a specific subject and an eSource.

   • oneTimePassword—One-time password provided for the device onboarding process.

   • context—Android application context.

   Return type: Void

   Example:

   iotAccessManager.setBootstrapParams("https://mhealth.oraclecloud.com/deviceBootstrap", "clientId", "otp", getApplicationContext() ); 
   

Activation

A device cannot send or receive data until activated in mHealth Connector with its virtual device model. After setting the bootstrap parameters, a device can be activated by calling the activate method on the HsmHealthDeviceManager instance. The activation process downloads device activation parameters from mHealth Connector and activates the device in the cloud, establishing a secure communication channel between the application running on the physical device and mHealth Connector.

Method:

HsmHealthDeviceManager.getSharedInstance().activate(HsActivationCallback callback) throws HsError

Arguments:

• callback—This method returns the status of the activation process. On successful activation of the device, the Boolean value is set to true and HsError is nil. On error conditions, an HsError instance is returned with cause of error. Call the send API only when this callback indicates that a device has been activated successfully.

Return type: Void

Example:

try{HsmHealthDeviceManager.gerSharedInstance().activate(new HsActivationCallback() {    @Override    public void status(boolean success, HsError error) {        if (success) {    // send data         } else {        //print error        }    }});} catch (HsError e) {    }

Data Transmission

To send data from your mobile application to mHealth Connector, use the send method in the HsmHealthDeviceManager class.

The data must be in JSON format (key-value pairs) and conform to the message structure and message format for a message URN defined in a device model. When called, this method will transmit the message to mHealth Connector.

Any message not containing the key attributes listed below will result in a message format error.

• KEY_EVENT_DATETIME_UTC— Event timestamp in yyyy-mm-ddThh:mi:ssZ format (ISO 8601 datetime format).

• KEY_TRIALID —Trial/study Id value set via device bootstrap process.

• KEY_UID—Surrogate patient /subject Id value set via device bootstrap process.

Method:

HsmHealthDeviceManager.getSharedInstance().send(string jsonMsg, string dataFormat, HsMessageType hsMessageType, HsMessageReliability hsMessageReliability, HsDispatchCallback callback) throws HsErrorHsmHealthDeviceManager.getSharedInstance().send(string jsonMsg, string dataFormat, HsDispatchCallback callback) throws HsError

Arguments:

• jsonMsg—JSON payload as string.

• dataFormat—Message URN. This value must match the message URN specified in the device data model created in mHealth Connector.

• hsMessageType—Message type. Can be Data or Alert. In the overloaded method where this value is not set, message type will be set as Data.

• hsMessageReliability—Value can be guaranteed_delivery or best_effort. Message reliability is guaranteed only on activated devices. In the overloaded method, where this value is not set, the library will use the guaranteed_delivery value.

• callback—The caller will get status of the message transfer via this method. Implement the messageStatus method to receive the status.

Return: Void

Exception: HSError

Example: The example shows a JSON message for a pulse oximeter medical device.

• dataMsg:

  "{\"KEY_PULSE\":73,\"KEY_SP02\":95,\"KEY_UID\":\"Myuid\",
  \"KEY_DID\":\"pulseoxy\",\"KEY_SN\":\"pulseoxy\",
  \"KEY_EVENT_DATETIME_UTC\":"2017-11-01T12:02:01Z",\"KEY_TRIALID\":\"mhealth\"}"
  

• dataFormat:

   "urn:oraclehs:iot:device:data:hsgbupulseoxystrm3:mhealth" 
  

• Code Snippet:

   HsmHealthDeviceManager.getSharedInstance().send(        dataMsg,        dataFormat,        new HsDispatchCallback() {            @Override            public void messageStatus(boolean isSuccess, String msg)   {                if(isSuccess) {                                                       // send success                } else {                  /error                                    }            }        });