KSC Open API  13.1
Kaspersky Security Center API description
ReportManager::ExecuteReportAsync ( int  lReportId,
params  pOptions,
[out] wstring  strRequestId 
)

Executes a report.

Asynchronously executes specified report and generates resulting data in the XML format and data for chart.

The KLPPT_EventRptExecDone event reports about the process and result of the report generation.

Parameters:
lReportId(int) report ID.
pOptions(params) options (see description below).
[out]strRequestId(wstring) ID of an asynchronous operation. To get a status, use AsyncActionStateChecker::CheckActionState. lStateCode "1" means OK, and "0" means fail. To get a result, use AsyncActionStateChecker::CheckActionState. pStateData contains URL-like links to download report files via the HTTP GET request (see description below). To cancel an operation, call ReportManager::ExecuteReportAsyncCancel.

The pOptions container must comprise at least one of the following attributes in order to have a correct format:

  • "KLRPT_OUTPUT_FORMAT"
  • "KLRPT_LOC_PRODUCTS"
  • "RPT_LOC_LOCALE"
  • "RPT_TIMEZONE_INFO"
  • "KLRPT_USE_UTC"

The full structure of the pOptions container is presented below:

            +--- (params)
                +---KLRPT_OUTPUT_FORMAT (paramParams)
                |   +---KLRPT_MAX_RECORDS_DETAILS (paramInt) = 3000
                |   +---KLRPT_TARGET_TYPE (paramInt) = 0
                |   +---KLRPT_XML_TARGET_TYPE (paramInt) = 2
                |   +---KLRPT_PDF_LANDSCAPE (paramBool) = true
                |   +---KLRPT_PDF_PAGE_SIZE (paramInt) = 9
                +---KLRPT_LOC_PRODUCTS (array)
                |   +---0 (paramParams)
                |       +---KLRPT_PROD_NAME (paramString) = "1093"
                |       +---KLRPT_PROD_NAME_LOC (paramString) = "Administration server"
                |       +---KLRPT_PROD_VER (paramString) = "1.0.0.0"
                |       +---KLRPT_PROD_VER_LOC (paramString) = "1.0.0.0"
                +---RPT_LOC_LOCALE (paramInt) = 2057
                +---KLRPT_USE_UTC (paramBool) = true
                +---RPT_TIMEZONE_INFO (paramParams)
                    +---RPT_TZ_BIAS (paramInt) = -180
                    +---RPT_TZ_DAYLIGHT_BIAS (paramInt) = -60
                    +---RPT_TZ_DAYLIGHT_DATE (paramParams)
                    |   +---RPT_STM_DAY (paramInt) = 0
                    |   +---RPT_STM_DAYOFWEEK (paramInt) = 0
                    |   +---RPT_STM_HOUR (paramInt) = 0
                    |   +---RPT_STM_MILLISECOND (paramInt) = 0
                    |   +---RPT_STM_MINUTE (paramInt) = 0
                    |   +---RPT_STM_MONTH (paramInt) = 0
                    |   +---RPT_STM_SECOND (paramInt) = 0
                    |   +---RPT_STM_YEAR (paramInt) = 0
                    +---RPT_TZ_DAYLIGHT_NAME (paramString) = "Russia TZ 2 Daylight Time"
                    +---RPT_TZ_STD_BIAS (paramInt) = 0
                    +---RPT_TZ_STD_DATE (paramParams)
                    |   +---RPT_STM_DAY (paramInt) = 0
                    |   +---RPT_STM_DAYOFWEEK (paramInt) = 0
                    |   +---RPT_STM_HOUR (paramInt) = 0
                    |   +---RPT_STM_MILLISECOND (paramInt) = 0
                    |   +---RPT_STM_MINUTE (paramInt) = 0
                    |   +---RPT_STM_MONTH (paramInt) = 0
                    |   +---RPT_STM_SECOND (paramInt) = 0
                    |   +---RPT_STM_YEAR (paramInt) = 0
                    +---RPT_TZ_STD_NAME (paramString) = "Russia TZ 2 Standard Time"
            

The full list of the report execution attributes is presented below:

AttributeTypeDescriptionAdditional information
"KLRPT_OUTPUT_FORMAT"paramParamsDescription of the report output format. Optional attribute.
"KLRPT_MAX_RECORDS_DETAILS"paramIntMaximum number of records in the detailed table. Optional attribute.
"KLRPT_TARGET_TYPE"paramIntReport target format. See Types of the report target format.

Optional attribute.

The default value is 0 (XML).

"KLRPT_XML_TARGET_TYPE"paramIntReport target XML format. See Types of the report XML target format.

Optional attribute.

The default value is -1 (Unknown).

"KLRPT_PDF_LANDSCAPE"paramBoolPDF report document orientation.

Optional attribute.

The default value is false.

Ignored for any format other than PDF.

"KLRPT_PDF_PAGE_SIZE"paramIntPage size for a PDF document with a report. See Sizes of a PDF report document.

Optional attribute.

The default value is 8 (A4).

Ignored for any format other than PDF.

"KLRPT_LOC_PRODUCTS"arrayArray of the internal and localized product names and versions. Optional attribute.
"KLRPT_PROD_NAME"paramStringName of the product. Required attribute.
"KLRPT_PROD_NAME_LOC"paramStringLocalized name of the product. Required attribute.
"KLRPT_PROD_VER"paramStringVersion of the product. Required attribute.
"KLRPT_PROD_VER_LOC"paramStringLocalized version of the product. Required attribute.
"RPT_LOC_LOCALE"paramIntLocale ID. Optional attribute.
"KLRPT_USE_UTC"paramBool If the attribute accepts true, values of the datetime fields will be in the YYYY-MM-DD'T'HH:mm:ss format. Time zone is considered (not the UTC time).

Optional attribute.

The default value is false.

"RPT_TIMEZONE_INFO"paramParamsTime zone settings. Optional attribute.
"RPT_TZ_BIAS"paramInt Difference between UTC and local time, in minutes. All time conversions between UTC and local time are based on the following formula: UTC = local time + bias. Required attribute.
"RPT_TZ_DAYLIGHT_BIAS"paramInt Offset value used when switching from standard time to daylight saving time.

Added to the "RPT_TZ_BIAS" value to form an offset when daylight saving time.

Ignored if the "RPT_TZ_DAYLIGHT_DATE" value is not supplied.

In the most time zones, the value of this attribute is –60.

"RPT_TZ_DAYLIGHT_DATE"paramParams Description of a date and local time when switching from standard time to daylight saving time occurs on this operating system.

IF a time zone has not daylight saving time or if the caller needs to disable daylight saving time, the "RPT_STM_MONTH" attribute must be zero.

If the date is present, the "RPT_TZ_STD_DATE" attribute must also be specified.

If the "RPT_STM_YEAR" attribute is not zero, the time conversion date is absolute and the time conversion occurs only one time. Otherwise, it is a relative date that comes every year.

"RPT_TZ_DAYLIGHT_NAME"paramString Description for daylight saving time. For example, "PDT" means Pacific Daylight Time. Can be empty.
"RPT_TZ_STD_BIAS"paramInt Offset value used in the local time conversion that occurs in standard time.

Added to the "RPT_TZ_BIAS" value to form an offset used for standard time.

Ignored if the "RPT_TZ_STD_DATE" value is not supplied.

In the most time zones, the value of this attribute is zero.

"RPT_TZ_STD_DATE"paramParams Description of a date and local time when switching from daylight saving time to standard time occurs on this operating system.

IF a time zone has not daylight saving time or if the caller needs to disable daylight saving time, the "RPT_STM_MONTH" attribute must be zero.

If the date is present, the "RPT_TZ_DAYLIGHT_DATE" attribute must also be specified.

If the "RPT_STM_YEAR" attribute is not zero, the time conversion date is absolute and the time conversion occurs only one time. Otherwise, it is a relative date that comes every year.

"RPT_TZ_STD_NAME"paramString Description of standard time. For example, "EST" means Eastern Standard Time. Can be empty.
"RPT_STM_DAY"paramIntDay of a month. Valid values are [1, 31].
"RPT_STM_DAYOFWEEK"paramIntDay of a week. Valid values are [0, 6] (starting from Sunday).
"RPT_STM_HOUR"paramIntHour. Valid values are [0, 23].
"RPT_STM_MILLISECOND"paramIntMillisecond. Valid values are [0, 999].
"RPT_STM_MINUTE"paramIntMinute. Valid values are [0, 59].
"RPT_STM_MONTH"paramIntMonth. Valid values are [1, 12] (starting from January).
"RPT_STM_SECOND"paramIntSecond. Valid values are [0, 59].
"RPT_STM_YEAR"paramIntYear. Valid values are [1601, 30827].

The full structure of the pStateData container is presented below:

            +--- (params)
                +---KLRPT_OUTPUT_FORMAT (paramParams)
                |   +---KLRPT_MAX_RECORDS_DETAILS (paramInt) = 3000
                |   +---KLRPT_TARGET_TYPE (paramInt) = 0
                |   +---KLRPT_XML_TARGET_TYPE (paramInt) = 2
                |   +---KLRPT_PDF_LANDSCAPE (paramBool) = true
                |   +---KLRPT_PDF_PAGE_SIZE (paramInt) = 9
                +---KLRPT_OUTPUT_FILE (paramString) = "/KLRT/7515da13-844e-47ce-ad64-af0009ef7c85.pdf"
                +---KLRPT_OUTPUT_CHART (paramString) = "/KLRT/7515da13-844e-47ce-ad64-af0009ef7c85.png"
                +---KLRPT_OUTPUT_LOGO (paramString) = "/KLRT/7515da13-844e-47ce-ad64-af0009ef7c85.hdr.png"
            

The full list of attributes received as a result of the asynchronous report execution is presented below:

AttributeTypeDescriptionAdditional information
"KLRPT_OUTPUT_FORMAT"paramParamsDescription of the report output format. Required attribute.
"KLRPT_MAX_RECORDS_DETAILS"paramIntMaximum number of records in the detailed table.

Required attribute.

The attribute is the same as in the pOptions container, or the attribute is initialized with the default value.

"KLRPT_TARGET_TYPE"paramIntReport target format. See Types of the report target format. Required attribute.
"KLRPT_XML_TARGET_TYPE"paramIntReport target XML format. See Types of the report XML target format.

Optional attribute.

It can be absent if the report target format is CSV or JSON, or the attribute can accept -1 if the report target format is XML.

"KLRPT_PDF_LANDSCAPE"paramBoolPDF report document orientation.

Optional attribute.

It is present if only the report XML target format is PDF.

"KLRPT_PDF_PAGE_SIZE"paramIntPage size for a PDF document with a report. See Sizes of a PDF report document

Optional attribute.

It is present if only the report XML target format is PDF.

"KLRPT_OUTPUT_FILE"paramStringURL-like link to download a report file via the HTTP GET request.

Required attribute.

Includes the "KLRT" prefix. See Some typical resources path prefixes.

"KLRPT_OUTPUT_CHART"paramStringURL-like link to download report chart file via HTTP GET request

Optional attribute.

It is absent if the report XML target format is not set or unknown.

Includes the "KLRT" prefix. See Some typical resources path prefixes.

"KLRPT_OUTPUT_LOGO"paramStringURL-like link to download the report logo file via the HTTP GET request.

Optional attribute.

It is absent if the report XML target format is not set or unknown.

Includes the "KLRT" prefix. See Some typical resources path prefixes.

See also the Python code below where the KlAkOAPI Python package is used:

    
        server = KlAkOAPI.AdmServer.KlAkAdmServer.Create("https://ksc.example.com:13299", "username", "password", verify = False)
        oReportManager = KlAkOAPI.ReportManager.KlAkReportManager(server)
        strResultFolder = 'results'
        # compose options
        options_format = KlAkOAPI.Params.KlAkParams({})
        options_format.AddInt('KLRPT_MAX_RECORDS_DETAILS', 3000)
        options_format.AddInt('KLRPT_TARGET_TYPE', 0)
        options_format.AddInt('KLRPT_XML_TARGET_TYPE',  0)  # report format: 0 for HTML, 1 for XLS, 2 for PDF
        options_format.AddBool('KLRPT_PDF_LANDSCAPE',  True)
        options_format.AddInt('KLRPT_PDF_PAGE_SIZE',  9)
        options_products = KlAkOAPI.Params.KlAkParams({})
        options_products.AddString('KLRPT_PROD_NAME', "1093")
        options_products.AddString('KLRPT_PROD_NAME_LOC', "Administration server")
        options_products.AddString('KLRPT_PROD_VER', "1.0.0.0")
        options_products.AddString('KLRPT_PROD_VER_LOC', "1.0.0.0")
        options_timezone = KlAkOAPI.Params.KlAkParams({})
        options_timezone.AddInt('RPT_TZ_BIAS', -180)
        options_timezone.AddInt('RPT_TZ_DAYLIGHT_BIAS', -60)
        options_timezone.AddParams('RPT_TZ_DAYLIGHT_DATE', {'RPT_STM_DAY':0, 'RPT_STM_DAYOFWEEK':0, 'RPT_STM_HOUR':0, 'RPT_STM_MILLISECOND':0, 'RPT_STM_MINUTE':0, 'RPT_STM_MONTH':0, 'RPT_STM_SECOND':0, 'RPT_STM_YEAR':0})
        options_timezone.AddString('RPT_TZ_DAYLIGHT_NAME', "Russia TZ 2 Daylight Time")
        options_timezone.AddInt('RPT_TZ_STD_BIAS', 0)
        options_timezone.AddString('RPT_TZ_STD_NAME', "Russia TZ 2 Standard Time")
        options_timezone.AddParams('RPT_TZ_STD_DATE', {'RPT_STM_DAY':0, 'RPT_STM_DAYOFWEEK':0, 'RPT_STM_HOUR':0, 'RPT_STM_MILLISECOND':0, 'RPT_STM_MINUTE':0, 'RPT_STM_MONTH':0, 'RPT_STM_SECOND':0, 'RPT_STM_YEAR':0})
        options = KlAkOAPI.Params.KlAkParams({})
        options.AddParams('KLRPT_OUTPUT_FORMAT', options_format )
        options.AddArray('KLRPT_LOC_PRODUCTS', [ KlAkOAPI.Params.paramParams(options_products) ])
        options.AddInt('RPT_LOC_LOCALE', 2057)
        options.AddParams('RPT_TIMEZONE_INFO', options_timezone)
        # generate a report with the proper ID and options
        strRequestId = oReportManager.ExecuteReportAsync(nReportId, options).OutPar('strRequestId')
        # check for result of an asynchronous action
        asyncActionStateChecker = KlAkOAPI.AsyncActionStateChecker.KlAkAsyncActionStateChecker (server)
        while True:
            res = asyncActionStateChecker.CheckActionState(strRequestId)
            bFinalized, bSuccededFinalized, lStateCode, pStateData, lNextCheckDelay = res.OutPar('bFinalized'), res.OutPar('bSuccededFinalized'), res.OutPar('lStateCode'), res.OutPar('pStateData'), res.OutPar('lNextCheckDelay')
            if bFinalized:
                if bSuccededFinalized:
                    # got asynchronous result - success
                    if not 'KLRPT_OUTPUT_FILE' in pStateData:
                        raise KlAkOAPI.Error.KlAkResponseError('Report was marked as generated successfully, but expected field KLRPT_OUTPUT_FILE is absent in response, nothing to download')
                    # create a folder for result
                    if not os.path.exists(strResultFolder):
                        os.makedirs(strResultFolder)
                    # download the resulting file
                    print ('Report generated successfully, ready to download')
                    file_name, file_ext = os.path.splitext(pStateData['KLRPT_OUTPUT_FILE'])
                    download_filename = os.path.join(strResultFolder, 'test' + file_ext)
                    server.DownloadFile(pStateData['KLRPT_OUTPUT_FILE'], download_filename)
                    # download charts if needed (report in the HTML format needs all images as separate files)
                    if 'KLRPT_OUTPUT_CHART' in pStateData:
                        chartpath = os.path.join(strResultFolder, os.path.basename(pStateData['KLRPT_OUTPUT_CHART']))
                        print('downloading', pStateData['KLRPT_OUTPUT_CHART'], 'to file', chartpath)
                        server.DownloadFile(pStateData['KLRPT_OUTPUT_CHART'], chartpath)
                        print('Chart is downloaded successfully')
                    # download logo if needed (report in the HTML format needs all images as separate files)
                    if 'KLRPT_OUTPUT_LOGO' in pStateData:
                        logopath = os.path.join(strResultFolder, os.path.basename(pStateData['KLRPT_OUTPUT_LOGO']))
                        print('downloading', pStateData['KLRPT_OUTPUT_LOGO'], 'to file', logopath)
                        server.DownloadFile(pStateData['KLRPT_OUTPUT_LOGO'], logopath)
                        print('Logo is downloaded successfully')
                    print ('Report is downloaded to:', download_filename)
                else:
                    # got asynchronous result - some error has occurred
                    err_description = KlAkOAPI.Params.KlAkParams(res.OutPar('pStateData'))
                    print('Cannot create a report:', err_description['GNRL_EA_DESCRIPTION'], '(error code ' + str(err_description['KLBLAG_ERROR_INFO']['KLBLAG_ERROR_CODE']) + ')')
                break
            else:
                # asynchronous result is not ready yet, need to wait for lNextCheckDelay milliseconds
                time.sleep(MillisecondsToSeconds(lNextCheckDelay))