Search
Link Search Menu Expand Document
Kony Quantum is now HCL Volt MX. See Revised Terminology. Current Quantum users, see the important note about API naming.
Release:

User Guide: SDKs > VoltMX Iris SDK > Binary APIs

Binary APIs

Volt MX Foundry SDK offer a different set of API to work with binary data on integration and object service. The APIs allow uploading and downloading binary data from different data providers such as Amazon S3, Box etc.

Online binary API allows downloading the files as a whole (typically small image files), in chunks (large pdfs or videos) or in streaming mode (raw bytes).

Note: For SPA/Desktop Web, SDK supports Binary APIs from release version V8 SP3 for Box adapter.

For Android and iOS, the Binary APIs are supported from V8 SP2 for Box adapter.

Integration Service APIs

Download API

The getBinaryData API allows users to download binary objects such as PDF, Document or any other files.

Syntax 

getBinaryData(operationName, downloadParams, streaming, headers, fileDownloadStartedCallback, chunkDownloadCompletedCallback, fileDownloadCompletedCallback, fileDownloadFailureCallback, options);

Parameters

Parameter Type Description
operationName String Integration service operation that provides the binary details. The parameter is used as part of Integration Service.
downloadParams JSON Download related parameters required for downloading the binary.
Streaming Boolean Boolean flag to determine if the required data must be sent in chunks or a file after download.
headers   Provision to send custom headers.
fileDownloadCompletedCallback True/False The callback is invoked after successful file download with the file path. The parameter is mandatory if the streaming is false.
chunkDownloadCompletedCallback True/False The callback is invoked after each successful chunk download. The parameter is invoked when the streaming is true. The callback is mandatory if the streaming is true.
fileDownloadCompletedCallback True/False The callback is invoked after successful file download with the file path. The parameter is mandatory if the streaming is false.
fileDownloadFailureCallback   Callback invoked in case of download failure.
options   Optional parameters are sent from this parameter. ChunkSize can be sent from this parameter. The parameter is used as part of Integration Service.

Options

Options Type Description Mandatory
ChunkSize String ChunkSize option allows to download the binary in chunks of given size. If a value is not specified, the default value is used. Default size is 1048576. No

Note: It is mandatory to pass all its parameters defined on the service.

Sample Code 

function fileDownloadStartedCallback(res) {
    //Callback
}

function chunkDownloadCompletedCallback(res) {
    //Callback
}

function fileDownloadCompletedCallback(res) {
    //Callback
}

function fileDownloadFailureCallback(err) {
    //Callback
}

var downloadParams = {};
var serviceName = "integration_service_name";
// Get an instance of SDK
var client = voltmx.sdk.getCurrentInstance();
var operationName = "operation_name";

// Adapter specific parameters (Mentioned below)
var integrationSvc = client.getIntegrationService(serviceName);
var streaming = false;
integrationSvc.getBinaryData(operationName,
    downloadParams,
    streaming, {},
    //Provision for user defined headers
    fileDownloadStartedCallback,
    chunkDownloadCompletedCallback,
    fileDownloadCompletedCallback,
    fileDownloadFailureCallback);

Note: For Android and iOS platforms, filePath or base64 chunk data is provided based on the streaming flag. For DesktopWeb Blob object is specified in successCallback.

Upload API

The uploadBinaryData API allows users to upload binary objects such as PDF, Document or any other files.

Syntax 

uploadBinaryData(operationName, uploadParams, fileUploadStartedCallback, chunkUploadCompletedCallback, fileUploadCompletedCallback, fileUploadFailureCallback)

Parameters

Parameters Type Description
operationName String Integration Service Operation which provides the binary details. The parameter is used as part of Integration Service.
uploadParams JSON upload related parameters required for uploading binary. The parameter is used as part of Integration Service.
fileUploadStartedCallback   The callback is invoked when the upload starts.
chunkUploadCompletedCallback   The callback is invoked when the upload of a chunk is completed. The parameter is applicable for backends that support chunked upload.
fileUploadCompletedCallback   The callback is invoked when the upload completes.
fileUploadFailureCallback   The callback is invoked when the upload fails (for any reason).

Note: It is mandatory to specify either FilePath or rawBytes for upload in the uploadParams parameter. Both parameters are NOT allowed together.

FilePath must contain a fully qualified path of a valid file present on the device.

rawBytes contains the raw bytes to be uploaded. An obvious usage is capturing an image using camera and uploading the same.

fileObject is accepted for DesktopWeb. fileObject is the output of Browse API and is the instance of File.

Common Parameters

uploadParams Type Description Mandatory
fileName String The valid file name of the file to be uploaded with the proper extension. Yes
FilePath String Fully qualified path of a valid file present on the mobile device. Yes (if rawBytes are not provided)
rawBytes String Raw bytes of file to be uploaded Yes (if FilePath is not provided)
fileObject File Output of the Browser API provided by HCL or the browser is a reference to the file in the device. Yes (for DesktopWeb)

Note: It is mandatory to pass all its parameters defined on the service.

Sample Code 

function fileUploadStartedCallback(res) {
    //Callback
}

function chunkUploadCompletedCallback(res) {
    //Callback
}

function fileUploadCompletedCallback(res) {
    //Callback
}

function fileUploadFailureCallback(err) {
    //Callback
}

var uploadParams = {};

var serviceName = "integration_service_name";
// Get an instance of SDK
var client = voltmx.sdk.getCurrentInstance();
var operationName = "operation_name";

// Adapter specific parameters (Mentioned below)
var integrationSvc = client.getIntegrationService(serviceName);

integrationSvc.uploadBinaryData(operationName,
    uploadParams,
    fileUploadStartedCallback,
    chunkUploadCompletedCallback,
    fileUploadCompletedCallback,
    fileUploadFailureCallback);

Object Service APIs

Download API

The getBinaryData API allows users to download binary objects such as PDF, Doc or any other files.

Syntax 

getBinaryData(options,fileDownloadStartedCallback, chunkDownloadCompletedCallback, fileDownloadCompletedCallback, fileDownloadFailureCallback)

Parameters

Parameter Type Description
options JSON Accepts a JSON object on which the binary is downloaded.
fileDownloadStartedCallback JSON The callback is invoked after the file download starts.
chunkDownloadCompletedCallback True/False The callback is invoked after each successful chunk download. The parameter is invoked when the streaming is true. The callback is mandatory if the streaming is true.
fileDownloadCompletedCallback True/False The callback is invoked after successful file download with the file path. The parameter is mandatory if the streaming is false.
fileDownloadFailureCallback True/False The callback is invoked in case of download failure.

Options

Options Type Description Mandatory Default
dataObject String Instance of voltmx.sdk.dto.DataObject Yes  
streaming Boolean Boolean flag to determine whether the data needed to be given to chunks or a file after download No False
queryParams   provision for the user to specify the additional query params to be sent in the download call. No Null
headers   Provision for sending custom headers. No Null
chunkSize   chunk size to download No 1048576

Sample Code 

var downloadParams = {};

// Adapter specific parameters (Mentioned below)
var objSvc = voltmx.sdk.getCurrentInstance().getObjectService("serviceName");

var dataObject = new voltmx.sdk.dto.DataObject("binaryObjectName");
dataObject.setRecord(downloadParams);

objSvc.getBinaryData({
        "dataObject": dataObject
    },
    function(response) {
        voltmx.print("fileDownloadStartedCallback: " + JSON.stringify(response));
    },
    function(response) {
        voltmx.print("chunkDownloadCompleteCallback: " + JSON.stringify(response));
    },
    function(response) {
        voltmx.print("fileDownloadCompleteCallback: " + JSON.stringify(response));
    },
    function(response) {
        voltmx.print("fileDownloadFailureCallback: " + JSON.stringify(response));
    });

Note: It is mandatory to pass all its parameters defined on the service.

Note: For Android and iOS platforms, filePath or base64 chunk data is provided based on the streaming flag. For DesktopWeb Blob object is specified in successCallback.

Upload API

The uploadBinaryData API allows users to download binary objects such as PDF, Doc, or any other files.

Syntax 

uploadBinaryData(options, fileUploadStartedCallback, chunkUploadCompletedCallback, fileUploadCompletedCallback, fileUploadFailureCallback)

Parameters

Parameter Type Description
options JSON The JSON object, based on the binary uploaded.
fileUploadStartedCallback   The callback is invoked when the upload starts.
chunkUploadCompletedCallback   The callback is invoked when the upload of a chunk is completed. The parameter is applicable for backends that support chunked upload.
fileUploadCompletedCallback   The callback is invoked when the upload completes.
fileUploadFailureCallback   The callback is invoked when the upload fails (for any reason). The JSON object specified under options is a voltmx.sdk.dto.DataObject containing relevant parameters for upload.

Options

Options Type Description Mandatory
dataObject   Instance of voltmx.sdk.dto.DataObject Yes

Common Parameters

uploadParams Type Description Mandatory
fileName String The valid file name of the file to be uploaded with the proper extension. Yes
FilePath String Fully qualified path of a valid file present on the mobile device. Yes (if rawBytes are not provided)
rawBytes String Raw bytes of file to be uploaded Yes (if FilePath is not provided)
fileObject File Output of the Browser API provided by HCL or the browser is a reference to the file in the device. Yes (for DesktopWeb)

Note: It is mandatory to pass all its parameters defined on the service.

Sample Code 

var uploadParams = {};
var client = voltmx.sdk.getCurrentInstance();
var objectSvc = voltmxClient.getObjectService("serviceName");
var dataObject = new voltmx.sdk.dto.DataObject("binaryObjectName");
dataObject.setRecord(uploadParams);

objectSvc.uploadBinaryData({
        "dataObject": dataObject
    },
    function(response) {
        voltmx.print("fileUploadStartedCallback: " + JSON.stringify(response));
    },
    function(response) {
        voltmx.print("chunkUploadCompleteCallback: " + JSON.stringify(response));
    },
    function(response) {
        voltmx.print("fileUploadCompleteCallback: " + JSON.stringify(response));
    },
    function(response) {
        voltmx.print("fileUploadFailureCallback: " + JSON.stringify(response));
    });