Generate Report

Reports are generated via calls to /api/reports/{id}.

Calls to generate a report require the "Write|ReportRecord" permission as well as the Reporting license sku. The calling user also must have "Read|Report" permission for that report, as well as permissions for ALL the underlying data being pulled into the report by the reporting engine.

If a Report has the Roles enumeration populated, the calling user must either have "Read|Report - All" or "Read|Report" and also be in one of the enumerated roles assigned for the report.

NOTE: A ReportRecord is a temporary cache object representing the generated report data. a Report object represents report settings.

Caching and Scoping

Report data is cached per tenant. If a user is accessing the report is a member of a security role that has scoped data permissions (meaning limited attribute access, or rule based horizontal scoping) then the report will be cached for that individual user. This prevents a user with limited permissions from being served a report generated by a more privileged user.

Reports delivered via schedules or workflows are generated by Panel Service, meaning full read permissions are applied and the data is NOT e.g. filtered based on intended email recipient. 

Performance

Reports can pull large data sets (up to 200,000 objects, 600,000 joins, and 5,000,000 table cells, by default), so caching prevents multiple calls from consuming excessive resources. Because a report may take longer to generate than the Azure Front Door timeout the API call will return progress results until the report is ready. It may be necessary to poll the API with the same query until a completed report is available. If the report is still building the API will return a result with status code 206 (Partial Content) 

Query Parameters

• id: path parameter giving GUID id of the report to build
• set-now: Requests to the reporting engine can specific a timestamp value in ISO 8601 format to build the report using a constructed point-in-time view of the underlying data. This approach takes more time to build the report as Identity Panel must modify queries and returned object to simulate a past timestamp
• sort: defaults to sort field in report definition, Set to field or -field to sort report results. NOTE: sort operations are performed on a cached report object so resorting does not require rebuilding the report
• limit: default 10, page report data
• skip: default 0, page report data
• file: name, will set Content-Disposition attachment; filename=slug(name).(ext) based on the provided name and requested content type
• Report Parameters: Many reports accept parameter values. Parameter names are passed as a URL slug value (which may be generated using the javascript slugify helper method, e.g. slugify('Parameter Name') => 'parameter-name'. Values should be data URI encoded. If a data value is wrapped in encoded square braces, the value will be treated as a rule engine value. e.g. [special.Identity Silo.MIM: Metaverse] will return the string converted Guid identifying the MIM: Metaverse Silo.

Returned Result

This API returns a ReportResult. 

ReportResult uses ICustomSerializer to support media type negotiation via the Content-Type and Accepts headers. Report Result supports the following types:

• text/plain: returns tab-delimited plain text table format
• text/xml: returns structured XML text data
• application/vnd.ms-excel: returns Excel XLSX xml data
• text/html: returns an HTML document containing embedded CSS and HTML table for report display, e.g. in an email body

Only application/json and application/bson will return the following full report with metadata. The above types return only the report contents.

{
  "Name": "Report Name",
  "Description": "Report description, if defined",
  "Generated": "ISO 8601 timestamp, allows user to see if cached report was used",
  "Id": "Guid Id of report definition",
  "ReportId": "Constructed Id of cached record",
  "Complete": true|false,
  "Truncated": true|false, // indicates if object limits truncated report data
  "PointInTime": "ISO 8601 timestamp"|null, // set if set-now parameter was used
  "SortField": "Field name"|null, // set if report had a sort column
  "SortDirection": "Ascending|Descending",
  "Count": ##, // number of rows in report
  "Data": [
    { "Field": Value | StyledValue, ... }
  ],
  "Progress" : [
    "list of steps in report build process",
    "partial list will be populated for an incomplete report"
  ]
}

Value:

A report value will be a JSON value (string, number, null, boolean) or an array of JSON values (for fields with a list of values)

StyledValue:

If a report definition specifies style rules the following value structure is returned:

{
  "S": "report style names",
  "V": Value
}

The reporting engine supports the following styles (expressed in JSON, BSON, XML, HTML, and Excel formats):

• s: bold/strong
• e: italic/emphasis
• h: hide (sets display:none for the value)
• Colors (prefix with t to color the text instead of the cell background)
  
  • r: red
  • o: orange
  • y: yellow
  • g: green
  • b: blue
  • p: purple