Creating a Client Application Using the Asynchronous Analytical Reporting API

Use this procedure to create a client application using the asynchronous analytical reporting API. Choose the asynchronous usage for larger projects.

Context

Follow these steps to create a client application using the asynchronous Analytical reporting API.

Procedure

For the first page of results, follow these steps:

  1. Choose a view template. If necessary, you can browse existing view templates using the GET /viewTemplates endpoint of the Analytical Reporting - View Management API.
    GET {{runtime_url}}/viewTemplates?realm={realm}&product=analytics
                   
  2. Optional. You can find out how many records will be included in the results set for a query using the specified view template and filters using the GET /views/{viewTemplateName}/count endpoint of the Analytical Reporting - Synchronous API.
    GET {{runtime_url}}/views/{template_name}/count?realm={realm}&filters={filter_list}
                   
    The response includes the following fields:
    count
    The total number of records that would be included in the results set using the specified view template and filters.
    MaxRecordsInEachPage
    The maximum number of records that can be returned in a single page of results. Note that a page might contain fewer records that this maximum.
    TotalPages
    The total number of pages in the results set.
  3. Post the initial request to the jobs queue, using the POST /jobs endpoint of the Analytical Reporting - Job Submission API, specifying the desired view and request ID.
    POST {{runtime_url}}/jobs?realm={realm}
    					
    Request body:{
    	"viewTemplateName":"ChosenViewName",
    	"filters":{filter_list},
    	"requestID":"myRequestID"
    }
    The response includes the following fields:
    requestID
    The request ID you specified in the requestID parameter.
    jobID
    A system-generated job ID.
  4. Request the status of your job using the GET /jobs/{jobId} endpoint of the Analytical Reporting - Job Results API. This request returns the job status.
    GET {{runtime_url}}/jobs/{job_id}?realm={realm}
                   
    This returns the job status, which can be one of the following:
    • In progress

    • Failed

    • Successful

    • Expired

    When the status is Successful, the job is complete, and output is batched into files. The response body includes the following fields:
    files
    A list of file IDs for the first page of files in your results set. Use these as the value of the fileID parameter in queries to download each file.
    pageToken
    A token you can pass as the value of the pageToken parameter in a subsequent query to request the next page of results.
    requestID
    The request ID you specified in the requestID parameter when you posted this job.
    TotalNumOfRecords
    The approximate total number of records in the response set, including records in the current response and all other responses that belong to the current results set.
    CurrentPageRecordsCount
    The number of records included in the current page.
    TotalNumOfPages
    The total number of pages associated with the current results set.
    CurrentPageNum
    The number of the current page in the sequence of pages associated with the current results set. The response to the initial POST /jobs query is 1.
    TotalNumOfFiles
    Records are returned in the form of links to ZIP files, with each ZIP file containing up to the maximum permitted number of records. This field indicates the total number of ZIP file links in the results set.
    FilesInCurrentPage
    This field indicates the total number of ZIP file links in the current page.
  5. Request files one at a time using the GET /jobs/{jobId}/files/{fileId} endpoint of the Analytical Reporting - Job Results API.
    GET {{runtime_url}}/jobs/{job_id}/files/{file_id}?realm={realm}
                   
    Files are returned in ZIP format. Repeat this step for all desired file IDs.

For subsequent pages, follow these steps:

  1. Post the request for the next page of results to the jobs queue, using the POST /jobs endpoint of the Analytical Reporting - Job Submission API, adding the page token returned in the response to the previous GET /jobs/{jobID} query:
    POST {{runtime_url}}/jobs?pageToken={pageToken}&realm={realm}
    
    Request body:{
    		"viewTemplateName":"ChosenViewName",
    		"filters":{filter_list},
    		"requestID":"myRequestID"
    		}
    					
  2. Request the status of your job, using the GET /jobs/{jobID} of the Analytical Reporting - Job Results API:
    GET {{runtime_url}}/jobs/{jobID}?realm={realm}
                   
    The response includes the file IDs for the specified page in the files block, and the page token for the next page of results in the pageToken field.
  3. Request files one at a time using the /jobs/{jobId}/files/{fileId} endpoint of the Analytical Reporting - Job Results API:
    GET {{runtime_url}}/jobs/{jobID}/files/{fileID}?realm={realm}
                   
    Repeat this step for all desired file IDs.
  4. Repeat this procedure until you reach the final page of results. When you reach the last page of results, the value of the pageToken field returned by the GET /jobs/{jobID} query is NULL because there are no subsequent pages in the response set.

Results

You can extract retrieved files and process the data as desired. Extraction and data processing are not executed using the APIs.