Added examples and documentation

.github/workflows/test.yml

@@ -42,7 +42,7 @@ jobs:
             (echo; echo "Unexpected difference in directories after code generation. Run 'make docs' command and commit."; exit 1)
 
   test-cli:
-    name: Tines CLI Unit Tests
+    name: Tines API Client Unit Tests
     needs: build
     runs-on: ubuntu-latest
     steps:
@@ -52,7 +52,7 @@ jobs:
             go-version-file: "go.mod"
             cache: true
       - run: go mod download
-      - run: go test -v -cover ./internal/tines_cli
+      - run: go test -v -cover ./internal/tines_cli/
 
   test-provider:
     name: Terraform Provider Acceptance Tests
@@ -61,6 +61,7 @@ jobs:
     timeout-minutes: 15
     strategy:
       fail-fast: false
+      max-parallel: 1 # Required to avoid resource conflicts in the test tenant
       matrix:
         terraform:
           - "1.1.*"

Makefile

@@ -19,17 +19,17 @@ lintfix:
 .PHONY: install
 install:
 	brew install golangci-lint
-	brew install terraform
+	brew tap hashicorp/tap
+	brew install hashicorp/tap/terraform
 	go install golang.org/x/tools/gopls@latest
-	go get github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
+	go install github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest
 
 # Generate docs
 .PHONY: docs
 docs:
-	go get github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
-	go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs
+	go run github.com/hashicorp/terraform-plugin-docs/cmd/tfplugindocs@latest
 
 # Run local install
 .PHONY: install-local
-install:
+install-local:
 	go install

docs/guides/version-0.1-upgrade.md

@@ -0,0 +1,52 @@
+---
+layout: ""
+page_title: "Upgrading to version 0.1.x (from 0.0.x)"
+description: Terraform Tines Provider Version 0.1 Upgrade Guide
+---
+
+# Terraform Tines Provider Version 0.1 Upgrade Guide
+Starting with version `0.1.0`, the Tines provider on Terraform introduces a new and simplified way to manage stories. This means that any Resource and its Schema with a version below `0.1.0` will no longer be compatible with `tines` Terraform provider version `0.1.0` or higher, as there are breaking changes in this version. If you have an older Terraform state file for a version below `0.1.0`, we recommend starting fresh by initializing a new state (via `terraform init`) for version `0.1.0` or higher.
+
+
+## Provider Version Configuration
+If you are not ready to make a move to version 0.1 of the Tines provider, you may keep the 0.0.x branch active for
+your Terraform project by specifying:
+
+```terraform
+provider "tines" {
+  version = "~> 0.0"
+  # ... any other configuration
+}
+```
+
+## Getting Started With v0.1.0
+To export your Tines Story, follow [these instructions](https://www.tines.com/docs/stories/importing-and-exporting#exporting-stories) and place the exported filed in the same directory as your `main.tf` file. After that, you can define your story as a Terraform Resource using the following syntax:
+
+```terraform
+# provider.tf
+provider "tines" {}
+
+# main.tf
+resource "tines_story" "dev_story_name" {
+  data            = file("${path.module}/story-example.json")
+  tenant_url      = "https://dev-tenant.tines.com"
+  tines_api_token = var.dev_tines_api_token
+  team_id         = var.team_id   # optional
+  folder_id       = var.folder_id # optional
+}
+
+# variable.tf
+variable "dev_tines_api_token" {
+  type = string
+}
+
+variable "team_id" {
+  type = number
+}
+
+variable "folder_id" {
+  type = number
+}
+```
+
+And that's all. You don't need to import the state into Terraform either. Running a `terraform apply` will automatically perform an upsert and set the state in Terraform accordingly.

docs/guides/version-0.2-upgrade.md

@@ -0,0 +1,39 @@
+---
+layout: ""
+page_title: "Upgrading to version 0.2.x (from 0.1.x)"
+description: Terraform Tines Provider Version 0.2 Upgrade Guide
+---
+
+# Terraform Tines Provider Version 0.2 Upgrade Guide
+
+Version 0.2 has made some architectural and configurability changes under the hood in preparation for some significant new functionality, which will be coming in a future release. While all existing resources are compatible with v0.2, some attributes have been deprecated and some new configuration values are required.
+
+## Provider Version Configuration
+If you are not ready to make a move to version 0.2 of the Tines provider, you may keep the 0.1.x branch active for
+your Terraform project by specifying:
+
+```terraform
+provider "tines" {
+  version = "~> 0.1"
+  # ... any other configuration
+}
+```
+
+We highly recommend that you review this guide, make necessary changes and move to 0.2.x branch, as further 0.1.x releases are
+unlikely to happen.
+
+~> Before attempting to upgrade to version 0.2, you should first upgrade to the
+   latest version of 0.1 to ensure any transitional updates are applied to your
+   existing configuration.
+
+## Provider Global Configuration Changes
+The following changes have been made at the provider level:
+
+- Added a new required configuration value for `tenant` which can be set either in the provider configuration or as the `TINES_TENANT` environment variable.
+- Added a new required configuration value for `api_key` which can be set either in the provider configuration or as the `TINES_API_KEY` environment variable.
+
+## Tines Story Configuration Changes
+The following changes have been made to the `tines_story` resource:
+
+- The `tines_api_token` resource attribute has been marked as deprecated and will be removed in a future release. In version 0.2, any value set here will be ignored and overridden by the provider-level `api_key` attribute.
+- The `tenant_url` resource attribute has been marked as deprecated and will be removed in a future release. In version 0.2, any value set here will be ignored and overriden by the provider-level `tenant` attibute.

docs/index.md

@@ -1,19 +1,36 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
-page_title: "tines Provider"
-subcategory: ""
+layout: ""
+page_title: "Provider: Tines"
 description: |-
-  
+  The Tines provider provides resources to interact with the Tines API.
 ---
 
-# tines Provider
-
+# Tines Provider
 
+The Tines provider is used to interact with resources supported by Tines. 
+The provider needs to be configured with the proper credentials before it can be used.
 
 ## Example Usage
 
 ```terraform
-provider "tines" {}
+terraform {
+    required_providers {
+      tines = {
+        source = "tines/tines"
+        version = "~> 0.2.0"
+      }
+    }
+}
+
+provider "tines" {
+    tenant = "https://example.tines.com"
+    api_key = var.tines_api_key
+}
+
+# Create a Tines Story
+resource "tines_story" "example_story" {
+    #
+}
 ```
 
 <!-- schema generated by tfplugindocs -->
@@ -22,4 +39,4 @@ provider "tines" {}
 ### Optional
 
 - `api_key` (String, Sensitive) If this value is not set in the configuration, you must set the TINES_API_KEY environment variable instead.
-- `tenant` (String) If this value is not set in the configuration, you must set the TINES_TENANT environment variable instead.
+- `tenant` (String) If this value is not set in the configuration, you must set the TINES_TENANT environment variable instead.

docs/resources/story.md

@@ -1,55 +1,73 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "tines_story Resource - terraform-provider-tines"
 subcategory: ""
 description: |-
-  Manage a Tines Story
+  A Tines Story resource can be managed either via a Story JSON export file, or by setting configuration values on the resource.
+  We recommend managing Stories via JSON export files if you rely on Terraform to manage change control for storyboard content. Otherwise, if
+  you use Tines' built-in Change Control feature, we recommend only enforcing configuration values via Terraform.
 ---
 
 # tines_story (Resource)
 
-Manage a Tines Story
+A Tines Story resource can be managed either via a Story JSON export file, or by setting configuration values on the resource.
+We recommend managing Stories via JSON export files if you rely on Terraform to manage change control for storyboard content. Otherwise, if
+you use Tines' built-in Change Control feature, we recommend only enforcing configuration values via Terraform.
 
+## Example Usage
 
+```terraform
+# Manage this Story resource using a JSON story export.
+resource "tines_story" "example_imported_story" {
+  team_id = 1
+  data = file("${path.module}/story-example.json")
+}
 
+# Manage this Story resource using resource attributes.
+resource "tines_story" "example_configured_story" {
+  team_id = 1
+  name = "Example Story Name"
+  change_control_enabled = true
+}
+```
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `data` (String) A local JSON file containing an exported Tines story. Setting this value can only be combined with the team_id and folder_id attributes.
 - `team_id` (Number) The ID of the team that this story belongs to.
 
 ### Optional
 
+- `change_control_enabled` (Boolean) Boolean flag indicating if change control is enabled.
+- `data` (String) A local JSON file containing an exported Tines story. Setting this value can only be combined with the team_id and folder_id attributes.
+- `description` (String) A user-defined description of the story.
+- `disabled` (Boolean) Boolean flag indicating whether the story is disabled from running.
+- `entry_agent_id` (Number) The ID of the entry action for this story (action must be of type Webhook).
+- `exit_agents` (List of Number) An Array of IDs describing exit actions for this story (actions must be message-only mode event transformation).
 - `folder_id` (Number) The ID of the folder where this story should be organized. The folder ID must belong to the associated team that owns this story.
+- `keep_events_for` (Number) Defined event retention period in seconds.
+- `locked` (Boolean) Boolean flag indicating whether the story is locked, preventing edits.
 - `name` (String) The name of the Tines story.
-- `tenant_url` (String, Deprecated) [DEPRECATED] Tines tenant URL
+- `priority` (Boolean) Boolean flag indicating whether story runs with high priority.
+- `send_to_story_access` (String) Controls who is allowed to send to this story (TEAM, GLOBAL, SPECIFIC_TEAMS). default: TEAM.
+- `send_to_story_access_source` (String) Valid values are STS, STS_AND_WORKBENCH, WORKBENCH or OFF indicating where the Send to Story can be used.
+- `send_to_story_enabled` (Boolean, Deprecated) Boolean flag indicating if Send to Story is enabled. If enabling Send to Story, the entry_agent_id and exit_agent_ids attributes must also be specified.
+- `send_to_story_skill_use_requires_confirmation` (Boolean) Boolean flag indicating whether Workbench should ask for confirmation before running this story.
+- `shared_team_slugs` (List of String) Array of team slugs that can send to this story. Required to set send_to_story_access to SPECIFIC_TEAMS.
+- `tags` (List of String) An array of tag names to apply to the story.
+- `tenant_url` (String, Deprecated) Tines tenant URL
 - `tines_api_token` (String, Sensitive, Deprecated) API token for Tines Tenant
 
 ### Read-Only
 
-- `change_control_enabled` (Boolean)
-- `created_at` (String)
-- `description` (String)
-- `disabled` (Boolean)
-- `edited_at` (String)
-- `entry_agent_id` (Number)
-- `exit_agents` (List of Number)
-- `guid` (String)
+- `created_at` (String) ISO 8601 Timestamp representing date and time the story was created.
+- `edited_at` (String) ISO 8601 Timestamp representing date and time the story was last logically updated.
+- `guid` (String) The globally unique identifier of the story.
 - `id` (Number) The Tines-generated identifier for this story.
-- `keep_events_for` (Number)
 - `last_updated` (String)
-- `locked` (Boolean)
-- `mode` (String)
-- `owners` (List of Number)
-- `priority` (Boolean)
-- `published` (Boolean)
-- `send_to_story_access` (String)
-- `send_to_story_access_source` (String)
-- `send_to_story_enabled` (Boolean)
-- `send_to_story_skill_use_requires_confirmation` (Boolean)
-- `shared_team_slugs` (List of String)
-- `slug` (String)
-- `tags` (List of String)
-- `user_id` (Number)
+- `mode` (String) The mode of the story (LIVE or TEST).
+- `owners` (List of Number) List of user IDs that are listed as owners on the story.
+- `published` (Boolean) Boolean flag indicating whether the story is published.
+- `slug` (String) An underscored representation of the story name.
+- `user_id` (Number) ID of the story creator.
+

examples/provider/provider.tf

@@ -1 +1,18 @@
-provider "tines" {}
+terraform {
+    required_providers {
+      tines = {
+        source = "tines/tines"
+        version = "~> 0.2.0"
+      }
+    }
+}
+
+provider "tines" {
+    tenant = "https://example.tines.com"
+    api_key = var.tines_api_key
+}
+
+# Create a Tines Story
+resource "tines_story" "example_story" {
+    #
+}