Grafana

1. Overview

Grafana is a leading open-source platform for monitoring, data visualization, and observability. It allows you to query, visualize, alert on, and explore your metrics, logs, and traces no matter where they are stored.

With the GoInsight Grafana node, you can seamlessly integrate Grafana administration into your automated workflows. This allows you to programmatically manage key resources within your Grafana instance, including:

• Dashboard Management: Create, retrieve, update, and delete dashboards.
• Team and User Administration: Build and manage teams, add or remove members, and handle user accounts.
• Data Retrieval: Fetch lists of dashboards, teams, and users to use in subsequent workflow steps.

2. Prerequisites

Before using this node, you must have a valid Grafana account with the necessary permissions to generate API keys. Depending on the operations you wish to perform, the API key may require Viewer, Editor, or Admin privileges.

3. Credentials

For a detailed guide on how to obtain and configure credentials, please refer to our official documentation: Credentials Configuration Guide.

4. Supported Operations

Summary

This node provides a comprehensive set of operations for managing Dashboards, Teams, Team Members, and Users within your Grafana instance.

Operation Details

Add a Team Member

Adds a user to a team in Grafana

Input Parameters:

• TeamId: The ID of the team to add member to
• UserId: The ID of the user to add to the team

Output:

• Added (bool): Indicates whether the adding member was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Dashboard

Creates a dashboard in Grafana

Input Parameters:

• Dashboard: The dashboard definition to create.

Options:

• Overwrited: Indicates whether to overwrite an existing dashboard with the same title. Defaults to False.

Output:

• Dashboard (object): Dictionary containing the created dashboard information.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Create a Team

Creates a team in Grafana

Input Parameters:

• Name: The name of the team to create.
• Email: The email of the team to create.

Output:

• Team (object): Team data created.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Dashboard

Deletes a dashboard from Grafana

Input Parameters:

• Uid: The UID of the dashboard to delete

Output:

• Deleted (bool): Indicates whether the deletion was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a Team

Deletes a team from Grafana

Options:

• TeamId: The ID of the team to delete

Output:

• Deleted (bool): Indicates whether the deletion was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Delete a User

Deletes a user from Grafana

Input Parameters:

• UserId: The ID of the user to delete from the organization.

Output:

• Deleted (bool): Indicates whether the deletion was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Dashboards

Gets all dashboards from Grafana with optional filtering

Options:

• Query: Query string to filter dashboard by title.
• PerPage: Number of dashboards per page. Defaults to 1000.
• Page: Page number to retrieve. Defaults to 1.

Output:

• Dashboards (object-array): Dashboard data retrieved from Grafana.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Team Members

Gets all members of a team from Grafana

Options:

• TeamId: The ID of the team to get members for

Output:

• Members (object-array): Team members data retrieved from Grafana.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Teams

Gets all teams from Grafana with optional filtering

Options:

• Name: The name parameter returns a single team if the parameter matches the name field.
• Query: The query parameter is optional and it will return results where the query value is contained in the name field.
• Sort: Sort options: name-asc, name-desc, email-asc, email-desc, memberCount-asc, memberCount-desc
• PerPage: Number of teams per page (1-1000)
• Page: Page number to retrieve

Output:

• Teams (object-array): Team data retrieved from Grafana.
• StatusCode (number): data retrieved from Grafana. HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get Many Users

Gets all users from Grafana with optional filtering

Options:

• Query: Query string to filter users by login, email or name.

Output:

• Users (object-array): User datas retrieved from Grafana.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Dashboard

Gets a specific dashboard from Grafana

Input Parameters:

• Uid: The UID of the dashboard to retrieve

Output:

• Dashboard (object): Dashboard data retrieved from Grafana.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Get a Team

Gets a specific team from Grafana

Input Parameters:

• TeamId: The ID of the team to retrieve.

Output:

• Team (object): Team data retrieved from Grafana.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Remove a Team Member

Removes a user from a team in Grafana

Input Parameters:

• TeamId: The ID of the team to remove member from
• UserId: The ID of the user to remove from the team.

Output:

• Removed (bool): Indicates whether the removal was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Dashboard

Updates a dashboard in Grafana

Input Parameters:

• Dashboard: The dashboard definition to update.

Output:

• Updated (bool): Indicates whether the update was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a Team

Updates a team in Grafana

Input Parameters:

• TeamId: The ID of the team to update
• Name: The new name of the team.
• Email: The new email of the team.

Output:

• Updated (bool): Indicates whether the update was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

Update a User

Updates a user in Grafana

Input Parameters:

• UserId: The ID of the user to update in the organization.
• Role: The new role for the user (Viewer, Editor, Admin).

Output:

• Updated (bool): Indicates whether the update was successful.
• StatusCode (number): HTTP status code or operation status code (-1 for parameter error, 500 for exceptions).
• ErrorMessage (string): Error message description, returns empty string on success.

5. Example Usage

This section will guide you through creating a simple workflow to create a new team in your Grafana instance.

The workflow will consist of three nodes: Start -> Grafana: Create a Team -> Answer.

1. Add the Grafana Node

• On the workflow canvas, click the + button to add a new node.
• In the panel that appears, select the "Tools" tab.
• Find and select "Grafana" from the list of tools.
• From the list of supported operations for Grafana, click on "Create a Team" to add the node to the canvas.

2. Configure the Node

• Click on the newly added "Create a Team" node to open its configuration panel on the right.
• Credentials: Find the credentials field at the top. Click the dropdown menu and select your pre-configured Grafana credential.
• Parameters: Fill in the required input parameters for the operation.
  • Name: Enter the desired name for your new team, for example, Marketing Analytics.
  • Email: Provide a contact or group email for the team, such as marketing-analytics@example.com.

3. Run and Validate

• Once all required parameters are correctly filled, any error indicators on the workflow canvas should disappear.
• Click the "Run" button in the top-right corner of the canvas to execute the workflow.
• After a successful execution, you can click the log icon in the top-right corner to view the detailed inputs and outputs of the node, confirming that the team was created successfully.

After completing these steps, your workflow is fully configured. When you run it, a new team will be created in your Grafana organization.

6. FAQs

Q: Why am I getting a 401 Unauthorized or 403 Forbidden error?

A: This typically indicates an issue with your API key or its permissions. Please check the following:

• Valid API Key: Ensure the API key used in your credential is correct and has not expired or been revoked in Grafana.
• Correct Role: The API key must have a role with sufficient permissions for the operation you are trying to perform (e.g., you need an Admin role to delete users or teams).
• Instance URL: Verify that the Grafana URL in your credential configuration is correct and accessible.

Q: How do I find the TeamId or UserId needed for some operations?

A: You can typically find these IDs in a couple of ways:

• Grafana UI: When you navigate to a team's or user's settings page in the Grafana web interface, the ID is often visible in the URL.
• GoInsight Workflow: Use the Get Many Teams or Get Many Users operations in a preceding step of your workflow. These operations will return a list of objects, each containing the name and ID, which you can then use as input for other nodes.

Q: What is the format for the Dashboard object when creating or updating a dashboard?

A: The Dashboard parameter expects a JSON object that represents the complete Grafana dashboard model. This includes properties like title, panels, templating, time, etc. The easiest way to get a valid structure is to export an existing dashboard from the Grafana UI as JSON and use that as a template. For detailed specifications, refer to the official Grafana documentation on the dashboard JSON model.

7. Official Documentation

For more in-depth information about the Grafana API and its capabilities, please refer to the Grafana Official API Documentation.