diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..cb68e08 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,52 @@ +# Contributing to SquaredUp Community Plugins + +First off, thanks for taking the time to contribute! :+1: + +SquaredUp actively encourages external contributions so that the project can develop in such a way that benefits the wider SquaredUp community. + +As a contributor, here are the guidelines we would like you to follow: + +* [Code of Conduct](#coc) +* [Question or Problem?](#question) +* [Found a problem?](#problem) +* [Suggest a feature?](#request) +* [Contributing enhancements and plugins](#contribute) +* [Submission Guidelines](#submit) + + +## Code of Conduct + +Help us keep SquaredUp Samples open and inclusive. +Please read and follow our [Code of Conduct](CODE_OF_CONDUCT.md). + +## Got a question? + +Please do not open issues for general support questions as we want to keep GitHub issues for bug reports and requests. + +Please use [SquaredUp Community Answers](https://community.squaredup.com) to ask questions. The forums provide + +* direct access to many people with extensive experience with SquaredUp +* public viewing so your question and its answer can help someone else +* central location where you and others can search for previously asked questions and answers + +## Found a problem? +If you find a bug or a problem, you can help us by: + +* [Submit an support ticket](https://docs.squaredup.com/submit-ticket) with as much information as possible. +* Even better, create a Pull Request with a fix! + +## Suggesting features and ideas +Is there a plugin you need, but aren't able to develop? Does a plugin need an enhancement? Then [submit a feedback](https://feedback.squaredup.com/plugins), please provide lots of details to help us build it! + +## Contributing enhancements and plugins +If there is an enhancement you want to make to an existing plugin or a cool new plugin you want to contribute then please submit a Pull Request with your work. + +### Submitting a Pull Request (PR) +Before you submit your Pull Request (PR) consider the following guidelines: + +1. Search [GitHub](pulls) for an open or closed PR that relates to your submission. You don't want to duplicate effort. +2. Read the [documentation](README.md) and explore the existing plugins for best practice guidance. +3. For creating pull requests see - [Creating a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) +4. Make sure you pull request is appropriately described, and contains all the required files and documentation for review. + +That's it, thank you for your contribution! :+1: diff --git a/README.md b/README.md index 67e1275..162304d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -# SquaredUp Plugin Repository +# SquaredUp Community Plugins Repository -This repository contains third-party/community plugins for the SquaredUp Observability Portal product. +This repository contains third-party/community plugins for [SquaredUp](https://squaredup.com). ## License @@ -12,26 +12,19 @@ Please read and adhere to our [Code of Conduct](./CODE_OF_CONDUCT.md) document b ## Introduction -This repository is a read-only copy of the documentation and test tools inside SquaredUp's main plugins repository. This contains the -information you will need to understand the process involved in developing a plugin for the SquaredUp Observability Portal product. -It contains tooling for you to make a start on developing a plugin. However, in order actually to install a plugin into the SquareUp -product, you will need to engage with SquaredUp by emailing hello@squaredup.com. +Plugins are vital components of SquaredUp. Each plugin bundles up everything involved in the interaction with a specific third party system, namely: -SquaredUp Cloud plugins are vital components of the SquaredUp Unified Observability Portal product. Each -plugin bundles up everything involved in the interaction with a specific third party system, namely: - -- The ability to import objects from an external system into the Observability Portal's Data Mesh. +- The ability to import objects from an external system into SquaredUp. - The ability to read data upon demand from an external system for displaying in dashboards and/or for use in the evaluation of monitors. -Plugins are installed into the Observability Portal product as part of the product build process managed by SquaredUp. Once installed, they appear within the Data Source Gallery in the product: +Plugins are installed into SquaredUp as part of the product build process. Once installed, they appear within the Data Source List in the product: -![DataSourceGallery](docs/images/DataSourceGallery.jpg) +![DataSourceList](docs/images/DataSourceGallery.jpg) ## Execution Environments -A plugin may be executed in a cloud environment as part of the Observability Portal product or on a machine within a customer's premises (upon which the customer has installed a Relay Agent). If both environments are equally suitable for a plugin, it can -be declared as "hybrid" (in which case, two separate plugins will appear in the Data Source Gallery, one with the suffix -" On-Premise" automatically added). +A plugin may be executed within SquaredUp's SaaS environment or on a machine within a customer's premises (upon which the customer has installed a Relay Agent). If both environments are equally suitable for a plugin, it can +be declared as "hybrid" (in which case, two separate plugins will appear in the Data Source list, one with the label "On-Prem" added). Javascript (NodeJS) is currently the implementation language/runtime with fullest capability, but PowerShell may be chosen for plugins which will only run On-Premise. We plan to support support other languages at some point in the future. @@ -46,22 +39,52 @@ A plugin is a directory in this repo of the form `plugins/`_plugin-name_`/v1` co - `metadata.json` - a file containing high-level information about the plugin (for example: the execution location of the plugin, or the information that appears in the Data Source Gallery, above). - `ui.json` - a file describing the configuration that must be shown to a user who is in the process of adding the plugin to their tenant to connect with an instance of the back end system. - `custom_types.json` (Optional) - a file containing information about non-standard object types that will be imported by the plugin into the Data Mesh. -- `data_streams.json` - a file describing the streams of on demand data that the Observability Portal can request of the plugin. +- `data_streams.json` - a file describing the streams of on demand data that SquaredUp can request of the plugin. - `handler.js` and `package.json` the executable code of the plugin. -## How to write a plugin - -The suggested way to write a new plugin is to make a copy of the `examplePlugins/hybrid/v1` directory in your `plugins/`_plugin-name_`/v1` directory and then tailor the configuration and code to interact with the specific back end as required. - -This process is described in more detail in [Writing a New Plugin](docs/writingANewPlugin.md). - -## Testing your plugin - -There are 2 main ways to test your plugin: - -1. Using the SquaredUp Test/Validation Script (`validate.js` at the root of this repo) -2. Testing within the SquaredUp Unified Observability Portal product. You would need to engage with SquaredUp to gain access to the private plugins repository before this means of testing is available to you. Contact hello@squaredup.com for more details. - -You should aim to do as much testing as possible with the `validate.js` script as the turn-around time is much quicker. - -This process is described in more detail in [Testing a Plugin](docs/testingAPlugin.md). +## Writing a Plugin + +1. **Clone the Repository:** + First, clone the repository to your local machine: + ```bash + git clone https://github.com/squaredup/squaredup-plugin-public.git + cd squaredup-plugin-public + ``` +2. **Create a New Branch:** + You will need to create a new branch for your changes: + ```bash + git checkout -b add-new-plugin # Replace Branch Name + ``` +3. **Creating the Plugin Folder:** + The suggested way to write a new plugin is to make a copy of the `examplePlugins/hybrid/v1` directory in your `plugins/`_plugin-name_`/v1` directory. + ```bash + # Replace 'ExamplePlugin' with your plugin name + mkdir -p 'plugins/ExamplePlugin/v1' + cp -r 'examplePlugins/hybrid/v1/*' 'plugins/ExamplePlugin/v1/' + ``` +4. **Tailoring the Example Plugin:** + You will need to tailor the configuration and code to interact with the specific back end as Required. + This process is described in more detail in [Writing a New Plugin](docs/writingANewPlugin.md). +5. **Testing the Plugin:** There are two main ways to test your plugin. + 1. Using the SquaredUp Test/Validation Script (`validate.js` at the root of this repo): + ```bash + npm ci + npm run validate + ``` + 2. Using the SquaredUp Unit Test Framework which can be executed by running: + ```bash + npm ci + # Replace 'ExamplePlugin' with your plugin name + npm test -- --pluginName="ExamplePlugin" --pluginPath="plugins/ExamplePlugin/v1" + ``` + You should aim to do as much testing as possible with the `validate.js` script as the turn-around time is much quicker. + This process is described in more detail in [Testing a Plugin](docs/testingAPlugin.md). +6. **Installation** + The plugin is only installed when a Pull Request has been submitted. During PR creation you will be + asked for your Tenant (Organization) Name which can be retrieved from the [settings page](https://app.squaredup.com/settings/organization). + This will be used for restricting the plugin to the specified tenant only. + Once the PR is approved and merged, the plugin will be available for everyone. + +## Contributing + +We greatly appreciate your interest in contributing to this repository! To help you get started, please take a look at our detailed contribution guidelines in the [CONTRIBUTING](CONTRIBUTING.md) document. diff --git a/docs/images/DataSourceGallery.jpg b/docs/images/DataSourceGallery.jpg index 310c8c2..ceef46c 100644 Binary files a/docs/images/DataSourceGallery.jpg and b/docs/images/DataSourceGallery.jpg differ diff --git a/resource.tf b/resource.tf new file mode 100644 index 0000000..367a972 --- /dev/null +++ b/resource.tf @@ -0,0 +1,27 @@ +terraform { + required_providers { + squaredup = { + source = "registry.terraform.io/squaredup/squaredup" + } + } +} +provider "squaredup" { + region = "us" + api_key = "bIMYMcZJ9tlAFslAq0q0" +} + +resource "squaredup_workspace" "application_workspace" { + display_name = "Application Team" + description = "Workspace with Dashboards for Application Team" + //auto link +} + +resource "squaredup_workspace" "devops_workspace" { + display_name = "DevOps Team" + description = "Workspace with Dashboards for DevOps Team" + type = "application" + tags = ["terraform", "auto-created"] + workspaces_links = ["space-123"] //only link so disable auto link +} + +workspaces_links = [] #disable auto link \ No newline at end of file