About EnOS Reporting Tool API¶

EnOS Reporting Tool is a lightweight tool empowering you to build report templates and manage daily reporting tasks with no code. For more information, see EnOS Reporting Tool.

Reporting Tool provides API services to facilitate the entire lifecycle of report design, generation, and schedule including the management of report templates and template parameters, report generation, report task troubleshooting, etc.

For more information on how to invoke EnOS APIs, see Get Started with EnOS API.

API List¶

Reporting Tool provides the following API services.

Operation Name	Description	URL	EnOS Cloud	EnOS Edge
Create Report Template	Create a report template	/report-design-service/v1.0/report-file?action=create	√	×
Update Report Template	Update a report template	/report-design-service/v1.0/report-file?action=update	√	×
Query Report Template	Query a report template	/report-design-service/v1.0/report-file?action=query	√	×
Query Series Report Parameter	Query a series of report templates	/report-design-service/v1.0/report-file/list?action=query	√	×
Delete Report Template	Delete a report template	/report-design-service/v1.0/report-file?action=delete	√	×
Query Template Parameter	Query template parameters	/report-design-service/v1.0/report-file/arguments?action=query	√	×
Generate Report	Generate a report	/report-runtime-service/v1.0/report?action=create	√	×

API Editions¶

The following table lists the API services included in Reporting Tool Enterprise and Lightweight editions.

Operation Name	Enterprise	Lightweight
Create Report Template	√	√
Update Report Template	√	√
Query Report Template	√	√
Query Series Report Parameter	√	√
Delete Report Template	√	√
Query Template Parameter	√	√
Generate Report	√	√

API Request¶

A Reporting Tool API request consists of the following parts:

Request URI¶

METHOD https://{api-gateway}/{service-name}/{version}/{endpoint-url}?{action=<action>&{ }}

In the URI：

METHOD：HTTP Method. For example, GET or POST.
api-gateway：API gateway address. For example, app-portal-xxx.envisioniot.com. It can be retrieved by logging in to the EnOS Management Console and clicking Help > Environment Information at the top right. Refer to the address under API Gateway.
service-name：Service name. For example, report-design-service or report-runtime-service.
version：API version. For example, v1.0.
endpoint-url：Resource name or operations on resources. For example, report-file or preview.
action=<action>&：Query parameters in URI. Use & as delimiters if there are multiple parameters. For example, action=query&orgId=yourOrgId.

Request Header¶

The fields required by REST API specification or the HTTP specification are bound in the request header.

The commonly used request header is Content-Type, which represents the data submission method. In general, its value can be set toapplication / json; charset = UTF-8; if file upload or other form submission is performed, the value is set to multipart / form-data; charset = UTF-8.

Request Parameters (Body)¶

The parameters in the request body vary depending on API services. The typical parameters used to designate a report template are listed below.

Name	Data Type	Description
reportKey	String	The unique key of the report template.
reportId	String	The ID of the report template.
originalId	String	The ID of the root report template.

The priority of these parameters is as follows:

reportId (highest) > reportKey > originalId (lowest).

Request Sample¶

#requestURI:
https://{api-gateway}/report-design-service/v1.0/report-file?orgId=yourOrgId&action=update
#requestbody:
{
    "file": "yourFileLocation",
    "reportKey": "yourKey",
    "category": "R",
    "type": "cus"
    "originalId":"originalReportId"
}

API Response¶

The structure of a Reporting Tool API response is as below.

{
    "msg": "{message}",
    "code": {code},
    "data": {data},
    "success": {true/false}
}

Response Parameters¶

An API response consists of the following parameters.

Name	Type	Description
msg	String	Description of API request status. Reporting Tool API returns Success or the detailed error message for every API request.
code	Integer	API request status code. Reporting Tool API returns 0 for a successful API request or a specific error code for a failed request. For more information, see Response Codes.
data	Array or Object	The returned dataset. The data type includes basic type, complex type, or array.
success	String	Reporting Tool API returns true or false to indicate if the API service was called successfully.

Response Codes ¶

The table below describes all response codes.

Code	Message	Description
0	Success	Success.
93001	Request parameters are non-compliance. Illegal parameters are { }	Illegal parameters are found in the request.
93002	Request body is non-compliance. Illegal request body is { }	Illegal body is found in the request.
93008	Error occurred when downloading files from the remote storage. File path is { }	Failed to download files from blob or S3.
93009	Error occurred when parsing report arguments.	Failed to parse report parameters.
93010	No available report or no permission to query reports. Report file IDs are :/query operation error.condition:{ }	Failed to query reports.
93012	Error occurred when generating reports. Download URL is { }, type is { }, category is { }	Failed to generate reports.
93013	Found more than one rptdesign files in zip folder. Files are { }	Multiple rptdesign files are found in the ZIP file.
93014	No rptdesign found: neither a single file nor a zip file is uploaded.	Failed to find a valid rptdesign file.
93015	zip file is broken	Corrupted ZIP file.
93016	rptdesign file is not compliance: the mime type must be XML while the current mime type is { }	Illegal rptdesign files.
93017	Error occurred when processing report parameters, msg : { }/rptdesign file contains sensitive string	Found incorrect report parameters during report generation.
93018	Render report exception, report file name : { } , render type : {}, locale { }	Failed to render reports during report generation.
93028	Report key is in use: report Key { } , type { } , category { }	Duplicate report template keys.
93029	No available records found from database, query criteria are { } , we expected at least { }	No available query results.
93030	Report key { } is not consistent with the root key	Inconsistent report template keys between the current template and its root template.
93070	Error occurred when uploading files to remote storage. File path is { }	Failed to upload files to blob or S3.
93071	Error occurred when uploading files, type : { } , category : { } , file name : { }	Failed to upload files.
93072	Failed to initialize report context	Failed to initialize report context.
93074	Could not find the authority rptdesign, condition { }， orgId{ }	No available rptdesign files.

Response Samples¶

Sample of response success.

{
    "msg": "Success",
    "code": 0,
    "data": {
        "reportId": "yourReportId",
        "fileName": "reportFileName.rptdesign"
    },
    "success": true
}

Sample of response failure.

{
    "msg": "Report key yourEnteredKey is not consistent with the root key ",
    "code": 93030,
    "success": false
}