Public API v2 → Schedule Dashboard Report Endpoint

About the /dashboards/{dashboardGuid}/send-report endpoint

The /dashboards/{dashboardGuid}/send-report endpoint creates and triggers a scheduler job for sending a dashboard report. Only the dashboard owner or a user with access rights to it can use the /dashboards/{dashboardGuid}/send-report endpoint to send the dashboard report.

For information about how to get started with Public API v2, refer to References → Public API v2.

Note

You must use the HTTPS scheme to be able to successfully run the API endpoints. Additionally, you must specify the tenant name (case-sensitive) in the endpoint request URL starting with the 2023.7.0 release.

Important

The Cluster Management Console (CMC) admin must define the email settings in the tenant configurations to allow the job to send the report.

Request URL

https://<cluster_URL>/incorta/api/v2/{tenantName}/dashboards/{dashboardGuid}/send-report

Request URL Parameters

Field name	Description	Type	Required
tenantName	The tenant name (case-sensitive)	String	Required starting with 2023.7.0
dashboardGuid	The GUID of the dashboard you want to send. Example: `79abe0db-67y6-4830-a9a7-2099x24b6541` Note: You can find this GUID either in the metadata database or the address bar when you open the dashboard.	String	Required

HTTP method

POST

Request headers

{
"Content-Type": "application/json",
"Accept": "application/json",
"Authorization": "Bearer {access_token}"
}

You must use a valid access token of the dashboard owner or a user with access rights to it.

For information about how to create an access token, refer to Public API v2 → Create an API access token.

Request body

{
  "toExternalEmails": ["string"],
  "toUsersNames": ["string"],
  "toGroupNames": ["string"],
  "bccExternalEmails": ["string"],
  "bccUsersNames": ["string"],
  "bccGroupsNames": ["string"],
  "ccExternalEmails": ["string"],
  "ccUsersNames": ["string"],
  "ccGroupsNames": ["string"],
  "subject": "string",
  "body": "string",
  "hideTemplate": boolean,
  "useHTMLBody": boolean,
  "appendTimestamp": boolean,
  "bursting": boolean,
  "outputFormat": "string"
}

Request body parameters

The following table describes the request body parameters in the /dashboards/{dashboardGuid}/send-report endpoint.

Parameter	Type	Description	Required	Values
outputFormat	String	The format of the dashboard report you want to send	Required	● `html` ● `csv` ● `pdf` ● `xlsx` Example: `"pdf"`
toExternalEmails	Array of string values	List of external emails that will receive the scheduled dashboard report	Optional	Valid email addresses separated by commas. Example: `["abc@mail.com", "def@mail.com"]`
toUsersNames	Array of string values	List of users that will receive the scheduled dashboard report	Optional	User names, as defined in Incorta, separated by commas. Example: `["user1", "user2"]`
toGroupNames	Array of string values	List of groups that will receive the scheduled dashboard report	Optional	Group names, as defined in Incorta, separated by commas. Example: `["HrGroup", "Analyzers"]`
bccExternalEmails	Array of string values	List of external emails that will receive the scheduled dashboard report as a blind carbon copy	Optional
bccUsersNames	Array of string values	List of users that will receive the scheduled dashboard report as a blind carbon copy	Optional
bccGroupsNames	Array of string values	List of groups that will receive the scheduled dashboard report as a blind carbon copy	Optional
ccExternalEmails	Array of string values	List of external emails (external recipients) that will receive the scheduled dashboard report as a carbon copy	Optional
ccUsersNames	Array of string values	List of users that will receive the scheduled dashboard report as a carbon copy	Optional
ccGroupsNames	Array of string values	List of groups that will receive the scheduled dashboard report as a carbon copy	Optional
bursting*	Boolean	Specify if you want to enable the bursting option to send the dashboard according to the security context of the recipient	Optional	● `true` ● `false` (default)
appendTimestamp	Boolean	Specify if you want to append the time of sending the report to the file name	Optional	● `true` (default) ● `false`
useHTMLBody	Boolean	Specify if you want to use HTML email body instead of plain text. You must use inline CSS styles only. Write the email body in the form of `<div> content </div>`	Optional	● `true` ● `false` (default)
hideTemplate	Boolean	Specify if you want to hide the default email	Optional	● `true` ● `false` (default)
body	String	The body of the sent mail	Optional
subject	String	The subject of the sent mail	Optional

*Bursting reports

You can’t send a bursting dashboard report to external recipients or to internal recipients as a carbon copy (CC) or a blind carbon copy (BCC). Therefore, if you set the bursting option to true, don’t add any value to the CC or BCC parameters, such as ccGroupsNames, or the external recipients.

Request body example

{
  "toExternalEmails": ["customer@external.com"],
  "toUsersNames": ["user1", "user2"],
  "toGroupNames": ["finance", "sales"],
  "bccExternalEmails": [""],
  "bccUsersNames": [""],
  "bccGroupsNames": [""],
  "ccExternalEmails": ["ceo@company.com"],
  "ccUsersNames": [""],
  "ccGroupsNames": [""],
  "subject": "Q1 Revenue Report ",
  "body": "<div>Hello, <br />Kindly check the <b>Q1 revenue report</b>. <br /> Thanks,</div>",
  "hideTemplate": false,
  "useHTMLBody": true,
  "appendTimestamp": true,
  "bursting": false,
  "outputFormat": "pdf"
}

Endpoint response

The following table shows the HTTP response status codes for this endpoint.

Code	Description	Payload Response
201	Created The endpoint created the scheduled job to send the dashboard report	The response contains the ID and name of the created job. `{"jobId": 0,"jobName": "string"}` Example: `{"jobId": 924, "jobName": "Public API triggered Job_16722303645"}`
400	Bad Request You set the bursting property to `true` while adding values to the external recipients or CC groups.	`{"message": "string"}` Example: `{"message": "INC_05070000: Only toUsersNames and toGroupsNames are allowed as bursting reports recipients."}`
401	Unauthorized The tenant name doesn’t match the tenant in the access token.	`{"message": "string"}`
422	Unprocessable Entity You provided invalid values, such as invalid email addresses or output format.	`{"message": "string"}` Example `{"errorMessages":[{"message": "INC_01210000: bccExternalEmails Following emails are invalid: abc@"},{"message": "INC_01210000: outputFormat must match \"html\\|csv\\|pdf\\|xlsx\""}]}`
403	Forbidden The endpoint couldn’t create the scheduled job due to authentication errors, such as an invalid or expired access token, or you don’t have access rights to the dashboard.	`{"message": "string"}` Example `{"INC_02010000: You are not authorized to VIEW the Demo DASHBOARD of ID [758]."}`
404	Not Found ● The endpoint couldn’t find the dashboard you provided its GUID. ● The tenant doesn't exist or is disabled.	`{"message": "string"}` Example: `{"message": "INC_05111201: The [ab642c0-c086-4xa9-9fb9-d4c75e4613c7] DASHBOARD cannot be found."}`
500	Internal Server Error The endpoint couldn’t create the scheduled job due to a server error.	`{"message": "string"}`

Content