dashboards

Creates, updates, deletes, gets or lists a dashboards resource.

Overview

Name	dashboards
Type	Resource
Id	aws.cloudtrail.dashboards

Fields

The following fields are returned by SELECT queries:

get_dashboard

Name	Datatype	Description
created_timestamp	string (date-time)	The timestamp that shows when the dashboard was created.
dashboard_arn	string	The ARN for the dashboard. (pattern: <code>^[a-zA-Z0-9._/-:]+$</code>)
last_refresh_failure_reason	string	Provides information about failures for the last scheduled refresh. (pattern: <code>.*</code>)
last_refresh_id	string	The ID of the last dashboard refresh. (pattern: <code>\d+</code>)
refresh_schedule	object	The refresh schedule for the dashboard, if configured.
status	string	The status of the dashboard. (CREATING, CREATED, UPDATING, UPDATED, DELETING)
termination_protection_enabled	boolean	Indicates whether termination protection is enabled for the dashboard.
type	string	The type of dashboard. (MANAGED, CUSTOM)
updated_timestamp	string (date-time)	The timestamp that shows when the dashboard was last updated.
widgets	array	An array of widgets for the dashboard.

list_dashboards

Name	Datatype	Description
dashboards	array	Contains information about dashboards in the account, in the current Region that match the applied filters.
next_token	string	A token you can use to get the next page of dashboard results. (pattern: <code>.*</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_dashboard	select	region		Returns the specified dashboard.
list_dashboards	select	region		Returns information about all dashboards in the account, in the current Region.
create_dashboard	insert	region		Creates a custom dashboard or the Highlights dashboard. Custom dashboards - Custom dashboards allow you to query events in any event data store type. You can add up to 10 widgets to a custom dashboard. You can manually refresh a custom dashboard, or you can set a refresh schedule. Highlights dashboard - You can create the Highlights dashboard to see a summary of key user activities and API usage across all your event data stores. CloudTrail Lake manages the Highlights dashboard and refreshes the dashboard every 6 hours. To create the Highlights dashboard, you must set and enable a refresh schedule. CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the CloudTrail User Guide. To set a refresh schedule, CloudTrail must be granted permissions to run the StartDashboardRefresh operation to refresh the dashboard on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to the dashboard. For more information, see Resource-based policy example for a dashboard in the CloudTrail User Guide. For more information about dashboards, see CloudTrail Lake dashboards in the CloudTrail User Guide.
update_dashboard	update	region, DashboardId		Updates the specified dashboard. To set a refresh schedule, CloudTrail must be granted permissions to run the StartDashboardRefresh operation to refresh the dashboard on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to the dashboard. For more information, see Resource-based policy example for a dashboard in the CloudTrail User Guide. CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the CloudTrail User Guide.
delete_dashboard	delete	region		Deletes the specified dashboard. You cannot delete a dashboard that has termination protection enabled.
start_dashboard_refresh	exec	region, DashboardId		Starts a refresh of the specified dashboard. Each time a dashboard is refreshed, CloudTrail runs queries to populate the dashboard's widgets. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the CloudTrail User Guide.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

get_dashboard

Returns the specified dashboard.

SELECT
created_timestamp,
dashboard_arn,
last_refresh_failure_reason,
last_refresh_id,
refresh_schedule,
status,
termination_protection_enabled,
type,
updated_timestamp,
widgets
FROM aws.cloudtrail.dashboards
WHERE region = '{{ region }}' -- required
;

list_dashboards

Returns information about all dashboards in the account, in the current Region.

SELECT
dashboards,
next_token
FROM aws.cloudtrail.dashboards
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_dashboard

Creates a custom dashboard or the Highlights dashboard. Custom dashboards - Custom dashboards allow you to query events in any event data store type. You can add up to 10 widgets to a custom dashboard. You can manually refresh a custom dashboard, or you can set a refresh schedule. Highlights dashboard - You can create the Highlights dashboard to see a summary of key user activities and API usage across all your event data stores. CloudTrail Lake manages the Highlights dashboard and refreshes the dashboard every 6 hours. To create the Highlights dashboard, you must set and enable a refresh schedule. CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the CloudTrail User Guide. To set a refresh schedule, CloudTrail must be granted permissions to run the StartDashboardRefresh operation to refresh the dashboard on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to the dashboard. For more information, see Resource-based policy example for a dashboard in the CloudTrail User Guide. For more information about dashboards, see CloudTrail Lake dashboards in the CloudTrail User Guide.

INSERT INTO aws.cloudtrail.dashboards (
Name,
RefreshSchedule,
TagsList,
TerminationProtectionEnabled,
Widgets,
region
)
SELECT 
'{{ Name }}',
'{{ RefreshSchedule }}',
'{{ TagsList }}',
{{ TerminationProtectionEnabled }},
'{{ Widgets }}',
'{{ region }}'
RETURNING
dashboard_arn,
name,
refresh_schedule,
tags_list,
termination_protection_enabled,
type,
widgets
;

Manifest

# Description fields are for documentation purposes
- name: dashboards
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the dashboards resource.
  - name: Name
    value: "{{ Name }}"
    description: |
      The name of the dashboard. The name must be unique to your account. To create the Highlights dashboard, the name must be AWSCloudTrail-Highlights.
  - name: RefreshSchedule
    description: |
      The refresh schedule configuration for the dashboard. To create the Highlights dashboard, you must set a refresh schedule and set the Status to ENABLED. The Unit for the refresh schedule must be HOURS and the Value must be 6.
    value:
      Frequency:
        Unit: "{{ Unit }}"
        Value: {{ Value }}
      Status: "{{ Status }}"
      TimeOfDay: "{{ TimeOfDay }}"
  - name: TagsList
    description: |
      A list of tags.
    value:
      - Key: "{{ Key }}"
        Value: "{{ Value }}"
  - name: TerminationProtectionEnabled
    value: {{ TerminationProtectionEnabled }}
    description: |
      Specifies whether termination protection is enabled for the dashboard. If termination protection is enabled, you cannot delete the dashboard until termination protection is disabled.
  - name: Widgets
    description: |
      An array of widgets for a custom dashboard. A custom dashboard can have a maximum of ten widgets. You do not need to specify widgets for the Highlights dashboard.
    value:
      - QueryStatement: "{{ QueryStatement }}"
        QueryParameters: "{{ QueryParameters }}"
        ViewProperties: "{{ ViewProperties }}"

UPDATE examples

update_dashboard

Updates the specified dashboard. To set a refresh schedule, CloudTrail must be granted permissions to run the StartDashboardRefresh operation to refresh the dashboard on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to the dashboard. For more information, see Resource-based policy example for a dashboard in the CloudTrail User Guide. CloudTrail runs queries to populate the dashboard's widgets during a manual or scheduled refresh. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the CloudTrail User Guide.

UPDATE aws.cloudtrail.dashboards
SET 
DashboardId = '{{ DashboardId }}',
Widgets = '{{ Widgets }}',
RefreshSchedule = '{{ RefreshSchedule }}',
TerminationProtectionEnabled = {{ TerminationProtectionEnabled }}
WHERE 
region = '{{ region }}' --required
AND DashboardId = '{{ DashboardId }}' --required
RETURNING
created_timestamp,
dashboard_arn,
name,
refresh_schedule,
termination_protection_enabled,
type,
updated_timestamp,
widgets;

DELETE examples

delete_dashboard

Deletes the specified dashboard. You cannot delete a dashboard that has termination protection enabled.

DELETE FROM aws.cloudtrail.dashboards
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

start_dashboard_refresh

Starts a refresh of the specified dashboard. Each time a dashboard is refreshed, CloudTrail runs queries to populate the dashboard's widgets. CloudTrail must be granted permissions to run the StartQuery operation on your behalf. To provide permissions, run the PutResourcePolicy operation to attach a resource-based policy to each event data store. For more information, see Example: Allow CloudTrail to run queries to populate a dashboard in the CloudTrail User Guide.

EXEC aws.cloudtrail.dashboards.start_dashboard_refresh 
@region='{{ region }}' --required 
@@json=
'{
"DashboardId": "{{ DashboardId }}", 
"QueryParameterValues": "{{ QueryParameterValues }}"
}'
;