### Manual Development Setup

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Sets up the development environment manually if Devbox is not used. Requires Go and wget to be installed.

```sh
make dev-setup
```

--------------------------------

### Start Devbox Shell

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Starts the Devbox shell, which automatically installs all required development tools and dependencies. This may take a while on the first run.

```sh
devbox shell
```

--------------------------------

### Install Devbox

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Installs the Devbox tool, which manages the development environment for the project. Ensure you have curl installed.

```sh
curl -fsSL https://get.jetpack.io/devbox | bash
```

--------------------------------

### Scorecards automation example with Jira task creation

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/data-sources/search.md

This comprehensive example demonstrates searching for microservices lacking a 'Gold' level in their 'ownership' scorecard and subsequently creating Jira tasks for each. It involves searching for entities, calculating the count of non-compliant services, and then using a resource to create Jira issues.

```hcl
data "port_search" "all_services" {
  query = jsonencode({
    "combinator" : "and", "rules" : [
      { "operator" : "=", "property" : "$blueprint", "value" : "microservice" },
    ]
  })
}

locals {
  // Count the number of services that are not owned by a team with a Gold level
  microservice_ownership_without_gold_level = length([
    for entity in data.port_search.all_services.entities : entity.scorecards["ownership"].level
    if entity.scorecards["ownership"].level != "Gold"
  ])
}

// create jira issue per service that is not owned by a team with a Gold level
resource "jira_issue" "microservice_ownership_without_gold_level" {
  count      = local.microservice_ownership_without_gold_level
  issue_type = "Task"

  project_key = "PORT"

  summary     = "Service ${data.port_search.backend_services.entities[count.index].title} hasn't reached Gold level in Ownership Scorecard"
  description = "[Service](https://app.getport.io/${port_blueprint.microservice.identifier}Entity/${data.port_search.backend_services.entities[count.index].identifier}) is not owned by a team with a Gold level, please assign a team with a Gold level to the service"
}
```

--------------------------------

### Initialize Terraform

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/README.md

Run this command after configuring the provider in your Terraform file to download and install the provider plugin.

```bash
terraform init
```

--------------------------------

### Sorted Permissions Example

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint_permissions.md

Illustrates the requirement for sorted lists of roles, users, and teams within the `entities` block. The example shows an invalid configuration with out-of-order roles and a valid configuration with roles sorted alphabetically.

```hcl
resource "port_blueprint_permissions" "microservices_permissions" {
	blueprint_identifier = "my_blueprint_identifier"
		entities             = {
			# invalid:
			"register" = {
				"roles" : [
					"Member",
				"Admin",
				],
				"users" : [],
				"teams" : []
			},
			# valid
			"register" = {
				"roles" : [
					"Admin",
				"Member",
				],
				"users" : [],
				"teams" : []
			},
			...
		},
	},
}

```

--------------------------------

### Dashboard Page Example

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

Create a dashboard page with a single markdown widget to display custom information or guides. This is suitable for providing overviews or instructions within the Port UI.

```terraform
resource "port_page" "microservice_dashboard_page" {
  identifier            = "microservice_dashboard_page"
  title                 = "Microservices"
  icon                  = "GitHub"
  type                  = "dashboard"
  widgets               = [
    jsonencode(
      {
        "id" : "dashboardWidget",
        "layout" : [
          {
            "height" : 400,
            "columns" : [
              {
                "id" : "microserviceGuide",
                "size" : 12
              }
            ]
          }
        ],
        "type" : "dashboard-widget",
        "widgets" : [
          {
            "title" : "Microservices Guide",
            "icon" : "BlankPage",
            "markdown" : "# This is the new Microservice Dashboard",
            "type" : "markdown",
            "description" : "",
            "id" : "microserviceGuide"
          }
        ],
      }
    )
  ]
}
```

--------------------------------

### Example Usage with Policy

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action_permissions.md

Demonstrates how to configure dynamic permissions for action execution and approval using the `jsonencode` function to pass a policy as a JSON string.

```APIDOC
resource "port_action_permissions" "restart_microservice_permissions" {
  action_identifier = port_action.restart_microservice.identifier
  permissions = {
    "execute" : {
      "roles" : [
        "Admin"
      ],
      "users" : [],
      "teams" : [],
      "owned_by_team" : true
    },
    "approve" : {
      "roles" : ["Member", "Admin"],
      "users" : [],
      "teams" : []
      "policy" : jsonencode(
        {
          queries : {
            executingUser : {
              rules : [
                {
                  value : "user",
                  operator : "=",
                  property : "$blueprint"
                },
                {
                  value : "true",
                  operator : "=",
                  property : "$owned_by_team" 

                }
              ],
              combinator : "and"
            }
          },
          conditions : [
          "true"]
        }
      )
    }
  }
}
```

--------------------------------

### Verify Contributions

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Runs linting and formatting checks to ensure code quality and consistency. These tools should be installed via 'make dev-setup'.

```sh
make lint
```

```sh
make format
```

--------------------------------

### Debug with Delve

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Installs Delve, a debugger for Go, and prepares the environment for debugging the provider's code.

```sh
make dev-debug
```

--------------------------------

### Create a Folder Inside Another Folder

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/folder.md

This example demonstrates how to create a sub-folder by specifying the parent folder's identifier. Requires the parent folder to be defined.

```hcl
resource "port_folder" "child_folder" {
  identifier = "child_folder"
  parent     = port_folder.example_folder.identifier
  title      = "Child Folder"
}
```

--------------------------------

### port_integration Resource Example

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/integration.md

Example of how to configure the port_integration resource in Terraform. This configuration manages an existing integration and its mappings.

```APIDOC
## port_integration Resource

### Description
Manages an existing integration and its mappings. This resource is not used for creating new integrations.

### Schema

#### Required

- `installation_id` (String) The installation ID of the integration. Must contain only lowercase letters, numbers, and dashes (pattern: `^[a-z0-9-]+$`).

#### Optional

- `config` (String) Integration Config Raw JSON string (use `jsonencode`).
- `installation_app_type` (String)
- `kafka_changelog_destination` (Object) The changelog destination of the blueprint (just an empty `{}`).
- `title` (String)
- `version` (String)
- `webhook_changelog_destination` (Attributes) The webhook changelog destination of the integration.

#### Read-Only

- `id` (String) The ID of this resource.

### Nested Schema for `kafka_changelog_destination`

Optional:

### Nested Schema for `webhook_changelog_destination`

Required:

- `url` (String) The url of the webhook changelog destination

Optional:

- `agent` (Boolean) The agent of the webhook changelog destination

### NOTICE:

The following config properties (`selector.query|entity.mappings.*`) are jq expressions, which means that you need to input either a valid jq expression (E.g `.title`), or if you want a string value, a qouted escaped string val (E.g `'my-string'`).

### Example Usage

```hcl
resource "port_integration" "my_custom_integration" {
	installation_id       = "my-custom-integration-id"
	title                 = "My Custom Integration"
	config = jsonencode({
		createMissingRelatedEntitiesboolean = true
		deleteDependentEntities = true,
		resources = [{
			kind = "my-custom-kind"
			selector = {
				query = ".title"
			}
			port = {
				entity = {
					mappings = [{
						identifier = "'my-identifier'"
						title      = ".title"
						blueprint  = "'my-blueprint'"
						properties = {
							my_property = 123
						}
						relations  = {}
					}]
				}
			}
		}]
	})
}
```
```

--------------------------------

### Action Resource Configuration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action.md

Example of configuring an Action resource with a filter and Kafka integration. This demonstrates how to define conditions for triggering actions and specify integration details.

```terraform
resource "port_action" "example" {
  blueprint = "example"
  trigger {
    "on" = "create"
    filter = jsonencode({
      "operator" = "AND"
      "conditions" = [
        {
          "property" = "status"
          "operator" = "="
          "value" = "active"
        }
      ]
    })
  }
  integration {
    "type" = "kafka"
    "kafka_method" = {}
  }
}
```

--------------------------------

### Search for an entity by identifier and blueprint

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/data-sources/search.md

This example shows how to find a specific entity by its identifier within a given blueprint. This is useful for targeting individual resources for further processing.

```hcl
data "port_search" "ads_service" {
  query = jsonencode({
    "combinator" : "and", "rules" : [
      { "operator" : "=", "property" : "$blueprint", "value" : "Service" },
      { "operator" : "=", "property" : "$identifier", "value" : "Ads" },
    ]
  })
}
```

--------------------------------

### Configure a Microservices Dashboard Page

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

This snippet shows how to define a 'Microservices' dashboard page with a specific layout and widgets, including a markdown widget for a guide.

```terraform
resource "port_page" "microservices" {
    title = "Microservices"
    icon  = "GitHub"
    type  = "dashboard"
    after = "microservices_entities_page"
    widgets = [
      jsonencode(
        {
          "id" : "dashboardWidget",
          "layout" : [
            {
              "height" : 400,
              "columns" : [
                {
                  "id" : "microserviceGuide",
                  "size" : 12
                }
              ]
            }
          ],
          "type" : "dashboard-widget",
          "widgets" : [
            {
              "title" : "Microservices Guide",
              "icon" : "BlankPage",
              "markdown" : "# This is the new Microservice Dashboard",
              "type" : "markdown",
              "description" : "",
              "id" : "microserviceGuide"
            }
          ],
        }
      )
    ]
  }
```

--------------------------------

### Create a Dashboard Page

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

This snippet shows how to create a 'dashboard' type page. It includes a title, icon, and custom widgets defined using JSON encoding. The example illustrates a dashboard widget with a markdown section.

```hcl
resource "port_page" "microservice_dashboard_page" {
  identifier            = "microservice_dashboard_page"
  title                 = "Microservices"
  icon                  = "GitHub"
  type                  = "dashboard"
  widgets               = [
    jsonencode(
      {
        "id" : "dashboardWidget",
        "layout" : [
          {
            "height" : 400,
            "columns" : [
              {
                "id" : "microserviceGuide",
                "size" : 12
              }
            ]
          }
        ],
        "type" : "dashboard-widget",
        "widgets" : [
          {
            "title" : "Microservices Guide",
            "icon" : "BlankPage",
            "markdown" : "# This is the new Microservice Dashboard",
            "type" : "markdown",
            "description" : "",
            "id" : "microserviceGuide"
          }
        ],
      }
    )
  ]
}

```

--------------------------------

### Allow update `myStringProperty` for admins and a specific user and team

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint_permissions.md

This example shows how to configure permissions to allow 'Admin' role, a specific user ('test-admin-user@test.com'), and a specific team ('Team Spiderman') to update the 'myStringProperty' of entities.

```APIDOC
## port_blueprint_permissions.microservices_permissions

### Description
Manages permissions for updating specific properties of blueprint entities.

### Schema

#### Required
- `blueprint_identifier` (String): The identifier of the blueprint.
- `entities` (Attributes): Configuration for entity permissions.

#### Nested Schema for `entities`

##### Optional
- `update_properties` (Attributes Map): Permissions for updating specific entity properties.

##### Nested Schema for `update_properties`

- `myStringProperty` (Attributes): Permissions for the 'myStringProperty'.
  - `roles` (List of String): Roles that have access.
  - `users` (List of String): Specific users with access.
  - `teams` (List of String): Specific teams with access.

### Example
```hcl
resource "port_blueprint_permissions" "microservices_permissions" {
	bluetooth_identifier = "my_blueprint_identifier"
		entities = {
			"update_properties" = {
				"myStringProperty" = {
					"roles": [
						"Admin",
					],
					"users": ["test-admin-user@test.com"],
					"teams": ["Team Spiderman"],
				}
			}
		}
}
```
```

--------------------------------

### Basic Blueprint Permissions Configuration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint_permissions.md

Defines basic permissions for the 'register' action on a blueprint, granting 'Member' role access. This is a foundational example for setting up blueprint access.

```hcl
resource "port_blueprint_permissions" "microservices_permissions" {
	blueprint_identifier = "my_blueprint_identifier"
		entities             = {
			"register" = {
				"roles" : [
					"Member",
				],
				"users" : [],
				"teams" : []
			},
		}
	}
}
```

--------------------------------

### Blueprint Entities Page Example

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

Configure a page to display entities belonging to a specific blueprint, using a table explorer widget. This is useful for listing and managing resources of a particular type.

```terraform
resource "port_page" "microservice_blueprint_page" {
  identifier            = "microservice_blueprint_page"
  title                 = "Microservices"
  type                  = "blueprint-entities"
  icon                  = "Microservice"
  blueprint             = port_blueprint.base_blueprint.identifier
  widgets               = [
    jsonencode(
      {
        "id" : "microservice-table-entities",
        "type" : "table-entities-explorer",
        "blueprint": port_blueprint.base_blueprint.identifier,
        "dataset" : {
          "combinator" : "and",
          "rules" : [
          ]
        }
      }
    )
  ]
}
```

--------------------------------

### Allow access to all members

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint_permissions.md

This example demonstrates how to grant 'Member' role access for registering and unregistering entities, while also allowing a specific user ('test-admin-user@test.com') and team ('Team Spiderman') to update entities and metadata properties.

```APIDOC
## port_blueprint_permissions.microservices_permissions

### Description
Manages permissions for blueprint entities, including registration, unregistration, and updates.

### Schema

#### Required
- `blueprint_identifier` (String): The identifier of the blueprint.
- `entities` (Attributes): Configuration for entity permissions.

#### Nested Schema for `entities`

##### Required
- `register` (Attributes): Permissions for registering entities.
- `unregister` (Attributes): Permissions for unregistering entities.
- `update` (Attributes): Permissions for updating entities.
- `update_metadata_properties` (Attributes): Permissions for updating metadata properties.

##### Optional
- `update_properties` (Attributes Map): Permissions for updating specific entity properties.
- `update_relations` (Attributes Map): Permissions for updating entity relations.

##### Nested Schema for `register`, `unregister`, `update`, `update_metadata_properties`, `update_properties`, `update_relations`

- `roles` (List of String): Roles that have access.
- `users` (List of String): Specific users with access.
- `teams` (List of String): Specific teams with access.

### Example
```hcl
resource "port_blueprint_permissions" "microservices_permissions" {
	bluetooth_identifier = "my_blueprint_identifier"
		entities             = {
			"register" = {
				"roles" : [
					"Member",
				],
				"users" : [],
				"teams" : []
			},
			"unregister" = {
				"roles" : [
					"Member",
				],
				"users" : [],
				"teams" : []
			},
			"update" = {
				"roles" : [
					"Member",
				],
				"users" : ["test-admin-user@test.com"],
				"teams" : []
			},
			"update_metadata_properties" = {
				"icon" = {
					"roles" : [
						"Member",
					],
					"users" : [],
					"teams" : []
				},
				"identifier" = {
					"roles" : [
						"Member",
					],
					"users" : [],
					"teams" : ["Team Spiderman"]
				},
				"team" = {
					"roles" : [
						"Admin",
					],
					"users" : [],
					"teams" : []
				},
				"title" = {
					"roles" : [
						"Member",
					],
					"users" : [],
					"teams" : []
				}
			}
		}
}
```
```

--------------------------------

### Create Aggregation Property for Pull Requests Per Day

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/aggregation_properties.md

This example shows how to set up an aggregation property to calculate the number of pull requests created per day for a repository. It links a repository blueprint with a pull request blueprint.

```terraform
resource "port_blueprint" "repository_blueprint" {
  title       = "Repository Blueprint"
  icon        = "Terraform"
  identifier  = "repository"
  description = ""
}

resource "port_blueprint" "pull_request_blueprint" {
  title       = "Pull Request Blueprint"
  icon        = "Terraform"
  identifier  = "pull_request"
  description = ""
  properties = {
    string_props = {
      "status" = {
        title = "Status"
      }
    }
  }
  relations = {
    "repository" = {
      title  = "Repository"
      target = port_blueprint.repository_blueprint.identifier
    }
  }
}

resource "port_aggregation_properties" "repository_aggregation_properties" {
  blueprint_identifier = port_blueprint.repository_blueprint.identifier
  properties           = {
    "pull_requests_per_day" = {
      target_blueprint_identifier = port_blueprint.pull_request_blueprint.identifier
      title                       = "Pull Requests Per Day"
      icon                        = "Terraform"
      description                 = "Pull Requests Per Day"

```

--------------------------------

### Action Permissions State Management Example

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action_permissions.md

When managing permissions, ensure that role lists are sorted to maintain valid Terraform state. Incorrectly ordered lists can lead to state inconsistencies.

```hcl
resource "port_action_permissions" "restart_microservice_permissions" {
		action_identifier = port_action.restart_microservice.identifier
		permissions = {
			# invalid
			"execute" : {
				"roles" : [
					"member",
					"admin",
				],
				...
			},
			# valid
			"approve" : {
				"roles" : [
					"admin",
					"member",
				],
			}
		}
	}
```

--------------------------------

### Calculate Average Fix Pull Requests Per Month with Query

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/aggregation_properties.md

This example demonstrates how to calculate the average number of 'fix' pull requests per month by adding a query to filter pull requests with a specific title.

```hcl
resource "port_blueprint" "repository_blueprint" {
  title       = "Repository Blueprint"
  icon        = "Terraform"
  identifier  = "repository"
  description = ""
}

resource "port_blueprint" "pull_request_blueprint" {
  title       = "Pull Request Blueprint"
  icon        = "Terraform"
  identifier  = "pull_request"
  description = ""
  properties = {
    string_props = {
      "status" = {
        title = "Status"
      }
    }
  }
  relations = {
    "repository" = {
      title  = "Repository"
      target = port_blueprint.repository_blueprint.identifier
    }
  }
}

resource "port_aggregation_properties" "repository_aggregation_properties" {

```

--------------------------------

### Basic Folder Creation

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/folder.md

Use this snippet to create a basic folder. Ensure the PORT_BETA_FEATURES_ENABLED environment variable is set to true.

```hcl
resource "port_folder" "example_folder" {
  identifier = "example_folder"
  title      = "Example Folder"
}
```

--------------------------------

### Create a Port Blueprint

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint.md

Defines a basic blueprint resource for an 'Environment' with string properties. Use this to set up the fundamental structure of your data model in Port.

```hcl
resource "port_blueprint" "environment" {
  title      = "Environment"
  icon       = "Environment"
  identifier = "environment"
  properties = {
    string_props = {
      "aws-region" = {
        title = "AWS Region"
      }
      "docs-url" = {
        title  = "Docs URL"
        format = "url"
      }
    }
  }
}
```

--------------------------------

### Initialize and Apply Terraform Configuration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/examples/README.md

Standard Terraform commands to initialize, plan, and apply a configuration. Ensure your provider configuration is set up correctly before running these commands.

```bash
terraform init
```

```bash
terraform plan
```

```bash
terraform apply
```

--------------------------------

### Create a Blueprint with Mirror Properties and Relations

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint.md

Define a blueprint for a microservice, including string properties like 'domain' and 'slack-channel', mirroring an 'aws-region' from an environment, and establishing a required relation to an 'environment' blueprint.

```hcl
resource "port_blueprint" "microservice" {
  title      = "Microservice"
  icon       = "Microservice"
  identifier = "microservice"
  properties = {
    string_props = {
      "domain" = {
        title = "Domain"
      }
      "slack-channel" = {
        title  = "Slack Channel"
        format = "url"
      }
    }
  }
  mirror_properties = {
    "aws-region" = {
      path = "environment.aws-region"
    }
  }
  relations = {
    "environment" = {
      target   = port_blueprint.environment.identifier
      required = true
      many     = false
    }
  }
}

```

--------------------------------

### Basic Action Permissions Configuration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action_permissions.md

Configure basic execute and approve permissions for an action. Ensure roles are listed in sorted order to maintain state validity.

```hcl
resource "port_action_permissions" "restart_microservice_permissions" {
	action_identifier = port_action.restart_microservice.identifier
	permissions = {
		"execute" : {
			"roles" : [
				"admin"
			],
			"users" : [],
			"teams" : [],
			"owned_by_team" : true
		},
		"approve" : {
			"roles" : ["member", "admin"],
			"users" : [],
			"teams" : []
		}
	}
}
```

--------------------------------

### Configure Webhook with Mixed Relations

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/webhook.md

Sets up a webhook for 'create' operations on the 'microservice' blueprint. It filters for 'pull_request' events and maps complex relations for 'author' and 'team'.

```hcl
resource "port_webhook" "create_pr" {
    identifier = "pr_webhook"
    title      = "Webhook with mixed relations"
    icon       = "Terraform"
    enabled    = true
    
    mappings = [
      {
        blueprint = port_blueprint.microservice.identifier
        operation = { "type" = "create" }
        filter    = ".headers.\"x-github-event\" == \"pull_request\""
        entity = {
          identifier = ".body.pull_request.id | tostring"
          title      = ".body.pull_request.title"
          properties = {
            url = ".body.pull_request.html_url"
          }
          relations = {
            # Complex object relation with search query
            author = jsonencode({
              combinator = "'and'",
              rules = [
                {
                  property = "'\'identifier\'"
                  operator = "'='"
                  value    = ".body.pull_request.user.login | tostring"
                }
              ]
            })
            
            # Simple string relation
            team = ".body.repository.owner.login | tostring"
          }
        }
      }
    ]
    
    depends_on = [
      port_blueprint.microservice,
      port_blueprint.author,
      port_blueprint.team
    ]
  }
```

--------------------------------

### Terraform Apply and Cleanup Commands

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/examples/resources/port_action/dynamic_form_filters/README.md

Provides bash commands for setting Terraform credentials, initializing, applying the configuration, and cleaning up resources.

```bash
# Set credentials
export TF_VAR_port_client_id="your-client-id"
export TF_VAR_port_client_secret="your-client-secret"

# Apply
terraform init
terraform apply

# Cleanup
terraform destroy
```

--------------------------------

### Create a Folder After Another Folder

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/folder.md

Use this snippet to create a folder that will be placed immediately after an existing folder, based on its identifier. Requires the reference folder to be defined.

```hcl
resource "port_folder" "another_folder" {
  identifier = "another_folder"
  after      = port_folder.example_folder.identifier
  title      = "Another Folder"
}
```

--------------------------------

### Configure port_integration Resource

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/integration.md

Use this snippet to configure an existing integration and its mappings. Note that properties like `selector.query` and `entity.mappings.*` accept jq expressions or escaped strings.

```hcl
resource "port_integration" "my_custom_integration" {
	installation_id       = "my-custom-integration-id"
	title                 = "My Custom Integration"
	config = jsonencode({
		createMissingRelatedEntitiesboolean = true
		deleteDependentEntities = true,
		resources = [{
			kind = "my-custom-kind"
			selector = {
				query = ".title"
			}
			port = {
				entity = {
					mappings = [{
						identifier = "'my-identifier'"
						title      = ".title"
						blueprint  = "'my-blueprint'"
						properties = {
							my_property = 123
						}
						relations  = {}
					}]
				}
			}
		}]
	})
}

```

--------------------------------

### Create Multiple Aggregation Properties in One Resource

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/aggregation_properties.md

Define multiple aggregation properties within a single resource block. This example shows how to calculate both the daily average of pull requests and the overall count of pull requests.

```terraform
resource "port_blueprint" "repository_blueprint" {
  title       = "Repository Blueprint"
  icon        = "Terraform"
  identifier  = "repository"
  description = ""
}

resource "port_blueprint" "pull_request_blueprint" {
  title       = "Pull Request Blueprint"
  icon        = "Terraform"
  identifier  = "pull_request"
  description = ""
  properties = {
    string_props = {
      "status" = {
        title = "Status"
      }
    }
  }
  relations = {
    "repository" = {
      title  = "Repository"
      target = port_blueprint.repository_blueprint.identifier
    }
  }
}

resource "port_aggregation_properties" "repository_aggregation_properties" {
  blueprint_identifier = port_blueprint.repository_blueprint.identifier
  properties           = {
    "pull_requests_per_day" = {
      target_blueprint_identifier = port_blueprint.pull_request_blueprint.identifier
      title                       = "Pull Requests Per Day"
      icon                        = "Terraform"
      description                 = "Pull Requests Per Day"
      method                      = {
        average_entities = {
          average_of      = "day"
          measure_time_by = "$createdAt"
        }
      }
    }
    "overall_pull_requests_count" = {
      target_blueprint_identifier = port_blueprint.pull_request_blueprint.identifier
      title                       = "Overall Pull Requests Count"
      icon                        = "Terraform"
      description                 = "Overall Pull Requests Count"
      method                      = {
        count_entities = true
      }
    }
  }
}
```

--------------------------------

### Allow Update Property for Admins and Specific User/Team

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint_permissions.md

Grants 'Admin' role access, along with specific user and team permissions, for updating the 'myStringProperty'. This example shows how to restrict property updates to authorized individuals and groups.

```hcl
resource "port_blueprint_permissions" "microservices_permissions" {
	blueprint_identifier = "my_blueprint_identifier"
		entities = {
			# all properties from the previous example...
			"update_properties" = {
				"myStringProperty" = {
					"roles": [
						"Admin",
					],
					"users": ["test-admin-user@test.com"],
					"teams": ["Team Spiderman"],
				}
			}
		}
	}
}
```

--------------------------------

### Run Acceptance Tests

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Executes acceptance tests for the provider. Ensure PORT_CLIENT_ID and PORT_CLIENT_SECRET environment variables are set. Optionally, set PORT_BASE_URL.

```sh
make acctest
```

--------------------------------

### Allow update relations for a specific team for admins and a specific user and team

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint_permissions.md

This example configures permissions to allow 'Admin' role, a specific user ('test-admin-user@test.com'), and a specific team ('Team Spiderman') to update the 'myRelations' relation of entities.

```APIDOC
## port_blueprint_permissions.microservices_permissions

### Description
Manages permissions for updating specific relations of blueprint entities.

### Schema

#### Required
- `blueprint_identifier` (String): The identifier of the blueprint.
- `entities` (Attributes): Configuration for entity permissions.

#### Nested Schema for `entities`

##### Optional
- `update_relations` (Attributes Map): Permissions for updating entity relations.

##### Nested Schema for `update_relations`

- `myRelations` (Attributes): Permissions for the 'myRelations' relation.
  - `roles` (List of String): Roles that have access.
  - `users` (List of String): Specific users with access.
  - `teams` (List of String): Specific teams with access.

### Example
```hcl
resource "port_blueprint_permissions" "microservices_permissions" {
	bluetooth_identifier = "my_blueprint_identifier"
		entities = {
			"update_relations" = {
				"myRelations" = {
					"roles": [
						"Admin",
					],
					"users": ["test-admin-user@test.com"],
					"teams": ["Team Spiderman"],
				}
			}
		}
}
```
```

--------------------------------

### Configure Action Permissions with Policy

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action_permissions.md

Use this resource to define specific execution and approval permissions for an action, including dynamic policies. Policies are evaluated by Port and must be provided as a JSON string via `jsonencode`.

```hcl
resource "port_action_permissions" "restart_microservice_permissions" {
  action_identifier = port_action.restart_microservice.identifier
  permissions = {
    "execute" : {
      "roles" : [
        "Admin"
      ],
      "users" : [],
      "teams" : [],
      "owned_by_team" : true
    },
    "approve" : {
      "roles" : ["Member", "Admin"],
      "users" : [],
      "teams" : []
      # Terraform's "jsonencode" function converts a
      # Terraform expression result to valid JSON syntax.
      "policy" : jsonencode(
        {
          queries : {
            executingUser : {
              rules : [
                {
                  "value" : "user",
                  "operator" : "=",
                  "property" : "$blueprint"
                },
                {
                  "value" : "true",
                  "operator" : "=",
                  "property" : "$owned_by_team"

                }
              ],
              "combinator" : "and"
            }
          },
          "conditions" : [
          "true"]
        }
      )
    }
  }
}
```

--------------------------------

### Create a Port Blueprint with Relations

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint.md

Defines a 'Microservice' blueprint that includes a required, one-to-one relation to an 'Environment' blueprint. This is useful for establishing connections between different entities in your catalog.

```hcl
resource "port_blueprint" "environment" {
  title      = "Environment"
  icon       = "Environment"
  identifier = "environment"
  properties = {
    string_props = {
      "aws-region" = {
        title = "AWS Region"
      }
      "docs-url" = {
        title  = "Docs URL"
        format = "url"
      }
    }
  }
}

resource "port_blueprint" "microservice" {
  title      = "Microservice"
  icon       = "Microservice"
  identifier = "microservice"
  properties = {
    string_props = {
      "domain" = {
        title = "Domain"
      }
      "slack-channel" = {
        title  = "Slack Channel"
        format = "url"
      }
    }
  }
  relations = {
    "environment" = {
      target   = port_blueprint.environment.identifier
      required = true
      many     = false
    }
  }
}
```

--------------------------------

### Configure a Home Page Resource

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

This snippet defines the default 'Home' page for the organization, including a markdown widget and an iframe widget for an external video.

```terraform
resource "port_page" "home_page" {
    identifier            = "$home"
    title                 = "Home"
    type                  = "home"
    widgets               = [
      jsonencode(
        {
          "type" : "dashboard-widget",
          "id" : "azkLJD6wLk6nJSvA",
          "layout" : [
            {
              "columns" : [
                {
                  "id" : "markdown",
                  "size" : 6
                },
                {
                  "id" : "overview",
                  "size" : 6
                },
              ],
              "height" : 648
            }
          ],
          "widgets" : [
            {
              "type" : "markdown",
              "markdown" : "## Welcome to your internal developer portal",
              "icon" : "port",
              "title" : "About developer Portal",
              "id" : "markdown"
            },
            {
              "type" : "iframe-widget",
              "id" : "overview",
              "title" : "Overview",
              "icon" : "Docs",
              "url" : "https://www.youtube.com/embed/ggXL2ZsPVQM?si=xj6XtV0faatoOhss",
              "urlType" : "public"
            }
          ]
        }
      )
    ]
  }
```

--------------------------------

### Run Provider for Integration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/CONTRIBUTING.md

Builds and runs the provider code for integration testing. After execution, export the printed TF_REATTACH_PROVIDERS environment variable.

```sh
make dev-run-integration
```

--------------------------------

### Create a Port Blueprint with Mirror Properties

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/blueprint.md

Defines a 'Microservice' blueprint that mirrors the 'aws-region' property from its related 'Environment' blueprint. This allows data to be synchronized across related entities.

```hcl
resource "port_blueprint" "microservice" {
  title      = "Microservice"
  icon       = "Microservice"
  identifier = "microservice"
  properties = {
    string_props = {
      "domain" = {
        title = "Domain"
      }
      "slack-channel" = {
        title  = "Slack Channel"
        format = "url"
      }
    }
  }
  mirror_properties = {
    "aws-region" = {
      path = "environment.aws-region"
    }
  }
  relations = {
    "environment" = {
      target   = port_blueprint.environment.identifier
      required = true
      many     = false
    }
  }
}
```

--------------------------------

### Import Home Page State

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

This command demonstrates how to import the state of the default home page into Terraform when it's not managed by a resource block.

```bash
terraform import port_page.home_page "$home"
```

--------------------------------

### Create a Blueprint Entities Page

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/page.md

This snippet demonstrates how to create a 'blueprint-entities' type page. It requires specifying the page identifier, title, icon, and the blueprint it relates to. Widgets can be defined using JSON encoding, such as a table explorer for entities.

```hcl
resource "port_page" "microservice_blueprint_page" {
  identifier            = "microservice_blueprint_page"
  title                 = "Microservices"
  type                  = "blueprint-entities"
  icon                  = "Microservice"
  blueprint             = port_blueprint.base_blueprint.identifier
  widgets               = [
    jsonencode(
      {
        "id" : "microservice-table-entities",
        "type" : "table-entities-explorer",
        "blueprint": port_blueprint.base_blueprint.identifier,
        "dataset" : {
          "combinator" : "and",
          "rules" : [
          ]
        }
      }
    )
  ]
}

```

--------------------------------

### Dynamic List of Allowed Values with JQ Query

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/examples/resources/port_action/pattern_jq_query/README.md

Use this to create a list of allowed values that varies based on context. This is useful for creating dynamic enums where the available options depend on other properties.

```hcl
pattern_jq_query = "if .team == \"platform\" then [\"dev\", \"staging\", \"production\"] else [\"dev\", \"staging\"] end"
```

--------------------------------

### Action Resource Configuration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action.md

Configuration options for the Action resource, including optional fields for notifications, triggers, and invocation methods.

```APIDOC
## Action Resource Configuration

### Description
Configuration options for the Action resource, including optional fields for notifications, triggers, and invocation methods.

### Optional Parameters
- `allow_anyone_to_view_runs` (Boolean) - Whether members can view the runs of this action
- `approval_email_notification` (Object) - The email notification of the approval. This is a presence-based block — defining it enables email notifications for approval; no nested attributes are required.
- `approval_webhook_notification` (Attributes) - The webhook notification of the approval
- `automation_trigger` (Attributes) - Automation trigger for the action
- `azure_method` (Attributes) - Azure DevOps invocation method
- `blueprint` (String, Deprecated) - The blueprint identifier the action relates to
- `description` (String) - Description
- `github_method` (Attributes) - GitHub invocation method
- `gitlab_method` (Attributes) - Gitlab invocation method
- `icon` (String) - Icon
- `integration_method` (Attributes) - Integration invocation method (handled by Ocean integrations)
- `kafka_method` (Attributes) - Kafka invocation method
- `publish` (Boolean) - Publish action
- `required_approval` (String) - Require approval before invoking the action. Can be one of "true", "false", "ANY" or "ALL"
- `self_service_trigger` (Attributes) - Self service trigger for the action. Note: you can define only one of `order_properties` and `steps`
- `title` (String) - Title
- `upsert_entity_method` (Attributes) - Upsert Entity invocation method
- `webhook_method` (Attributes) - Webhook invocation method

### Read-Only Parameters
- `id` (String) - The ID of this resource.
```

--------------------------------

### Webhook Method Configuration

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/action.md

Configuration for the webhook method, including URL, agent, body, headers, HTTP method, and synchronization options.

```APIDOC
## Webhook Method Configuration

### Description
Configure the webhook method for invoking actions, specifying the target URL, HTTP method, and optional payload details.

### Parameters
#### Required
- **url** (String) - Required when selecting type WEBHOOK. The URL to invoke the action

#### Optional
- **agent** (String) - Specifies whether to use an agent to invoke the action. This can be a boolean value (`'true''` or `'false'`) or a JQ if dynamic evaluation is needed.
- **body** (String) - The Webhook body should be in `JSON` format, encoded as a string. Use [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode) to encode arrays or objects. Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
- **headers** (Map of String) - The HTTP headers for invoking the action. They should be encoded as a key-value object to a string using [jsonencode](https://developer.hashicorp.com/terraform/language/functions/jsonencode). Learn about how to [define the action payload](https://docs.getport.io/create-self-service-experiences/setup-backend/#define-the-actions-payload).
- **method** (String) - The HTTP method to invoke the action
- **synchronized** (String) - Synchronize the action
```

--------------------------------

### port_system_blueprint Resource Schema

Source: https://github.com/port-labs/terraform-provider-port-labs/blob/main/docs/resources/system_blueprint.md

Defines the schema for the port_system_blueprint resource, including required, optional, and read-only fields for configuring system blueprints.

```APIDOC
## Schema

### Required

- `identifier` (String) Identifier of the system blueprint.

### Optional

- `calculation_properties` (Attributes Map) The calculation properties of the blueprint (see [below for nested schema](#nestedatt--calculation_properties))
- `include_in_global_search` (Boolean) Whether to include this blueprint's entities in global search (Spotlight). When not set, the organization's `include_blueprints_in_global_search_by_default` setting applies.
- `mirror_properties` (Attributes Map) The mirror properties of the blueprint (see [below for nested schema](#nestedatt--mirror_properties))
- `properties` (Attributes) The properties of the blueprint (see [below for nested schema](#nestedatt--properties))
- `relations` (Attributes Map) The relations of the blueprint (see [below for nested schema](#nestedatt--relations))

### Read-Only

- `id` (String) Identifier of the system blueprint.

<a id="nestedatt--calculation_properties">
### Nested Schema for `calculation_properties`

Required:

- `calculation` (String) The calculation of the calculation property
- `type` (String) The type of the calculation property

Optional:

- `colorized` (Boolean) The colorized of the calculation property
- `colors` (Map of String) The colors of the calculation property
- `date_format` (String) Display format for `date-time` calculation properties (for example `24-hour`)
- `description` (String) The description of the calculation property
- `format` (String) The format of the calculation property
- `icon` (String) The icon of the calculation property
- `spec` (String) The spec of the calculation property
- `spec_authentication` (Attributes) The spec authentication of the calculation property (see [below for nested schema](#nestedatt--calculation_properties--spec_authentication))
- `title` (String) The title of the calculation property

<a id="nestedatt--calculation_properties--spec_authentication">
### Nested Schema for `calculation_properties.spec_authentication`

Required:

- `authorization_url` (String) The authorizationUrl of the spec authentication
- `client_id` (String) The clientId of the spec authentication
- `token_url` (String) The tokenUrl of the spec authentication


<a id="nestedatt--mirror_properties">
### Nested Schema for `mirror_properties`

Required:

- `path` (String) The path of the mirror property

Optional:

- `title` (String) The title of the mirror property


<a id="nestedatt--properties">
### Nested Schema for `properties`

Optional:

- `array_props` (Attributes Map) The array property of the blueprint (see [below for nested schema](#nestedatt--properties--array_props))
- `boolean_props` (Attributes Map) The boolean property of the blueprint (see [below for nested schema](#nestedatt--properties--boolean_props))
- `number_props` (Attributes Map) The number property of the blueprint (see [below for nested schema](#nestedatt--properties--number_props))
- `object_props` (Attributes Map) The object property of the blueprint (see [below for nested schema](#nestedatt--properties--object_props))
- `string_props` (Attributes Map) The string property of the blueprint (see [below for nested schema](#nestedatt--properties--string_props))

<a id="nestedatt--properties--array_props">
### Nested Schema for `properties.array_props`

Optional:

- `boolean_items` (Attributes) The items of the array property (see [below for nested schema](#nestedatt--properties--array_props--boolean_items))
- `description` (String) The description of the property
- `icon` (String) The icon of the property
- `max_items` (Number) The max items of the array property
- `min_items` (Number) The min items of the array property
- `number_items` (Attributes) The items of the array property (see [below for nested schema](#nestedatt--properties--array_props--number_items))
- `object_items` (Attributes) The items of the array property (see [below for nested schema](#nestedatt--properties--array_props--object_items))
- `required` (Boolean) Whether the property is required
- `string_items` (Attributes) The items of the array property (see [below for nested schema](#nestedatt--properties--array_props--string_items))
- `title` (String) The title of the property

<a id="nestedatt--properties--array_props--boolean_items">
### Nested Schema for `properties.array_props.boolean_items`

Optional:

- `default` (List of Boolean) The default of the items


<a id="nestedatt--properties--array_props--number_items">
### Nested Schema for `properties.array_props.number_items`

(Schema details omitted as they were not fully provided in the source text)
```