button in the top-right corner of the page.
+
+ This will display the latest action runs that have been executed by the logged-in user:
+ 
+
+ You can also click on the `My run history` button to see a table with all of the user's previous action runs.
+
+- After executing an action from the [self-service page](https://app.getport.io/self-serve), the `My latest runs` list will open automatically, showing the newly created action run.
+
+### Admin role
+
+In addition to the methods mentioned above, `admins` can find action runs using one of the following methods:
- The dedicated `Runs history` table:
- **Self-service actions** - go to the [self-service page](https://app.getport.io/self-serve) of your portal, then click on the +
@@ -252,15 +246,10 @@ jobs:
+
+
+Monitor response data
+ +```json showLineNumbers +{ + "id":15173866, + "org_id":1000147697, + "type":"query alert", + "name":"A change @webhook-PORT", + "message":"A change has happened", + "tags":[ + "app:webserver" + ], + "query":"change(avg(last_5m),last_1h):avg:datadog.agent.running{local} by {version,host} > 40", + "options":{ + "thresholds":{ + "critical":40.0, + "warning":30.0 + }, + "notify_audit":false, + "include_tags":true, + "new_group_delay":60, + "notify_no_data":false, + "timeout_h":0, + "silenced":{ + } + }, + "multi":true, + "created_at":1706707941000, + "created":"2024-01-31T13:32:21.270116+00:00", + "modified":"2024-02-02T16:31:40.516062+00:00", + "deleted":"None"[ + "REDACTED" + ], + "restricted_roles":"None"[ + "REDACTED" + ], + "priority":5, + "overall_state_modified":"2024-03-08T20:52:46+00:00", + "overall_state":"No Data", + "creator":{ + "name":"John Doe", + "email":"john.doe@gmail.com", + "handle":"john.doe@gmail.com", + "id":1001199545 + }, + "matching_downtimes":[ + ] +} +``` + +
+
+
+Service response data
+ +```json showLineNumbers +{ + "type":"service-definition", + "id":"04fbab48-a233-4592-8c53-d1bfe282e6c3", + "attributes":{ + "meta":{ + "last-modified-time":"2024-05-29T10:31:06.833444245Z", + "github-html-url":"", + "ingestion-source":"api", + "origin":"unknown", + "origin-detail":"", + "warnings":[ + { + "keyword-location":"/properties/integrations/properties/opsgenie/properties/service-url/pattern", + "instance-location":"/integrations/opsgenie/service-url", + "message":"does not match pattern '^(https?://)?[a-zA-Z\\\\d_\\\\-.]+\\\\.opsgenie\\\\.com/service/([a-zA-Z\\\\d_\\\\-]+)/?$'" + }, + { + "keyword-location":"/properties/integrations/properties/pagerduty/properties/service-url/pattern", + "instance-location":"/integrations/pagerduty/service-url", + "message":"does not match pattern '^(https?://)?[a-zA-Z\\\\d_\\\\-.]+\\\\.pagerduty\\\\.com/service-directory/(P[a-zA-Z\\\\d_\\\\-]+)/?$'" + } + ], + "ingested-schema-version":"v2.1" + }, + "schema":{ + "schema-version":"v2.2", + "dd-service":"inventory-management", + "team":"Inventory Management Team", + "application":"Inventory System", + "tier":"Tier 1", + "description":"Service for managing product inventory and stock levels.", + "lifecycle":"production", + "contacts":[ + { + "name":"Inventory Team", + "type":"email", + "contact":"inventory-team@example.com" + }, + { + "name":"Warehouse Support", + "type":"email", + "contact":"warehouse-support@example.com" + } + ], + "links":[ + { + "name":"Repository", + "type":"repo", + "provider":"GitHub", + "url":"https://github.com/example/inventory-service" + }, + { + "name":"Runbook", + "type":"runbook", + "provider":"Confluence", + "url":"https://wiki.example.com/runbooks/inventory-service" + } + ], + "tags":[ + "inventory", + "stock" + ], + "integrations":{ + "pagerduty":{ + "service-url":"https://pagerduty.com/services/inventory" + }, + "opsgenie":{ + "service-url":"https://opsgenie.com/services/inventory", + "region":"US" + } + }, + "extensions":{ + "qui_6":{ + + } + } + } + } + } +} +``` + +
+
+
+SLO response data
+ +```json showLineNumbers +{ + "id":"b6869ae6189d59baa421feb8b437fe9e", + "name":"Availability SLO for shopping-cart service", + "tags":[ + "service:shopping-cart", + "env:none" + ], + "monitor_tags":[ + + ], + "thresholds":[ + { + "timeframe":"7d", + "target":99.9, + "target_display":"99.9" + } + ], + "type":"monitor", + "type_id":0, + "description":"This SLO tracks the availability of the shopping-cart service. Availability is measured as the number of successful requests divided by the number of total requests for the service", + "timeframe":"7d", + "target_threshold":99.9, + "monitor_ids":[ + 15173866, + 15216083, + 15254771 + ], + "creator":{ + "name":"John Doe", + "handle":"john.doe@gmail.com", + "email":"john.doe@gmail.com" + }, + "created_at":1707215619, + "modified_at":1707215619 +} +``` + +
+
+
+
+SLO history response data
+ +```json showLineNumbers +{ + "thresholds": { + "7d": { + "timeframe": "7d", + "target": 99, + "target_display": "99." + } + }, + "from_ts": 1719254776, + "to_ts": 1719859576, + "type": "monitor", + "type_id": 0, + "slo": { + "id": "5ec82408e83c54b4b5b2574ee428a26c", + "name": "Host {{host.name}} with IP {{host.ip}} is not having enough memory", + "tags": [ + "p69hx03", + "pages-laptop" + ], + "monitor_tags": [], + "thresholds": [ + { + "timeframe": "7d", + "target": 99, + "target_display": "99." + } + ], + "type": "monitor", + "type_id": 0, + "description": "Testing SLOs from DataDog", + "timeframe": "7d", + "target_threshold": 99, + "monitor_ids": [ + 147793 + ], + "creator": { + "name": "John Doe", + "handle": "janesmith@gmail.com", + "email": "janesmith@gmail.com" + }, + "created_at": 1683878238, + "modified_at": 1684773765 + }, + "overall": { + "name": "Host {{host.name}} with IP {{host.ip}} is not having enough memory", + "preview": false, + "monitor_type": "query alert", + "monitor_modified": 1683815332, + "errors": null, + "span_precision": 2, + "history": [ + [ + 1714596313, + 1 + ] + ], + "uptime": 3, + "sli_value": 10, + "precision": { + "custom": 2, + "7d": 2 + }, + "corrections": [], + "state": "breached" + } +} +``` + +
+
+
+
+### Mapping Result
+
+The combination of the sample payload and the Ocean configuration generates the following Port entity:
+
+Service metric response data
+ +:::tip Response Enrichment +The Datadog response is enriched with a variety of metadata fields, including: + +- `__service`: The name or identifier of the service generating the data. +- `__query_id`: A unique identifier for the query that generated the data. +- `__query`: The original query used to retrieve the data. +- `__env`: The environment associated with the data (e.g., production, staging). + +This enrichment significantly enhances the usability of the Datadog response by providing valuable context and facilitating easier analysis and troubleshooting. +::: + +```json showLineNumbers +{ + "status": "ok", + "res_type": "time_series", + "resp_version": 1, + "query": "avg:system.mem.used{service:inventory-management,env:staging}", + "from_date": 1723796537000, + "to_date": 1723797137000, + "series": [ + { + "unit": [ + { + "family": "bytes", + "id": 2, + "name": "byte", + "short_name": "B", + "plural": "bytes", + "scale_factor": 1.0 + } + ], + "query_index": 0, + "aggr": "avg", + "metric": "system.mem.used", + "tag_set": [], + "expression": "avg:system.mem.used{env:staging,service:inventory-management}", + "scope": "env:staging,service:inventory-management", + "interval": 2, + "length": 39, + "start": 1723796546000, + "end": 1723797117000, + "pointlist": [ + [1723796546000.0, 528986112.0], + [1723796562000.0, 531886080.0], + [1723796576000.0, 528867328.0], + [1723796592000.0, 522272768.0], + [1723796606000.0, 533704704.0], + [1723796846000.0, 533028864.0], + [1723796862000.0, 527417344.0], + [1723796876000.0, 531513344.0], + [1723796892000.0, 533577728.0], + [1723796906000.0, 533471232.0], + [1723796922000.0, 528125952.0], + [1723796936000.0, 530542592.0], + [1723796952000.0, 530767872.0], + [1723796966000.0, 526966784.0], + [1723796982000.0, 528560128.0], + [1723796996000.0, 530792448.0], + [1723797012000.0, 527384576.0], + [1723797026000.0, 529534976.0], + [1723797042000.0, 521650176.0], + [1723797056000.0, 531001344.0], + [1723797072000.0, 525955072.0], + [1723797086000.0, 529469440.0], + [1723797102000.0, 532279296.0], + [1723797116000.0, 526979072.0] + ], + "display_name": "system.mem.used", + "attributes": {} + } + ], + "values": [], + "times": [], + "message": "", + "group_by": [], + // highlight-start + "__service": "inventory-management", + "__query_id": "avg:system.mem.used/service:inventory-management/env:staging", + "__query": "avg:system.mem.used", + "__env": "staging" + // highlight-end +} +``` + +
+",
+ "updatedAt": "2024-05-29T09:43:34.750Z",
+ "updatedBy": ""
+}
+```
+
+
+
+Monitor entity in Port
+ +```json showLineNumbers +{ + "identifier": "15173866", + "title": "A change @webhook-PORT", + "icon": "Datadog", + "blueprint": "datadogMonitor", + "team": [], + "properties": { + "tags": [ + "app:webserver" + ], + "overallState": "No Data", + "priority": "5", + "createdAt": "2024-01-31T13:32:21.270116+00:00", + "updatedAt": "2024-02-02T16:31:40.516062+00:00", + "createdBy": "john.doe@gmail.com", + "monitorType": "query alert" + }, + "relations": {}, + "createdAt": "2024-05-29T09:43:34.750Z", + "createdBy": "
+",
+ "updatedAt": "2024-05-29T10:31:44.283Z",
+ "updatedBy": ""
+}
+```
+
+
+
+Service entity in Port
+ +```json showLineNumbers +{ + "identifier": "inventory-management", + "title": "inventory-management", + "icon": "Datadog", + "blueprint": "datadogService", + "team": [], + "properties": { + "owners": [ + "inventory-team@example.com", + "warehouse-support@example.com" + ], + "links": [ + "https://github.com/example/inventory-service", + "https://wiki.example.com/runbooks/inventory-service" + ], + "description": "Service for managing product inventory and stock levels.", + "tags": [ + "inventory", + "stock" + ], + "application": "Inventory System" + }, + "relations": {}, + "createdAt": "2024-05-29T10:31:44.283Z", + "createdBy": "
+",
+ "updatedAt": "2024-05-29T12:02:01.559Z",
+ "updatedBy": ""
+}
+```
+
+
+
+SLO entity in Port
+ +```json showLineNumbers +{ + "identifier": "b6869ae6189d59baa421feb8b437fe9e", + "title": "Availability SLO for shopping-cart service", + "icon": "Datadog", + "blueprint": "datadogSlo", + "team": [], + "properties": { + "description": "This SLO tracks the availability of the shopping-cart service. Availability is measured as the number of successful requests divided by the number of total requests for the service", + "updatedAt": "2024-02-06T10:33:39Z", + "createdBy": "ahosea15@gmail.com", + "sloType": "monitor", + "targetThreshold": "99.9", + "tags": [ + "service:shopping-cart", + "env:none" + ], + "createdAt": "2024-02-06T10:33:39Z" + }, + "relations": { + "monitors": [ + "15173866", + "15216083", + "15254771" + ], + "services": [ + "shopping-cart" + ] + }, + "createdAt": "2024-05-29T09:43:51.946Z", + "createdBy": "
+",
+ "updatedAt": "2024-07-01T12:02:01.559Z",
+ "updatedBy": ""
+}
+```
+
+
+
+SLO history entity in Port
+ +```json showLineNumbers +{ + "identifier": "5ec82408e83c54b4b5b2574ee428a26c", + "title": "Host {{host.name}} with IP {{host.ip}} is not having enough memory", + "icon": "Datadog", + "blueprint": "datadogSloHistory", + "team": [], + "properties": { + "sampling_end_date": "2024-07-01T18:46:16Z", + "sliValue": 10, + "sampling_start_date": "2024-06-24T18:46:16Z" + }, + "relations": { + "slo": "5ec82408e83c54b4b5b2574ee428a26c" + }, + "createdAt": "2024-07-01T09:43:51.946Z", + "createdBy": "
+",
+ "updatedAt": "2024-08-16T08:02:02.399Z",
+ "updatedBy": ""
+}
+```
+
+
## Relevant Guides
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/example.md b/docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/examples.md
similarity index 97%
rename from docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/example.md
rename to docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/examples.md
index d7c27e94e..2dbe71d25 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/example.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/apm-alerting/datadog/examples.md
@@ -410,6 +410,12 @@ Based on the [best practices for tagging infrastructure](https://www.datadoghq.c
Service metric entity in Port
+ +```json showLineNumbers +{ + "identifier": "avg:system.disk.used/service:inventory-management/env:prod", + "title": "avg:system.disk.used{service:inventory-management,env:prod}", + "icon": null, + "blueprint": "datadogServiceMetric", + "team": [], + "properties": { + "query": "avg:system.disk.used", + "series": [], + "res_type": "time_series", + "from_date": "2024-08-16T07:32:00Z", + "to_date": "2024-08-16T08:02:00Z", + "env": "prod" + }, + "relations": { + "service": "inventory-management" + }, + "createdAt": "2024-08-15T15:54:36.638Z", + "createdBy": "Integration configuration
+:::tip Configuration Options +The SLO history selector supports two time-related configurations: +- `timeframe`: How many days to look back for each SLO history data point. Must be greater than 0 (default: 7 days) +- `periodOfTimeInMonths`: How far back in time to fetch SLO history. Must be between 1-12 months (default: 6 months) +::: + ```yaml showLineNumbers createMissingRelatedEntities: true deleteDependentEntities: true @@ -417,7 +423,8 @@ resources: - kind: sloHistory selector: query: 'true' - sampleIntervalPeriodInDays: 7 + timeframe: 7 + periodOfTimeInMonths: 6 port: entity: mappings: @@ -433,10 +440,6 @@ resources: slo: .slo.id ``` -:::tip Service Relation -Based on the [best practices for tagging infrastructure](https://www.datadoghq.com/blog/tagging-best-practices/), the default JQ maps SLOs to services using tags that starts with the `service` keyword -::: -Prerequisites
+ ++ +For details about the available parameters for the installation, see the table below.
@@ -214,15 +232,10 @@ jobs:
@@ -336,13 +348,7 @@ steps: ```
Prerequisites
-| Parameter | Description | Required | -| --------------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | -| `port.clientId` | Your port client id | ✅ | -| `port.clientSecret` | Your port client secret | ✅ | -| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | ✅ | -| `integration.identifier` | Change the identifier to describe your integration | ✅ | -| `integration.type` | The integration type | ✅ | -| `integration.eventListener.type` | The event listener type | ✅ | -| `integration.secrets.newRelicAPIKey` | The New Relic API key | ✅ | -| `integration.secrets.newRelicAccountID` | The New Relic account ID | ✅ | -| `scheduledResyncInterval` | The number of minutes between each resync | ❌ | -| `initializePortResources` | Default true, When set to true the integration will create default blueprints and the port App config Mapping | ❌ | ++
Event listener
@@ -205,15 +195,17 @@ The integration uses polling to pull the configuration from Port every minute an+
Prerequisites
+ ++
Event listener
@@ -181,15 +183,17 @@ The integration uses polling to pull the configuration from Port every minute an
+
+
+ 2. Apply the manifest with `kubectl` to create the user:
+
+ ```bash
+ kubectl apply -f argocd-user.yaml
+ ```
+
+ 3. Grant read only RBAC policy to the new user using the below manifest file (`argocd-rbac-cm.yaml`)
-## Common use cases
+ Create user manifest (click to expand)
+ + ```yaml showLineNumbers + apiVersion: v1 + kind: ConfigMap + metadata: + name: argocd-cm + namespace: argocd + labels: + app.kubernetes.io/name: argocd-cm + app.kubernetes.io/part-of: argocd + data: + # add an additional local user with apiKey and login capabilities + # apiKey - allows generating API keys + # login - allows to login using UI + accounts.port-ocean-user: apiKey, login + accounts.port-ocean-user.enabled: "true" + ``` +
+
-- Map your monitored Kubernetes resources in ArgoCD.
-- Watch for object changes (create/update) in real-time, and automatically apply the changes to your entities in Port.
+ 4. Apply the `argocd-rbac-cm.yaml` manifest with `kubectl`:
-## Installation
+ ```bash
+ kubectl apply -f argocd-rbac-cm.yaml
+ ```
+
+ 5. Go to your ArgoCD UI to generate a new token for the user or use the CLI
+ ```bash
+ argocd account generate-token --account RBAC policy to grant readonly role to the new user (click to expand)
+ + ```yaml showLineNumbers + apiVersion: v1 + kind: ConfigMap + metadata: + name: argocd-rbac-cm + namespace: argocd + data: + policy.default: role:readonly + policy.csv: | + p, role:read-only-role, applications, *, */*, allow + p, role:read-only-role, clusters, get, *, allow + p, role:read-only-role, repositories, get, *, allow + p, role:read-only-role, projects, get, *, allow + p, role:read-only-role, logs, get, *, allow + + g, port-ocean-user, role:read-only-role + ``` +Prerequisites
-+
@@ -214,15 +310,10 @@ jobs:
@@ -358,231 +444,39 @@ ingest_data:
-
-
-2. Apply the manifest with `kubectl` to create the user:
-```bash
-kubectl apply -f argocd-user.yaml
-```
-3. Grant read only RBAC policy to the new user using the below manifest file (`argocd-rbac-cm.yaml`)
-Create user manifest (click to expand)
- -```yaml showLineNumbers -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-cm - namespace: argocd - labels: - app.kubernetes.io/name: argocd-cm - app.kubernetes.io/part-of: argocd -data: - # add an additional local user with apiKey and login capabilities - # apiKey - allows generating API keys - # login - allows to login using UI - accounts.port-ocean-user: apiKey, login - accounts.port-ocean-user.enabled: "true" -``` -
-
-
-4. Apply the `argocd-rbac-cm.yaml` manifest with `kubectl`:
-```bash
-kubectl apply -f argocd-rbac-cm.yaml
-```
+The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
-5. Go to your ArgoCD UI to generate a new token for the user or use the CLI
-```bash
-argocd account generate-token --account RBAC policy to grant readonly role to the new user (click to expand)
- -```yaml showLineNumbers -apiVersion: v1 -kind: ConfigMap -metadata: - name: argocd-rbac-cm - namespace: argocd -data: - policy.default: role:readonly - policy.csv: | - p, role:read-only-role, applications, *, */*, allow - p, role:read-only-role, clusters, get, *, allow - p, role:read-only-role, repositories, get, *, allow - p, role:read-only-role, projects, get, *, allow - p, role:read-only-role, logs, get, *, allow - - g, port-ocean-user, role:read-only-role -``` -
-
-
-Cluster blueprint
- -```json showLineNumbers - { - "identifier": "argocdCluster", - "description": "This blueprint represents an ArgoCD cluster", - "title": "ArgoCD Cluster", - "icon": "Argo", - "schema": { - "properties": { - "applicationsCount": { - "title": "Applications Count", - "type": "number", - "description": "The number of applications managed by Argo CD on the cluster", - "icon": "DefaultProperty" - }, - "serverVersion": { - "title": "Server Version", - "type": "string", - "description": "Contains information about the Kubernetes version of the cluster", - "icon": "DefaultProperty" - }, - "labels": { - "title": "Labels", - "type": "object", - "description": "Contains information about cluster metadata", - "icon": "DefaultProperty" - }, - "updatedAt": { - "icon": "DefaultProperty", - "title": "Updated At", - "type": "string", - "format": "date-time" - }, - "server": { - "title": "Server", - "description": "The API server URL of the Kubernetes cluster", - "type": "string", - "icon": "DefaultProperty" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": {} - } -``` - -
-
-
-### Namespace
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: cluster - selector: - query: "true" - port: - entity: - mappings: - identifier: .name - title: .name - blueprint: '"argocdCluster"' - properties: - applicationsCount: .info.applicationsCount - serverVersion: .serverVersion - labels: .labels - updatedAt: .connectionState.attemptedAt - server: .server -``` - -
-
-
-Namespace blueprint
- -```json showLineNumbers - { - "identifier": "argocdNamespace", - "description": "This blueprint represents an ArgoCD namespace", - "title": "ArgoCD Namespace", - "icon": "Argo", - "schema": { - "properties": {}, - "required": [] - }, - "aggregationProperties": {}, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "cluster": { - "title": "ArgoCD Cluster", - "target": "argocdCluster", - "required": false, - "many": false - } - } - } -``` - -
-
-
-### Project
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: cluster - selector: - query: "true" - port: - itemsToParse: .namespaces - entity: - mappings: - identifier: .name + "-" + .item | tostring - title: .name + "-" + .item - blueprint: '"argocdNamespace"' - properties: {} - relations: - cluster: .name -``` - -
-
-
-Project blueprint
- -```json showlineNumbers - { - "identifier": "argocdProject", - "description": "This blueprint represents an ArgoCD Project", - "title": "ArgoCD Project", - "icon": "Argo", - "schema": { - "properties": { - "createdAt": { - "title": "Created At", - "type": "string", - "format": "date-time", - "icon": "DefaultProperty" - }, - "description": { - "title": "Description", - "description": "Project description", - "type": "string", - "icon": "DefaultProperty" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": {} - } -``` - -
-
+## Relevant Guides
-### Application
-
-Integration configuration
+To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your [data sources page](https://app.getport.io/settings/data-sources). Find the integration in the list of data sources and click on it to open the playground. -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: project - selector: - query: "true" - port: - entity: - mappings: - identifier: .metadata.name - title: .metadata.name - blueprint: '"argocdProject"' - properties: - createdAt: .metadata.creationTimestamp - description: .spec.description -``` +Examples of blueprints and the relevant integration configurations can be found on the argocd [examples page](example.md) -
-
-
-Application blueprint
- -```json showlineNumbers - { - "identifier": "argocdApplication", - "description": "This blueprint represents an ArgoCD Application", - "title": "Running Service", - "icon": "Argo", - "schema": { - "properties": { - "gitRepo": { - "type": "string", - "icon": "Git", - "title": "Repository URL", - "description": "The URL of the Git repository containing the application source code" - }, - "gitPath": { - "type": "string", - "title": "Path", - "description": "The path within the Git repository where the application manifests are located" - }, - "destinationServer": { - "type": "string", - "title": "Destination Server", - "description": "The URL of the target cluster's Kubernetes control plane API" - }, - "revision": { - "type": "string", - "title": "Revision", - "description": "Revision contains information about the revision the comparison has been performed to" - }, - "targetRevision": { - "type": "string", - "title": "Target Revision", - "description": "Target Revision defines the revision of the source to sync the application to. In case of Git, this can be commit, tag, or branch" - }, - "syncStatus": { - "type": "string", - "title": "Sync Status", - "enum": [ - "Synced", - "OutOfSync", - "Unknown" - ], - "enumColors": { - "Synced": "green", - "OutOfSync": "red", - "Unknown": "lightGray" - }, - "description": "Status is the sync state of the comparison" - }, - "healthStatus": { - "type": "string", - "title": "Health Status", - "enum": [ - "Healthy", - "Missing", - "Suspended", - "Degraded", - "Progressing", - "Unknown" - ], - "enumColors": { - "Healthy": "green", - "Missing": "yellow", - "Suspended": "purple", - "Degraded": "red", - "Progressing": "blue", - "Unknown": "lightGray" - }, - "description": "Status holds the status code of the application or resource" - }, - "createdAt": { - "title": "Created At", - "type": "string", - "format": "date-time", - "description": "The created timestamp of the application" - }, - "labels": { - "type": "object", - "title": "Labels", - "description": "Map of string keys and values that can be used to organize and categorize object" - }, - "annotations": { - "type": "object", - "title": "Annotations", - "description": "Annotations are unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "project": { - "title": "ArgoCD Project", - "target": "argocdProject", - "required": false, - "many": false - }, - "cluster": { - "title": "ArgoCD Cluster", - "target": "argocdCluster", - "required": false, - "many": false - }, - "namespace": { - "title": "ArgoCD Namespace", - "target": "argocdNamespace", - "required": false, - "many": false - } - } - } -``` - -
-
-
-### Deployment history
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: application - selector: - query: "true" - port: - entity: - mappings: - identifier: .metadata.uid - title: .metadata.name - blueprint: '"argocdApplication"' - properties: - gitRepo: .spec.source.repoURL - gitPath: .spec.source.path - destinationServer: .spec.destination.server - revision: .status.sync.revision - targetRevision: .spec.source.targetRevision - syncStatus: .status.sync.status - healthStatus: .status.health.status - createdAt: .metadata.creationTimestamp - labels: .metadata.labels - annotations: .metadata.annotations - relations: - project: .spec.project - namespace: .metadata.namespace - cluster: .spec.destination.name -``` - -
-
-
-Deployment history blueprint
- -```json showlineNumbers - { - "identifier": "argocdDeploymentHistory", - "description": "This blueprint represents an ArgoCD deployment history", - "title": "ArgoCD Deployment History", - "icon": "Argo", - "schema": { - "properties": { - "deployedAt": { - "title": "Deployed At", - "type": "string", - "format": "date-time" - }, - "deployStartedAt": { - "title": "Deploy Started At", - "type": "string", - "format": "date-time" - }, - "revision": { - "title": "Revision", - "type": "string" - }, - "initiatedBy": { - "title": "Initiated By", - "type": "string" - }, - "repoURL": { - "title": "Repository URL", - "type": "string" - }, - "sourcePath": { - "title": "Source Path", - "type": "string" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "application": { - "title": "Application", - "target": "argocdApplication", - "required": false, - "many": false - } - } - } -``` - -
-
-
-### Kubernetes Resource
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: application - selector: - query: "true" - port: - itemsToParse: .status.history - entity: - mappings: - identifier: .metadata.uid + "-" + (.item.id | tostring) - title: .metadata.name + "-" + (.item.id | tostring) - blueprint: '"argocdDeploymentHistory"' - properties: - deployedAt: .item.deployedAt - deployStartedAt: .item.deployStartedAt - revision: .item.source.repoURL + "/commit/" + .item.revision - initiatedBy: .item.initiatedBy.username - repoURL: .item.source.repoURL - sourcePath: .item.source.path - relations: - application: .metadata.uid -``` - -
-
-
-Images blueprint
- -```json showlineNumbers - { - "identifier": "image", - "description": "This blueprint represents an image", - "title": "Image", - "icon": "AWS", - "schema": { - "properties": {}, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": {} - } -``` - -
-
-
-
-Kubernetes resource blueprint
- -```json showlineNumbers - { - "identifier": "argocdKubernetesResource", - "description": "This blueprint represents an ArgoCD kubernetes resource", - "title": "Kubernetes Resource", - "icon": "Argo", - "schema": { - "properties": { - "kind": { - "title": "Kind", - "type": "string" - }, - "version": { - "title": "Version", - "type": "string" - }, - "namespace": { - "title": "Namespace", - "type": "string" - }, - "labels": { - "type": "object", - "title": "Labels" - }, - "annotations": { - "type": "object", - "title": "Annotations" - } - }, - "required": [] - }, - "mirrorProperties": { - "healthStatus": { - "title": "Health Status", - "path": "application.healthStatus" - }, - "syncStatus": { - "title": "Sync Status", - "path": "application.syncStatus" - } - }, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "application": { - "title": "Application", - "target": "argocdApplication", - "required": false, - "many": false - }, - "image": { - "title": "Image", - "target": "image", - "required": false, - "many": false - } - } - } -``` - -
-
+For relevant guides and examples, see the [guides section](https://docs.getport.io/guides?tags=ArgoCD).
## Alternative installation via webhook
@@ -1285,25 +619,25 @@ To set up a webhook configuration in ArgoCD for sending notifications to Port, f
1. Install ArgoCD notifications manifest;
-```bash showLineNumbers
+```bash
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/manifests/install.yaml
```
2. Install ArgoCD triggers and templates manifest;
-```bash showLineNumbers
+```bash
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj-labs/argocd-notifications/release-1.0/catalog/install.yaml
```
3. Use `kubectl` to connect to the Kubernetes cluster where your ArgoCD instance is deployed;
-```bash showLineNumbers
+```bash
kubectl config use-context Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: managed-resource - selector: - query: "true" - port: - entity: - mappings: - identifier: .__application.metadata.uid + "-" + .kind + "-" + .name - title: .__application.metadata.name + "-" + .kind + "-" + .name - blueprint: '"argocdKubernetesResource"' - properties: - kind: .kind - namespace: .namespace - version: .resourceVersion - annotations: .liveState | fromjson | .metadata.annotations - labels: .liveState | fromjson | .metadata.labels - relations: - application: .__application.metadata.uid - image: 'if .kind == "Deployment" then .liveState | fromjson | .spec.template.spec.containers[0].image else null end' -``` -
+
+
+Cluster blueprint
+ +```json showLineNumbers + { + "identifier": "argocdCluster", + "description": "This blueprint represents an ArgoCD cluster", + "title": "ArgoCD Cluster", + "icon": "Argo", + "schema": { + "properties": { + "applicationsCount": { + "title": "Applications Count", + "type": "number", + "description": "The number of applications managed by Argo CD on the cluster", + "icon": "DefaultProperty" + }, + "serverVersion": { + "title": "Server Version", + "type": "string", + "description": "Contains information about the Kubernetes version of the cluster", + "icon": "DefaultProperty" + }, + "labels": { + "title": "Labels", + "type": "object", + "description": "Contains information about cluster metadata", + "icon": "DefaultProperty" + }, + "updatedAt": { + "icon": "DefaultProperty", + "title": "Updated At", + "type": "string", + "format": "date-time" + }, + "server": { + "title": "Server", + "description": "The API server URL of the Kubernetes cluster", + "type": "string", + "icon": "DefaultProperty" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": {} + } +``` + +
+
+
+## Namespace
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: cluster + selector: + query: "true" + port: + entity: + mappings: + identifier: .name + title: .name + blueprint: '"argocdCluster"' + properties: + applicationsCount: .info.applicationsCount + serverVersion: .serverVersion + labels: .labels + updatedAt: .connectionState.attemptedAt + server: .server +``` + +
+
+
+Namespace blueprint
+ +```json showLineNumbers + { + "identifier": "argocdNamespace", + "description": "This blueprint represents an ArgoCD namespace", + "title": "ArgoCD Namespace", + "icon": "Argo", + "schema": { + "properties": {}, + "required": [] + }, + "aggregationProperties": {}, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "cluster": { + "title": "ArgoCD Cluster", + "target": "argocdCluster", + "required": false, + "many": false + } + } + } +``` + +
+
+
+## Project
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: cluster + selector: + query: "true" + port: + itemsToParse: .namespaces + entity: + mappings: + identifier: .name + "-" + .item | tostring + title: .name + "-" + .item + blueprint: '"argocdNamespace"' + properties: {} + relations: + cluster: .name +``` + +
+
+
+Project blueprint
+ +```json showlineNumbers + { + "identifier": "argocdProject", + "description": "This blueprint represents an ArgoCD Project", + "title": "ArgoCD Project", + "icon": "Argo", + "schema": { + "properties": { + "createdAt": { + "title": "Created At", + "type": "string", + "format": "date-time", + "icon": "DefaultProperty" + }, + "description": { + "title": "Description", + "description": "Project description", + "type": "string", + "icon": "DefaultProperty" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": {} + } +``` + +
+
+
+## Application
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: project + selector: + query: "true" + port: + entity: + mappings: + identifier: .metadata.name + title: .metadata.name + blueprint: '"argocdProject"' + properties: + createdAt: .metadata.creationTimestamp + description: .spec.description +``` + +
+
+
+Application blueprint
+ +```json showlineNumbers + { + "identifier": "argocdApplication", + "description": "This blueprint represents an ArgoCD Application", + "title": "Running Service", + "icon": "Argo", + "schema": { + "properties": { + "gitRepo": { + "type": "string", + "icon": "Git", + "title": "Repository URL", + "description": "The URL of the Git repository containing the application source code" + }, + "gitPath": { + "type": "string", + "title": "Path", + "description": "The path within the Git repository where the application manifests are located" + }, + "destinationServer": { + "type": "string", + "title": "Destination Server", + "description": "The URL of the target cluster's Kubernetes control plane API" + }, + "revision": { + "type": "string", + "title": "Revision", + "description": "Revision contains information about the revision the comparison has been performed to" + }, + "targetRevision": { + "type": "string", + "title": "Target Revision", + "description": "Target Revision defines the revision of the source to sync the application to. In case of Git, this can be commit, tag, or branch" + }, + "syncStatus": { + "type": "string", + "title": "Sync Status", + "enum": [ + "Synced", + "OutOfSync", + "Unknown" + ], + "enumColors": { + "Synced": "green", + "OutOfSync": "red", + "Unknown": "lightGray" + }, + "description": "Status is the sync state of the comparison" + }, + "healthStatus": { + "type": "string", + "title": "Health Status", + "enum": [ + "Healthy", + "Missing", + "Suspended", + "Degraded", + "Progressing", + "Unknown" + ], + "enumColors": { + "Healthy": "green", + "Missing": "yellow", + "Suspended": "purple", + "Degraded": "red", + "Progressing": "blue", + "Unknown": "lightGray" + }, + "description": "Status holds the status code of the application or resource" + }, + "createdAt": { + "title": "Created At", + "type": "string", + "format": "date-time", + "description": "The created timestamp of the application" + }, + "labels": { + "type": "object", + "title": "Labels", + "description": "Map of string keys and values that can be used to organize and categorize object" + }, + "annotations": { + "type": "object", + "title": "Annotations", + "description": "Annotations are unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "project": { + "title": "ArgoCD Project", + "target": "argocdProject", + "required": false, + "many": false + }, + "cluster": { + "title": "ArgoCD Cluster", + "target": "argocdCluster", + "required": false, + "many": false + }, + "namespace": { + "title": "ArgoCD Namespace", + "target": "argocdNamespace", + "required": false, + "many": false + } + } + } +``` + +
+
+
+## Deployment history
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: application + selector: + query: "true" + port: + entity: + mappings: + identifier: .metadata.uid + title: .metadata.name + blueprint: '"argocdApplication"' + properties: + gitRepo: .spec.source.repoURL + gitPath: .spec.source.path + destinationServer: .spec.destination.server + revision: .status.sync.revision + targetRevision: .spec.source.targetRevision + syncStatus: .status.sync.status + healthStatus: .status.health.status + createdAt: .metadata.creationTimestamp + labels: .metadata.labels + annotations: .metadata.annotations + relations: + project: .spec.project + namespace: .metadata.namespace + cluster: .spec.destination.name +``` + +
+
+
+Deployment history blueprint
+ +```json showlineNumbers + { + "identifier": "argocdDeploymentHistory", + "description": "This blueprint represents an ArgoCD deployment history", + "title": "ArgoCD Deployment History", + "icon": "Argo", + "schema": { + "properties": { + "deployedAt": { + "title": "Deployed At", + "type": "string", + "format": "date-time" + }, + "deployStartedAt": { + "title": "Deploy Started At", + "type": "string", + "format": "date-time" + }, + "revision": { + "title": "Revision", + "type": "string" + }, + "initiatedBy": { + "title": "Initiated By", + "type": "string" + }, + "repoURL": { + "title": "Repository URL", + "type": "string" + }, + "sourcePath": { + "title": "Source Path", + "type": "string" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "application": { + "title": "Application", + "target": "argocdApplication", + "required": false, + "many": false + } + } + } +``` + +
+
+
+## Kubernetes Resource
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: application + selector: + query: "true" + port: + itemsToParse: .status.history + entity: + mappings: + identifier: .metadata.uid + "-" + (.item.id | tostring) + title: .metadata.name + "-" + (.item.id | tostring) + blueprint: '"argocdDeploymentHistory"' + properties: + deployedAt: .item.deployedAt + deployStartedAt: .item.deployStartedAt + revision: .item.source.repoURL + "/commit/" + .item.revision + initiatedBy: .item.initiatedBy.username + repoURL: .item.source.repoURL + sourcePath: .item.source.path + relations: + application: .metadata.uid +``` + +
+
+
+Images blueprint
+ +```json showlineNumbers + { + "identifier": "image", + "description": "This blueprint represents an image", + "title": "Image", + "icon": "AWS", + "schema": { + "properties": {}, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} + } +``` + +
+
+
+
+Kubernetes resource blueprint
+ +```json showlineNumbers + { + "identifier": "argocdKubernetesResource", + "description": "This blueprint represents an ArgoCD kubernetes resource", + "title": "Kubernetes Resource", + "icon": "Argo", + "schema": { + "properties": { + "kind": { + "title": "Kind", + "type": "string" + }, + "version": { + "title": "Version", + "type": "string" + }, + "namespace": { + "title": "Namespace", + "type": "string" + }, + "labels": { + "type": "object", + "title": "Labels" + }, + "annotations": { + "type": "object", + "title": "Annotations" + } + }, + "required": [] + }, + "mirrorProperties": { + "healthStatus": { + "title": "Health Status", + "path": "application.healthStatus" + }, + "syncStatus": { + "title": "Sync Status", + "path": "application.syncStatus" + } + }, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "application": { + "title": "Application", + "target": "argocdApplication", + "required": false, + "many": false + }, + "image": { + "title": "Image", + "target": "image", + "required": false, + "many": false + } + } + } +``` + +
+
\ No newline at end of file
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cicd/octopus-deploy/octopus-deploy.md b/docs/build-your-software-catalog/sync-data-to-catalog/cicd/octopus-deploy/octopus-deploy.md
index 77b9a4bc1..b87052b0c 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/cicd/octopus-deploy/octopus-deploy.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/cicd/octopus-deploy/octopus-deploy.md
@@ -10,18 +10,31 @@ import DockerParameters from "./\_octopus-deploy-docker-parameters.mdx"
import AdvancedConfig from '../../../../generalTemplates/_ocean_advanced_configuration_note.md'
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "./\_octopus_deploy_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+
# Octopus Deploy Integration
-Port's Octopus Deploy integration allows you to import `spaces`, `projects`, `releases`, `deployments`, and `machines` from Octopus Deploy into Port based on your mappings and definitions.
+Port's Octopus Deploy integration allows you to model Octopus Deploy resources in your software catalog and ingest data into them.
+
+## Overview
+
+This integration allows you to:
+
+- Map and organize your desired Octopus Deploy resources and their metadata in Port (see supported resources below).
+- Watch for Octopus Deploy object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
-## Common Use Cases
+### Supported Resources
-- Map `spaces`, `projects`, `releases`, `deployments`, and `machines` from Octopus Deploy to Port.
-- Monitor real-time changes (create/update/delete) in Octopus Deploy and automatically sync them with your entities in Port.
+The resources that can be ingested from Octopus Deploy into Port are listed below. It is possible to reference any field that appears in the API responses linked below in the mapping configuration.
+- [`Space`](https://octopus.com/docs/octopus-rest-api/examples/spaces)
+- [`Project`](https://octopus.com/docs/octopus-rest-api/examples/projects)
+- [`Release`](https://octopus.com/docs/octopus-rest-api/examples/releases)
+- [`Deployment`](https://octopus.com/docs/octopus-rest-api/examples/deployments)
-## Installation
+
+## Setup
Choose one of the following installation methods:
@@ -33,55 +46,28 @@ Choose one of the following installation methods:
Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: managed-resource + selector: + query: "true" + port: + entity: + mappings: + identifier: .__application.metadata.uid + "-" + .kind + "-" + .name + title: .__application.metadata.name + "-" + .kind + "-" + .name + blueprint: '"argocdKubernetesResource"' + properties: + kind: .kind + namespace: .namespace + version: .resourceVersion + annotations: .liveState | fromjson | .metadata.annotations + labels: .liveState | fromjson | .metadata.labels + relations: + application: .__application.metadata.uid + image: 'if .kind == "Deployment" then .liveState | fromjson | .spec.template.spec.containers[0].image else null end' +``` +Prerequisites
-| Parameter | Description | Required | -|-------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| -------- | -| `port.clientId` | Your port client id ([Get the credentials](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | ✅ | -| `port.clientSecret` | Your port client secret ([Get the credentials](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) | ✅ | -| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | ✅ | -| `integration.identifier` | Change the identifier to describe your integration | ✅ | -| `integration.type` | The integration type | ✅ | -| `integration.eventListener.type` | The event listener type | ✅ | -| `integration.secrets.octopusApiKey` | The Octopus API Key | ✅ | -| `integration.config.serverUrl` | The Octopus host | ✅ | -| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Octopus | ❌ | -| `scheduledResyncInterval` | The number of minutes between each resync | ❌ | -| `initializePortResources` | Default true, When set to true the integration will create default blueprints and the port App config Mapping | ❌ | -| `sendRawDataExamples` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | ❌ | ++For details about the available parameters for the installation, see the table below.
+
@@ -319,13 +323,7 @@ steps: ```
+Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port.
+The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API.
-## Ingesting Octopus Objects
-
-The Octopus integration uses a YAML configuration to define how data is loaded into the developer portal.
-
-Below is an example snippet from the configuration that shows how to retrieve `space` data from Octopus:
-
-
-```yaml showLineNumbers
-createMissingRelatedEntities: true
-deleteDependentEntities: true
-resources:
- - kind: space
- selector:
- query: "true"
- port:
- entity:
- mappings:
- identifier: .Id
- title: .Name
- blueprint: '"octopusSpace"'
- properties:
- url: env.OCEAN__INTEGRATION__CONFIG__SERVER_URL + "/app#/" + .Id
- description: .Description
-```
-
-The integration makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from Octopus's API events.
-
-
-### Ingest data into Port
-
-To ingest Octopus objects using the [integration configuration](/build-your-software-catalog/customize-integrations/configure-mapping), you can follow the steps below:
-
-1. Go to the DevPortal Builder page.
-2. Select a blueprint you want to ingest using Octopus.
-3. Choose the **Ingest Data** option from the menu.
-4. Click the Octopus integration to open the edit page.
-5. Modify the [configuration](/build-your-software-catalog/customize-integrations/configure-mapping) according to your needs.
-6. Click `Resync`.
## Examples
@@ -567,7 +523,6 @@ resources:
-
### Release
@@ -644,7 +599,6 @@ resources:
-
### Deployment
@@ -727,7 +681,6 @@ resources:
-
### Machine
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/gcp/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/gcp/installation.md
index 7dd8e499b..602b2055b 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/gcp/installation.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/cloud-providers/gcp/installation.md
@@ -320,6 +320,7 @@ gcp_ocean_integration_image = "/port-ocean-g
gcp_organization = ""
gcp_ocean_setup_project = ""
gcp_included_projects = [""] # The Project list that the integration digests resources from.
+gcp_project_filter = "" # The filter string used to retrieve GCP projects, allowing complex filtering by combining multiple conditions with logical operators (AND | OR).
integration_identifier = "gcp"
scheduled_resync_interval = 1440
event_listener = {
@@ -345,8 +346,9 @@ The Port GCP integration's Terraform module offers a set of configurations:
| `gcp_ocean_integration_image` | | True | The Artifact Registry / Dockerhub image to deploy. |
| `integration_identifier` | | True | The Integration's identifier in Port |
| `port_base_url` | 'https://api.getport.io' | False | The Port Base url. |
-| `gcp_included_projects` | [] | False | The Projects list you want the integration to collect from. If left empty, It will collect *All* projects in the organization. |
-| `gcp_excluded_projects` | [] | False | The Projects list you want the integration NOT to collect from. This will be overriden by any value in gcp_included_projects besides []. |
+| `gcp_included_projects` | [] | False | The Projects list you want the integration to collect from. If left empty, It will collect *All* projects in the organization. `This option will be deprecated soon.` |
+| `gcp_project_filter` | | False | The filter string used to retrieve GCP projects, allowing complex filtering by combining multiple conditions with logical operators. Follows GCP's [filter expressions syntax](https://registry.terraform.io/providers/hashicorp/google/latest/docs/data-sources/projects#filter-1). Example `parent.id:184606565139 labels.environment:production AND labels.team:devops OR labels priority:high` |
+| `gcp_excluded_projects` | [] | False | The Projects list you want the integration NOT to collect from. This will be overriden by any value in gcp_included_projects besides []. `This option will be deprecated soon.` |
| `assets_types_for_monitoring` | ["cloudresourcemanager.googleapis.com/Organization", "cloudresourcemanager.googleapis.com/Project", "storage.googleapis.com/Bucket", "cloudfunctions.googleapis.com/Function", "pubsub.googleapis.com/Subscription", "pubsub.googleapis.com/Topic"] | False | The list of asset types the integration will digest real-time events for. |
| `ocean_integration_service_account_permissions` | ["cloudasset.assets.exportResource", "cloudasset.assets.listCloudAssetFeeds", "cloudasset.assets.listResource", "cloudasset.assets.searchAllResources", "cloudasset.feeds.create", "cloudasset.feeds.list", "pubsub.topics.list", "pubsub.topics.get", "pubsub.subscriptions.list", "pubsub.subscriptions.get", "resourcemanager.projects.get", "resourcemanager.projects.list", "resourcemanager.folders.get", "resourcemanager.folders.list", "resourcemanager.organizations.get", "cloudquotas.quotas.get", "run.routes.invoke", "run.jobs.run"] | False | The permissions granted to the integration's service_account. We recommend not changing it to prevent unexpected errors. |
| `assets_feed_topic_id` | "ocean-integration-topic" | False | The name of the topic created to recieve real time events. |
@@ -362,6 +364,41 @@ The Port GCP integration's Terraform module offers a set of configurations:
| `scheduled_resync_interval` | 1440 | False | The interval to resync the integration (in minutes). |
| `ocean_service_account_custom_roles` | [] | False | A list of custom roles you want to grant the Integration's Service account. The module will grant these permissions to every available project and to the setup project `gcp_ocean_setup_project`. Example value: ["organizations/1234567890/roles/MyCustomRole", "organizations/1234567890/roles/MyOtherCustomRole"] |
+
Optional - Project Filtering
+ +You have the option to specify which projects are included or excluded for real-time events. This can be particularly useful when you have a large number of projects and want to target specific ones based on certain criteria. + +:::warning Deprecation Notice +The variables `gcp_included_projects` and `gcp_excluded_projects` are deprecated and will be removed in future releases. We recommend using the gcp_project_filter variable for project filtering moving forward. +::: + +You can use the following three filtering strategies together: + +- `gcp_excluded_projects` +- `gcp_included_projects` +- `gcp_project_filter` + +However, please note the priority conditions when using them simultaneously. + +Priority Conditions
+You can use all three filtering strategies together, but it's important to understand how they interact. The following priority conditions apply: + +- **gcp_included_projects (Highest Priority):** + - When specified, only the projects listed in `gcp_included_projects` are included. + - All other filters (`gcp_excluded_projects` and `gcp_project_filter`) are ignored. + - Use this when you have a specific list of projects to include, regardless of other criteria. + +- **gcp_excluded_projects:** + - If `gcp_included_projects` is not specified but `gcp_excluded_projects` is provided, all projects are included except those listed. + - The `gcp_project_filter` is still applied, further refining the included projects. + +- **gcp_project_filter:** + - If neither `gcp_included_projects` nor `gcp_excluded_projects` are specified, and `gcp_project_filter` is provided, only projects matching the filter criteria are included. + - This allows for flexible and complex filtering using GCP's native filtering syntax. + +- **Default Behavior (Lowest Priority):** + - If none of the above variables are specified, all projects in your GCP organization are included by default. +Optional - Scaling the permissions
If you want the integration to collect resources from multiple projects/folders or to have it collect from the entire organization, you need to have permissions to create/view additional resources. Follow these instructions to make sure you are equipped with enough permissions. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/examples.md new file mode 100644 index 000000000..f32e9d2a0 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/examples.md @@ -0,0 +1,539 @@ +--- +sidebar_position: 2 +--- + +# Examples +To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your [data sources page](https://app.getport.io/settings/data-sources). Find the integration in the list of data sources and click on it to open the playground. + +## Project + +
+
+
+Projects blueprint (Click to expand)
+ +```json showLineNumbers +{ + "identifier": "sonarQubeProject", + "title": "SonarQube Project", + "icon": "sonarqube", + "schema": { + "properties": { + "organization": { + "type": "string", + "title": "Organization", + "icon": "TwoUsers" + }, + "link": { + "type": "string", + "format": "url", + "title": "Link", + "icon": "Link" + }, + "lastAnalysisDate": { + "type": "string", + "format": "date-time", + "icon": "Clock", + "title": "Last Analysis Date" + }, + "numberOfBugs": { + "type": "number", + "title": "Number Of Bugs" + }, + "numberOfCodeSmells": { + "type": "number", + "title": "Number Of CodeSmells" + }, + "numberOfVulnerabilities": { + "type": "number", + "title": "Number Of Vulnerabilities" + }, + "numberOfHotSpots": { + "type": "number", + "title": "Number Of HotSpots" + }, + "numberOfDuplications": { + "type": "number", + "title": "Number Of Duplications" + }, + "coverage": { + "type": "number", + "title": "Coverage" + }, + "mainBranch": { + "type": "string", + "icon": "Git", + "title": "Main Branch" + }, + "tags": { + "type": "array", + "title": "Tags" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": {} +} +``` + +
+
+
+## Issue
+
+Integration configuration (Click to expand)
+ +:::tip filter projects +The integration provides an option to filter the data that is retrieved from the SonarQube API using the following attributes: + +1. `query`: Limits the search to component names that contain the supplied string +2. `alertStatus`: To filter a project's quality gate status. Accepts a list of values such as `OK`, `ERROR` and `WARN` +3. `languages`: To filter projects using a list of languages or a single language +4. `tags`: To filter a list of tags or a single tag +5. `qualifier`: To filter on a component qualifier. Accepts values such as `TRK` (for projects only) and `APP` (for applications only) + +These attributes can be enabled using the path: `selector.apiFilters.filter`. By default, the integration fetches only SonarQube projects using the `qualifier` attribute. +::: + +:::tip Define your own metrics +Besides filtering the API data, the integration provides a mechanism to allow users to define their own list of metrics used in SonarQube to evaluate the code. This list can be defined in the `selector.metrics` property. A complete list of valid SonarQube metrics can be in the [SonarQube documentation](https://docs.sonarsource.com/sonarqube/latest/user-guide/code-metrics/metrics-definition/) +::: + +:::note Supported Sonar environment +Please note that the API filters are supported on on-premise Sonar environments (SonarQube) only, and will not work on SonarCloud. +::: + +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: projects + selector: + query: "true" + apiFilters: + filter: + qualifier: TRK + metrics: + - code_smells + - coverage + - bugs + - vulnerabilities + - duplicated_files + - security_hotspots + - new_violations + - new_coverage + - new_duplicated_lines_density + port: + entity: + mappings: + blueprint: '"sonarQubeProject"' + identifier: .key + title: .name + properties: + organization: .organization + link: .__link + lastAnalysisStatus: .__branch.status.qualityGateStatus + lastAnalysisDate: .__branch.analysisDate + numberOfBugs: .__measures[]? | select(.metric == "bugs") | .value + numberOfCodeSmells: .__measures[]? | select(.metric == "code_smells") | .value + numberOfVulnerabilities: .__measures[]? | select(.metric == "vulnerabilities") | .value + numberOfHotSpots: .__measures[]? | select(.metric == "security_hotspots") | .value + numberOfDuplications: .__measures[]? | select(.metric == "duplicated_files") | .value + coverage: .__measures[]? | select(.metric == "coverage") | .value + mainBranch: .__branch.name + tags: .tags +``` +
+
+
+Issue blueprint (Click to expand)
+ +```json showLineNumbers +{ + "identifier": "sonarQubeIssue", + "title": "SonarQube Issue", + "icon": "sonarqube", + "schema": { + "properties": { + "type": { + "type": "string", + "title": "Type", + "enum": ["CODE_SMELL", "BUG", "VULNERABILITY"] + }, + "severity": { + "type": "string", + "title": "Severity", + "enum": ["MAJOR", "INFO", "MINOR", "CRITICAL", "BLOCKER"], + "enumColors": { + "MAJOR": "orange", + "INFO": "green", + "CRITICAL": "red", + "BLOCKER": "red", + "MINOR": "yellow" + } + }, + "link": { + "type": "string", + "format": "url", + "icon": "Link", + "title": "Link" + }, + "status": { + "type": "string", + "title": "Status", + "enum": ["OPEN", "CLOSED", "RESOLVED", "REOPENED", "CONFIRMED"] + }, + "assignees": { + "title": "Assignees", + "type": "string", + "icon": "TwoUsers" + }, + "tags": { + "type": "array", + "title": "Tags" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "title": "Created At" + } + } + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "sonarQubeProject": { + "target": "sonarQubeProject", + "required": false, + "title": "SonarQube Project", + "many": false + } + } +} +``` + +
+
+
+## Saas Analysis
+
+Integration configuration (Click to expand)
+ +:::tip filter issues +The integration provides an option to filter the data that is retrieved from the SonarQube API using the following attributes: + +1. `assigned`: To retrieve assigned or unassigned issues. Accepts values: `yes`, `no`, `true`, `false` +2. `assignees`: A list of assignee logins +3. `cleanCodeAttributeCategories`: List of clean code attribute categories. Accepts values: `ADAPTABLE`, `CONSISTENT`, `INTENTIONAL`, `RESPONSIBLE` +4. `createdBefore`: To retrieve issues created before the given date +5. `createdAfter`: To retrieve issues created after the given date +6. `impactSeverities`: List of impact severities. Accepts values: `HIGH`, `LOW`, `MEDIUM` +7. `impactSoftwareQualities`: List of impact software qualities. Accepts values: `MAINTAINABILITY`, `RELIABILITY`, `SECURITY` +8. `statuses`: List of statuses. Accepts values: `OPEN`, `CONFIRMED`, `FALSE_POSITIVE`, `ACCEPTED`, `FIXED` +9. `languages`: List of languages +10. `resolved`: To retrieve resolved or unresolved issues. Accepts values: `yes`, `no`, `true`, `false` +11. `scopes`: List of scopes. Accepts values: `MAIN`, `TESTS` +12. `tags`: List of tags + +These attributes can be enabled using the path: `selector.apiFilters`. By default, the integration fetches unresolved SonarQube issues. It is also possible to configure the integration to fetch issues from a SonarQube project using the path: `selector.projectApiFilters.filter` while specifying any of [the above project attributes](#project) +::: + +:::note Supported Sonar environment +Please note that the API filters are supported on on-premise Sonar environments (SonarQube) only, and will not work on SonarCloud. +::: + +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: issues + selector: + query: "true" + apiFilters: + resolved: 'false' + projectApiFilters: + filter: + qualifier: TRK + port: + entity: + mappings: + blueprint: '"sonarQubeIssue"' + identifier: .key + title: .message + properties: + type: .type + severity: .severity + link: .__link + status: .status + assignees: .assignee + tags: .tags + createdAt: .creationDate + relations: + sonarQubeProject: .project +``` + +
+
+
+Saas analysis blueprint (Click to expand)
+ +```json showLineNumbers +{ + "identifier": "sonarQubeAnalysis", + "title": "SonarQube Analysis", + "icon": "sonarqube", + "schema": { + "properties": { + "branch": { + "type": "string", + "title": "Branch", + "icon": "GitVersion" + }, + "fixedIssues": { + "type": "number", + "title": "Fixed Issues" + }, + "newIssues": { + "type": "number", + "title": "New Issues" + }, + "coverage": { + "title": "Coverage", + "type": "number" + }, + "duplications": { + "type": "number", + "title": "Duplications" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "title": "Created At" + } + } + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "sonarQubeProject": { + "target": "sonarQubeProject", + "required": false, + "title": "SonarQube Project", + "many": false + } + } +} +``` + +
+
+
+## On-Premise Analysis
+
+Integration configuration (Click to expand)
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: saas_analysis + selector: + query: "true" + port: + entity: + mappings: + blueprint: '"sonarQubeAnalysis"' + identifier: .analysisId + title: .__commit.message // .analysisId + properties: + branch: .__branchName + fixedIssues: .measures.violations_fixed + newIssues: .measures.violations_added + coverage: .measures.coverage_change + duplications: .measures.duplicated_lines_density_change + createdAt: .__analysisDate + relations: + sonarQubeProject: .__project +``` + +
+
+
+On-premise analysis blueprint (Click to expand)
+ +```json showLineNumbers +{ + "identifier": "sonarQubeAnalysis", + "title": "SonarQube Analysis", + "icon": "sonarqube", + "schema": { + "properties": { + "branch": { + "type": "string", + "title": "Branch", + "icon": "GitVersion" + }, + "fixedIssues": { + "type": "number", + "title": "Fixed Issues" + }, + "newIssues": { + "type": "number", + "title": "New Issues" + }, + "coverage": { + "title": "Coverage", + "type": "number" + }, + "duplications": { + "type": "number", + "title": "Duplications" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "title": "Created At" + } + } + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "sonarQubeProject": { + "target": "sonarQubeProject", + "required": false, + "title": "SonarQube Project", + "many": false + } + } +} +``` + +
+
+
+## Portfolio
+
+Integration configuration (Click to expand)
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: onprem_analysis + selector: + query: 'true' + port: + entity: + mappings: + blueprint: '"sonarQubeAnalysis"' + identifier: .__project + "-" + .key + title: .title + properties: + branch: .branch + newIssues: .__measures[]? | select(.metric == "new_violations") | .period.value + coverage: .__measures[]? | select(.metric == "new_coverage") | .period.value + duplications: .__measures[]? | select(.metric == "new_duplicated_lines_density") | .period.value + createdAt: .analysisDate + relations: + sonarQubeProject: .__project +``` + +
+
+
+Portfolio blueprint (Click to expand)
+ +```json showLineNumbers +{ + "identifier": "sonarQubePortfolio", + "title": "SonarQube Portfolio", + "icon": "sonarqube", + "schema": { + "properties": { + "description": { + "type": "string", + "title": "Description" + }, + "visibility": { + "type": "string", + "title": "Visibility", + "enum": [ + "PUBLIC", + "PRIVATE" + ], + "enumColors": { + "PUBLIC": "green", + "PRIVATE": "lightGray" + } + }, + "selectionMode": { + "type": "string", + "title": "Selection Mode", + "enum": [ + "AUTO", + "MANUAL", + "NONE" + ], + "enumColors": { + "AUTO": "blue", + "MANUAL": "green", + "NONE": "lightGray" + } + }, + "disabled": { + "type": "boolean", + "title": "Disabled" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "referencedBy": { + "title": "Referenced By", + "target": "sonarQubePortfolio", + "required": false, + "many": true + }, + "subPortfolios": { + "title": "Sub Portfolios", + "target": "sonarQubePortfolio", + "required": false, + "many": true + } + } +} +``` + +
+
\ No newline at end of file
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/sonarqube.md b/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/sonarqube.md
index 188c0a824..321806e89 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/sonarqube.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/sonarqube/sonarqube.md
@@ -11,24 +11,40 @@ import SonarcloudAnalysisBlueprint from "/docs/build-your-software-catalog/custo
import SonarcloudAnalysisConfiguration from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/sonarqube/\_example_sonarcloud_analysis_configuration.mdx";
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+
# SonarQube
-Port's SonarQube integration (powered by [Ocean](https://ocean.getport.io)) allows you to import `projects`, `issues` and `analyses` from your SonarQube account into
-Port, according to your mapping and definitions.
+Port's SonarQube integration allows you to model SonarQube resources in your software catalog and ingest data into them.
-## Common use cases
-- Map `projects`, `issues`, `analyses` and `portfolios` in your SonarQube organization environment.
-- Watch for object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in
- Port.
-- Create/delete SonarQube objects using self-service actions.
+## Overview
-## Prerequisites
+This integration allows you to:
-Integration configuration (Click to expand)
+ +```yaml showLineNumbers +deleteDependentEntities: true +createMissingRelatedEntities: true +resources: + - kind: portfolios + selector: + query: 'true' + port: + entity: + mappings: + identifier: .key + title: .name + blueprint: '"sonarQubePortfolio"' + properties: + description: .description + visibility: if .visibility then .visibility | ascii_upcase else null end + selectionMode: if .selectionMode then .selectionMode | ascii_upcase else null end + disabled: .disabled + relations: + subPortfolios: .subViews | map(select((.qualifier | IN("VW", "SVW"))) | .key) + referencedBy: .referencedBy | map(select((.qualifier | IN("VW", "SVW"))) | .key) +``` + +Prerequisites
-+
-
-
-Projects blueprint (Click to expand)
- -```json showLineNumbers -{ - "identifier": "sonarQubeProject", - "title": "SonarQube Project", - "icon": "sonarqube", - "schema": { - "properties": { - "organization": { - "type": "string", - "title": "Organization", - "icon": "TwoUsers" - }, - "link": { - "type": "string", - "format": "url", - "title": "Link", - "icon": "Link" - }, - "lastAnalysisDate": { - "type": "string", - "format": "date-time", - "icon": "Clock", - "title": "Last Analysis Date" - }, - "numberOfBugs": { - "type": "number", - "title": "Number Of Bugs" - }, - "numberOfCodeSmells": { - "type": "number", - "title": "Number Of CodeSmells" - }, - "numberOfVulnerabilities": { - "type": "number", - "title": "Number Of Vulnerabilities" - }, - "numberOfHotSpots": { - "type": "number", - "title": "Number Of HotSpots" - }, - "numberOfDuplications": { - "type": "number", - "title": "Number Of Duplications" - }, - "coverage": { - "type": "number", - "title": "Coverage" - }, - "mainBranch": { - "type": "string", - "icon": "Git", - "title": "Main Branch" - }, - "tags": { - "type": "array", - "title": "Tags" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": {} -} -``` - -
-
-
-### Issue
-
-Integration configuration (Click to expand)
- -:::tip filter projects -The integration provides an option to filter the data that is retrieved from the SonarQube API using the following attributes: - -1. `query`: Limits the search to component names that contain the supplied string -2. `alertStatus`: To filter a project's quality gate status. Accepts a list of values such as `OK`, `ERROR` and `WARN` -3. `languages`: To filter projects using a list of languages or a single language -4. `tags`: To filter a list of tags or a single tag -5. `qualifier`: To filter on a component qualifier. Accepts values such as `TRK` (for projects only) and `APP` (for applications only) - -These attributes can be enabled using the path: `selector.apiFilters.filter`. By default, the integration fetches only SonarQube projects using the `qualifier` attribute. -::: - -:::tip Define your own metrics -Besides filtering the API data, the integration provides a mechanism to allow users to define their own list of metrics used in SonarQube to evaluate the code. This list can be defined in the `selector.metrics` property. A complete list of valid SonarQube metrics can be in the [SonarQube documentation](https://docs.sonarsource.com/sonarqube/latest/user-guide/code-metrics/metrics-definition/) -::: - -:::note Supported Sonar environment -Please note that the API filters are supported on on-premise Sonar environments (SonarQube) only, and will not work on SonarCloud. -::: - -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: projects - selector: - query: "true" - apiFilters: - filter: - qualifier: TRK - metrics: - - code_smells - - coverage - - bugs - - vulnerabilities - - duplicated_files - - security_hotspots - - new_violations - - new_coverage - - new_duplicated_lines_density - port: - entity: - mappings: - blueprint: '"sonarQubeProject"' - identifier: .key - title: .name - properties: - organization: .organization - link: .__link - lastAnalysisStatus: .__branch.status.qualityGateStatus - lastAnalysisDate: .__branch.analysisDate - numberOfBugs: .__measures[]? | select(.metric == "bugs") | .value - numberOfCodeSmells: .__measures[]? | select(.metric == "code_smells") | .value - numberOfVulnerabilities: .__measures[]? | select(.metric == "vulnerabilities") | .value - numberOfHotSpots: .__measures[]? | select(.metric == "security_hotspots") | .value - numberOfDuplications: .__measures[]? | select(.metric == "duplicated_files") | .value - coverage: .__measures[]? | select(.metric == "coverage") | .value - mainBranch: .__branch.name - tags: .tags -``` -
-
+To view and test the integration's mapping against examples of the third-party API responses,
+use the jq playground in your [data sources page](https://app.getport.io/settings/data-sources).
+Find the integration in the list of data sources and click on it to open the playground.
-Issue blueprint (Click to expand)
- -```json showLineNumbers -{ - "identifier": "sonarQubeIssue", - "title": "SonarQube Issue", - "icon": "sonarqube", - "schema": { - "properties": { - "type": { - "type": "string", - "title": "Type", - "enum": ["CODE_SMELL", "BUG", "VULNERABILITY"] - }, - "severity": { - "type": "string", - "title": "Severity", - "enum": ["MAJOR", "INFO", "MINOR", "CRITICAL", "BLOCKER"], - "enumColors": { - "MAJOR": "orange", - "INFO": "green", - "CRITICAL": "red", - "BLOCKER": "red", - "MINOR": "yellow" - } - }, - "link": { - "type": "string", - "format": "url", - "icon": "Link", - "title": "Link" - }, - "status": { - "type": "string", - "title": "Status", - "enum": ["OPEN", "CLOSED", "RESOLVED", "REOPENED", "CONFIRMED"] - }, - "assignees": { - "title": "Assignees", - "type": "string", - "icon": "TwoUsers" - }, - "tags": { - "type": "array", - "title": "Tags" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "title": "Created At" - } - } - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "sonarQubeProject": { - "target": "sonarQubeProject", - "required": false, - "title": "SonarQube Project", - "many": false - } - } -} -``` - -
-
-### Saas Analysis
-
-Integration configuration (Click to expand)
- -:::tip filter issues -The integration provides an option to filter the data that is retrieved from the SonarQube API using the following attributes: - -1. `assigned`: To retrieve assigned or unassigned issues. Accepts values: `yes`, `no`, `true`, `false` -2. `assignees`: A list of assignee logins -3. `cleanCodeAttributeCategories`: List of clean code attribute categories. Accepts values: `ADAPTABLE`, `CONSISTENT`, `INTENTIONAL`, `RESPONSIBLE` -4. `createdBefore`: To retrieve issues created before the given date -5. `createdAfter`: To retrieve issues created after the given date -6. `impactSeverities`: List of impact severities. Accepts values: `HIGH`, `LOW`, `MEDIUM` -7. `impactSoftwareQualities`: List of impact software qualities. Accepts values: `MAINTAINABILITY`, `RELIABILITY`, `SECURITY` -8. `statuses`: List of statuses. Accepts values: `OPEN`, `CONFIRMED`, `FALSE_POSITIVE`, `ACCEPTED`, `FIXED` -9. `languages`: List of languages -10. `resolved`: To retrieve resolved or unresolved issues. Accepts values: `yes`, `no`, `true`, `false` -11. `scopes`: List of scopes. Accepts values: `MAIN`, `TESTS` -12. `tags`: List of tags - -These attributes can be enabled using the path: `selector.apiFilters`. By default, the integration fetches unresolved SonarQube issues. It is also possible to configure the integration to fetch issues from a SonarQube project using the path: `selector.projectApiFilters.filter` while specifying any of [the above project attributes](#project) -::: +Examples of blueprints and the relevant integration configurations can be found on the sonarqube [examples page](examples.md) -:::note Supported Sonar environment -Please note that the API filters are supported on on-premise Sonar environments (SonarQube) only, and will not work on SonarCloud. -::: - -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: issues - selector: - query: "true" - apiFilters: - resolved: 'false' - projectApiFilters: - filter: - qualifier: TRK - port: - entity: - mappings: - blueprint: '"sonarQubeIssue"' - identifier: .key - title: .message - properties: - type: .type - severity: .severity - link: .__link - status: .status - assignees: .assignee - tags: .tags - createdAt: .creationDate - relations: - sonarQubeProject: .project -``` - -
-
-
-Saas analysis blueprint (Click to expand)
- -```json showLineNumbers -{ - "identifier": "sonarQubeAnalysis", - "title": "SonarQube Analysis", - "icon": "sonarqube", - "schema": { - "properties": { - "branch": { - "type": "string", - "title": "Branch", - "icon": "GitVersion" - }, - "fixedIssues": { - "type": "number", - "title": "Fixed Issues" - }, - "newIssues": { - "type": "number", - "title": "New Issues" - }, - "coverage": { - "title": "Coverage", - "type": "number" - }, - "duplications": { - "type": "number", - "title": "Duplications" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "title": "Created At" - } - } - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "sonarQubeProject": { - "target": "sonarQubeProject", - "required": false, - "title": "SonarQube Project", - "many": false - } - } -} -``` - -
-
-
-### On-Premise Analysis
-
-Integration configuration (Click to expand)
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: saas_analysis - selector: - query: "true" - port: - entity: - mappings: - blueprint: '"sonarQubeAnalysis"' - identifier: .analysisId - title: .__commit.message // .analysisId - properties: - branch: .__branchName - fixedIssues: .measures.violations_fixed - newIssues: .measures.violations_added - coverage: .measures.coverage_change - duplications: .measures.duplicated_lines_density_change - createdAt: .__analysisDate - relations: - sonarQubeProject: .__project -``` - -
-
-
-On-premise analysis blueprint (Click to expand)
- -```json showLineNumbers -{ - "identifier": "sonarQubeAnalysis", - "title": "SonarQube Analysis", - "icon": "sonarqube", - "schema": { - "properties": { - "branch": { - "type": "string", - "title": "Branch", - "icon": "GitVersion" - }, - "fixedIssues": { - "type": "number", - "title": "Fixed Issues" - }, - "newIssues": { - "type": "number", - "title": "New Issues" - }, - "coverage": { - "title": "Coverage", - "type": "number" - }, - "duplications": { - "type": "number", - "title": "Duplications" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "title": "Created At" - } - } - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "sonarQubeProject": { - "target": "sonarQubeProject", - "required": false, - "title": "SonarQube Project", - "many": false - } - } -} -``` - -
-
-
-### Portfolio
-
-Integration configuration (Click to expand)
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: onprem_analysis - selector: - query: 'true' - port: - entity: - mappings: - blueprint: '"sonarQubeAnalysis"' - identifier: .__project + "-" + .key - title: .title - properties: - branch: .branch - newIssues: .__measures[]? | select(.metric == "new_violations") | .period.value - coverage: .__measures[]? | select(.metric == "new_coverage") | .period.value - duplications: .__measures[]? | select(.metric == "new_duplicated_lines_density") | .period.value - createdAt: .analysisDate - relations: - sonarQubeProject: .__project -``` - -
-
-
-Portfolio blueprint (Click to expand)
- -```json showLineNumbers -{ - "identifier": "sonarQubePortfolio", - "title": "SonarQube Portfolio", - "icon": "sonarqube", - "schema": { - "properties": { - "description": { - "type": "string", - "title": "Description" - }, - "visibility": { - "type": "string", - "title": "Visibility", - "enum": [ - "PUBLIC", - "PRIVATE" - ], - "enumColors": { - "PUBLIC": "green", - "PRIVATE": "lightGray" - } - }, - "selectionMode": { - "type": "string", - "title": "Selection Mode", - "enum": [ - "AUTO", - "MANUAL", - "NONE" - ], - "enumColors": { - "AUTO": "blue", - "MANUAL": "green", - "NONE": "lightGray" - } - }, - "disabled": { - "type": "boolean", - "title": "Disabled" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "referencedBy": { - "title": "Referenced By", - "target": "sonarQubePortfolio", - "required": false, - "many": true - }, - "subPortfolios": { - "title": "Sub Portfolios", - "target": "sonarQubePortfolio", - "required": false, - "many": true - } - } -} -``` - -
-
## Let's Test It
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/wiz.md b/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/wiz.md
index c8a48db7a..fc620640e 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/wiz.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/code-quality-security/wiz.md
@@ -9,15 +9,31 @@ import WizConfiguration from "/docs/build-your-software-catalog/custom-integrati
import FindCredentials from "/docs/build-your-software-catalog/custom-integration/api/_template_docs/_find_credentials.mdx";
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+
# Wiz
-Our Wiz integration allows you to import `projects`, `issues`, `controls`, and `serviceTickets` from your Wiz account into Port, according to your mapping and definitions.
+Port's Wiz integration allows you to model Wiz resources in your software catalog and ingest data into them.
+
+
+## Overview
+
+This integration allows you to:
+
+- Map and organize your desired Wiz resources and their metadata in Port (see supported resources below).
+- Watch for Wiz object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
-## Common use cases
-- Map `projects`, `issues`, `controls`, and `serviceTickets` in your Wiz organization environment.
-- Watch for object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
+### Supported Resources
+
+The resources that can be ingested from Wiz into Port are listed below. It is possible to reference any field that appears in the API responses linked below in the mapping configuration.
+
+- [`Project`](https://integrate.wiz.io/reference/pull-projects)
+- [`Issue`](https://integrate.wiz.io/reference/issues-tutorial)
+- [`Control`](https://integrate.wiz.io/docs/welcome#controls)
+- [`Service ticket`](https://integrate.wiz.io/reference/issues-query#:~:text=string-,serviceTickets,-array)
+
## Prerequisites
@@ -85,7 +101,7 @@ You must create a service account in Wiz to generate the Client ID and Client Se
Integration configuration (Click to expand)
- -```yaml showLineNumbers -deleteDependentEntities: true -createMissingRelatedEntities: true -resources: - - kind: portfolios - selector: - query: 'true' - port: - entity: - mappings: - identifier: .key - title: .name - blueprint: '"sonarQubePortfolio"' - properties: - description: .description - visibility: if .visibility then .visibility | ascii_upcase else null end - selectionMode: if .selectionMode then .selectionMode | ascii_upcase else null end - disabled: .disabled - relations: - subPortfolios: .subViews | map(select((.qualifier | IN("VW", "SVW"))) | .key) - referencedBy: .referencedBy | map(select((.qualifier | IN("VW", "SVW"))) | .key) -``` - --## Installation +## Setup Choose one of the following installation methods: @@ -97,61 +113,28 @@ Choose one of the following installation methods:
Prerequisites
++ +For details about the available parameters for the installation, see the table below.
+
@@ -353,10 +355,9 @@ pipeline { ```
@@ -984,50 +870,6 @@ resources:
-## Alternative installation via webhook
-While the Ocean integration described above is the recommended installation method, you may prefer to use a webhook to ingest data from Wiz. If so, use the following instructions:
-
-
-
-
-
## Let's Test It
This section includes a sample response data from Wiz. In addition, it includes the entity created from the resync event based on the Ocean configuration provided in the previous section.
@@ -1309,3 +1151,51 @@ The combination of the sample payload and the Ocean configuration generates the
```
+
+## Alternative installation via webhook
+While the Ocean integration described above is the recommended installation method, you may prefer to use a webhook to ingest data from Wiz. If so, use the following instructions:
+
+**Note** that when using the webhook installation method, data will be ingested into Port only when the webhook is triggered.
+
+
+Webhook installation (click to expand)
- -In this example you are going to create a webhook integration between [Wiz](https://wiz.io/) and Port, which will ingest Wiz issue entities into Port. - -Port configuration
- -Create the following blueprint definition: - -
-
-
-Create the following webhook configuration [using Port's UI](/build-your-software-catalog/custom-integration/webhook/?operation=ui#configuring-webhook-endpoints)
-
-Wiz issue blueprint
- -
-
-
-Wiz issue webhook configuration
- -1. **Basic details** tab - fill the following details: - 1. Title : `Wiz Mapper`; - 2. Identifier : `wiz_mapper`; - 3. Description : `A webhook configuration to map Wiz issues to Port`; - 4. Icon : `Box`; -2. **Integration configuration** tab - fill the following JQ mapping: - -Create a webhook in Wiz
- -1. Send an email to win@wiz.io requesting for access to the developer documentation or reach out to your Wiz account manager. -2. Follow this [guide](https://integrate.wiz.io/reference/webhook-tutorial#create-a-custom-webhook) in the documentation to create a webhook. - -Done! Any issue created in Wiz will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly. -
+
+
+
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/feature-management/launchdarkly/launchdarkly.md b/docs/build-your-software-catalog/sync-data-to-catalog/feature-management/launchdarkly/launchdarkly.md
index c6a78ca52..f378e5481 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/feature-management/launchdarkly/launchdarkly.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/feature-management/launchdarkly/launchdarkly.md
@@ -9,6 +9,10 @@ import TabItem from "@theme/TabItem"
import DockerParameters from "./\_launchdarkly_one_time_docker_parameters.mdx"
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+import Prerequisites from "../../templates/\_ocean_helm_prerequisites_block.mdx"
+
+
# LaunchDarkly
@@ -45,61 +49,27 @@ Choose one of the following installation methods:
Webhook installation (click to expand)
+ +In this example you are going to create a webhook integration between [Wiz](https://wiz.io/) and Port, which will ingest Wiz issue entities into Port. + +Port configuration
+ +Create the following blueprint definition: + +
+
+
+Create the following webhook configuration [using Port's UI](/build-your-software-catalog/custom-integration/webhook/?operation=ui#configuring-webhook-endpoints)
+
+Wiz issue blueprint
+ +
+
+
+Wiz issue webhook configuration
+ +1. **Basic details** tab - fill the following details: + 1. Title : `Wiz Mapper`; + 2. Identifier : `wiz_mapper`; + 3. Description : `A webhook configuration to map Wiz issues to Port`; + 4. Icon : `Box`; +2. **Integration configuration** tab - fill the following JQ mapping: + +Create a webhook in Wiz
+ +1. Send an email to win@wiz.io requesting for access to the developer documentation or reach out to your Wiz account manager. +2. Follow this [guide](https://integrate.wiz.io/reference/webhook-tutorial#create-a-custom-webhook) in the documentation to create a webhook. + +Done! Any issue created in Wiz will trigger a webhook event to the webhook URL provided by Port. Port will parse the events according to the mapping and update the catalog entities accordingly. +Prerequisites
- -To install the integration, you need a Kubernetes cluster that the integration's container chart will be deployed to. +Prerequisites
-Using this installation option means that the integration will be able to update Port in real time using webhooks. +Event listener
The integration uses polling to pull the configuration from Port every minute and check it for changes. If there is a change, a resync will occur. @@ -191,14 +178,15 @@ The integration uses polling to pull the configuration from Port every minute an
+
+
+
+Project response data
+ +```json showLineNumbers +{ + "_links": { + "environments": { + "href": "/api/v2/projects/fourth-project/environments", + "type": "application/json" + }, + "flagDefaults": { + "href": "/api/v2/projects/fourth-project/flag-defaults", + "type": "application/json" + }, + "self": { + "href": "/api/v2/projects/fourth-project", + "type": "application/json" + } + }, + "_id": "666b298cc671e81012b578c6", + "key": "fourth-project", + "includeInSnippetByDefault": false, + "defaultClientSideAvailability": { + "usingMobileKey": false, + "usingEnvironmentId": false + }, + "name": "Fourth Project", + "tags": [] +} +``` +
+
+
+Feature Flag response data
+ +```json showLineNumbers +{ + "_links": { + "parent": { + "href": "/api/v2/flags/fourth-project", + "type": "application/json" + }, + "self": { + "href": "/api/v2/flags/fourth-project/randomflag", + "type": "application/json" + } + }, + "_maintainer": { + "_id": "6669b0f34162860fefd6d724", + "_links": { + "self": { + "href": "/api/v2/members/6669b0f34162860fefd6d724", + "type": "application/json" + } + }, + "email": "example@gmail.com", + "firstName": "John", + "lastName": "Doe", + "role": "owner" + }, + "_version": 1, + "archived": false, + "clientSideAvailability": { + "usingEnvironmentId": false, + "usingMobileKey": false + }, + "creationDate": 1718299647527, + "customProperties": {}, + "defaults": { + "offVariation": 1, + "onVariation": 0 + }, + "deprecated": false, + "description": "", + "environments": { + "fourth-env": { + "_environmentName": "fourth-env", + "_site": { + "href": "/fourth-project/fourth-env/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718299647539, + "on": false, + "salt": "c713989066a446febf07a42d488221e8", + "sel": "6d7c3692dd9d4ffa8eee8e2d96b6fd2c", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "new-env": { + "_environmentName": "new env", + "_site": { + "href": "/fourth-project/new-env/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718299647539, + "on": false, + "salt": "caa436a38411406491f0da9230349bb3", + "sel": "8bcf1667ab2f4f628fc26ad31966f045", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "new-project": { + "_environmentName": "new_project", + "_site": { + "href": "/fourth-project/new-project/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718299647539, + "on": false, + "salt": "f79c8849d22d497d8a519fbb6263aeda", + "sel": "257f0acaf18f4252b40258f8aa93b966", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "production": { + "_environmentName": "Production", + "_site": { + "href": "/fourth-project/production/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718299647539, + "on": false, + "salt": "28c5efba5fd445d5896a8b9f7f8fbff6", + "sel": "28a317cdf3aa4d40b8a0b1c6f56be4c9", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "shadow": { + "_environmentName": "shadow", + "_site": { + "href": "/fourth-project/shadow/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718311480830, + "on": false, + "salt": "cb214aeac84f48d08ff136514c589b11", + "sel": "00b5f9ae56a547db9c4e5e619bdb39f3", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "some-random-env": { + "_environmentName": "some-random-env", + "_site": { + "href": "/fourth-project/some-random-env/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718300514123, + "on": false, + "salt": "0618861de85c48a5a77c360db7a8847b", + "sel": "5ae511fe5630469084453c2c4d45f719", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "staging": { + "_environmentName": "staging", + "_site": { + "href": "/fourth-project/staging/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718300902420, + "on": false, + "salt": "bc27ddc205984379a4863f5f1323bdb0", + "sel": "2762811a62734de79277544ff4362f8c", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + }, + "test": { + "_environmentName": "Test", + "_site": { + "href": "/fourth-project/test/features/randomflag", + "type": "text/html" + }, + "_summary": { + "prerequisites": 0, + "variations": { + "0": { + "contextTargets": 0, + "isFallthrough": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + }, + "1": { + "contextTargets": 0, + "isOff": true, + "nullRules": 0, + "rules": 0, + "targets": 0 + } + } + }, + "archived": false, + "lastModified": 1718299647539, + "on": false, + "salt": "fac0fe470f844433986166f3d570415d", + "sel": "8e8ae9542dc94f35b1ac64c845277d8a", + "trackEvents": false, + "trackEventsFallthrough": false, + "version": 1 + } + }, + "experiments": { + "baselineIdx": 0, + "items": [] + }, + "goalIds": [], + "includeInSnippet": false, + "key": "randomflag", + "kind": "boolean", + "maintainerId": "6669b0f34162860fefd6d724", + "name": "randomflag", + "tags": [], + "temporary": true, + "variationJsonSchema": null, + "variations": [ + { + "_id": "8868f0d9-8b1d-4575-9436-827188276792", + "value": true + }, + { + "_id": "8929317b-d2aa-479c-9249-e6c0ec5dc415", + "value": false + } + ], + "__projectKey": "fourth-project" +} +``` + +
+
+
+
+Environment response data
+ +```json showLineNumbers +{ + "_links": { + "analytics": { + "href": "https://app.launchdarkly.com/snippet/events/v1/666b2a74cbdbfb108f3fc911.js", + "type": "text/html" + }, + "apiKey": { + "href": "/api/v2/projects/fourth-project/environments/fourth-env/apiKey", + "type": "application/json" + }, + "mobileKey": { + "href": "/api/v2/projects/fourth-project/environments/fourth-env/mobileKey", + "type": "application/json" + }, + "self": { + "href": "/api/v2/projects/fourth-project/environments/fourth-env", + "type": "application/json" + }, + "snippet": { + "href": "https://app.launchdarkly.com/snippet/features/666b2a74cbdbfb108f3fc911.js", + "type": "text/html" + } + }, + "_id": "666b2a74cbdbfb108f3fc911", + "_pubnub": { + "channel": "b4f644c56dbbfe88a4028cb2d2142c258926f9b7a9add263d105202f0cd6599c", + "cipherKey": "9571e2de187881614fe9b6b94d13a99fbdb056e508c9226e6c6bb7d0be117725" + }, + "key": "fourth-env", + "name": "fourth-env", + "apiKey": "sdk-1b3cf928-acae-4553-aab3-c956b7f04219", + "mobileKey": "mob-87679d8a-698d-4c5f-9ec1-05e368975afe", + "color": "e2e6ff", + "defaultTtl": 0, + "secureMode": false, + "defaultTrackEvents": false, + "requireComments": false, + "confirmChanges": false, + "tags": [], + "approvalSettings": { + "required": false, + "bypassApprovalsForPendingChanges": false, + "minNumApprovals": 1, + "canReviewOwnRequest": false, + "canApplyDeclinedChanges": true, + "serviceKind": "launchdarkly", + "serviceConfig": {}, + "requiredApprovalTags": [] + }, + "critical": false, + "__projectKey": "fourth-project" +} +``` + +
+
+
+### Mapping Result
+
+The combination of the sample payload and the Ocean configuration generates the following Port entity:
+
+Feature Flag In Environment response data
+ +```json showLineNumbers +{ + "_links": { + "parent": { + "href": "/api/v2/flags/fourth-project/olulufe", + "type": "application/json" + }, + "self": { + "href": "/api/v2/flag-statuses/fourth-project/shadow/olulufe", + "type": "application/json" + } + }, + "name": "new", + "lastRequested": null, + "__environmentKey": "shadow", + "__projectKey": "fourth-project" +} +``` + +
+
+
+Project entity in Port
+ +```json showLineNumbers +{ + "identifier": "fourth-project", + "title": "Fourth Project", + "blueprint": "launchDarklyProject", + "properties": { + "tags": [] + }, + "relation": { + "service": "fourth-project" + } +} +``` +
+
+
+Feature Flag entity in Port
+ +```json showLineNumbers +{ + "identifier": "randomflag-fourth-project", + "title": "randomflag", + "blueprint": "launchDarklyFeatureFlag", + "properties": { + "kind": "boolean", + "description": "", + "creationDate": "2024-06-13T17:27:27Z", + "clientSideAvailability": { + "usingEnvironmentId": false, + "usingMobileKey": false + }, + "temporary": true, + "tags": [], + "maintainer": "example@gmail.com", + "deprecated": false, + "variations": [ + { + "_id": "8868f0d9-8b1d-4575-9436-827188276792", + "value": true + }, + { + "_id": "8929317b-d2aa-479c-9249-e6c0ec5dc415", + "value": false + } + ], + "customProperties": {}, + "archived": false + }, + "relations": { + "project": "fourth-project" + } +} +``` + +
+
+
+Environment entity in Port
+ +```json showLineNumbers +{ + "identifier": "fourth-env-fourth-project", + "title": "fourth-env", + "blueprint": "launchDarklyEnvironment", + "properties": { + "defaultTtl": 0, + "secureMode": false, + "defaultTrackEvents": false, + "requireComments": false, + "confirmChanges": false, + "tags": [], + "critical": false + }, + "relations": { + "project": "fourth-project" + } + } +``` + +
+
+
+
+
## Relevant Guides
For relevant guides and examples, see the [guides section](https://docs.getport.io/guides?tags=Launchdarkly).
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx
index 2cdf91b81..c9bcd927f 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/_azuredevops_exporter_supported_resources.mdx
@@ -1,7 +1,3 @@
-:::tip Available Azure DevOps resources
-
-The following resources can be used to map data from Azure DevOps, it is possible to reference any field that appears in the API responses linked below for the Azure Devops integration api reference.
-
- [`repository`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/repositories/list?view=azure-devops-rest-7.2&tabs=HTTP#gitrepository)
- [`repository-policy`](https://learn.microsoft.com/en-us/rest/api/azure/devops/git/policy-configurations/get?view=azure-devops-rest-7.1#policyconfiguration)
- [`project`](https://learn.microsoft.com/en-us/rest/api/azure/devops/core/projects/list?view=azure-devops-rest-7.1&tabs=HTTP#teamprojectreference)
@@ -12,6 +8,3 @@ The following resources can be used to map data from Azure DevOps, it is possibl
- [`work-item`](https://learn.microsoft.com/en-us/rest/api/azure/devops/wit/wiql/query-by-wiql?view=azure-devops-rest-7.1&tabs=HTTP)
- [`board`](https://learn.microsoft.com/en-us/rest/api/azure/devops/work/boards/list?view=azure-devops-rest-7.1)
- [`release`](https://learn.microsoft.com/en-us/rest/api/azure/devops/release/releases?view=azure-devops-rest-7.1)
-
-
-:::
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md
index 22a20198d..de02ce83e 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/azure-devops.md
@@ -2,181 +2,45 @@ import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"
import AzureDevopsResources from './\_azuredevops_exporter_supported_resources.mdx'
+
# Azure DevOps
-Our integration with Azure DevOps allows you to export objects to Port as entities of existing blueprints. The integration supports real-time event processing so Port always provides an accurate real-time representation of your Azure DevOps resources.
+Port's Azure DevOps integration allows you to model Azure DevOps resources in your software catalog and ingest data into them.
-## Common use cases
+## Overview
-Our Azure DevOps integration makes it easy to fill the software catalog with data directly from your organization, for example:
+This integration allows you to:
-- Map most of the resources in the organization, including **projects**, **repositories**, **pipelines**, **pull requests**, **teams** and **members**.
+- Map and orgaize your desired Azure DevOps resources and their metadata in Port (see supported resources below).
- Watch for Azure DevOps object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
- Manage Port entities using GitOps.
-## Installation
-
-To install Port's Azure DevOps integration, follow the [installation](./installation.md) guide.
-
-## Ingesting Git objects
-
-This integration allows you to ingest a variety of objects resources provided by the Azure DevOps API. It allows you to perform ETL operations on data from the Azure DevOps API into the desired data model.
-
-This integration uses a YAML configuration to describe the ETL process to load data into the developer portal. The approach reflects a golden middle between an overly opinionated Git visualization that might not work for everyone and a too-broad approach that could introduce unneeded complexity into the developer portal.
-
-Here is an example snippet from the config which demonstrates the ETL process for getting `pull-request` data from Azure DevOps into the software catalog:
-
-```yaml showLineNumbers
-resources:
- # Extract
- # highlight-start
- - kind: pull-request
- selector:
- query: "true" # JQ boolean query. If evaluated to false - skip syncing the object.
- # highlight-end
- port:
- entity:
- mappings:
- # Transform & Load
- # highlight-start
- identifier: >-
- .repository.project.name + "/" + .repository.name + (.pullRequestId
- | tostring) | gsub(" "; "")
- blueprint: '"azureDevopsPullRequest"'
- properties:
- creator: .createdBy.uniqueName
- status: .status
- reviewers: '[.reviewers[].uniqueName]'
- createdAt: .creationDate
- relations:
- repository: '.repository.project.name + "/" + .repository.name | gsub(" "; "")'
- # highlight-end
-```
-
-The integration makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the different Azure DevOps API routes.
-
-### Integration configuration
-
-The integration's configuration is how you specify the exact resources you want to query from your organization, and which entities and properties you want to fill with the received data.
-
-Here is an example for the integration configuration block:
-
-```yaml showLineNumbers
-resources:
- - kind: repository
- selector:
- query: 'true' # JQ boolean query. If evaluated to false - skip syncing the object.
- port:
- entity:
- mappings:
- identifier: .project.name + "/" + .name # The Entity identifier will be the repository name.
- title: .name
- blueprint: '"azureDevopsRepository"'
- properties:
- url: .url
- readme: file://README.md
-```
-
-### Configuration structure
-
-- The root key of the integration configuration is the `resources` key:
-
- ```yaml showLineNumbers
- # highlight-next-line
- resources:
- - kind: repository
- selector:
- ...
- ```
-
-- The `kind` key is a specifier for an object from the Azure DevOps API:
-
- ```yaml showLineNumbers
- resources:
- # highlight-next-line
- - kind: repository
- selector:
- ...
- ```
+
+### Supported Resources
+
+The resources that can be ingested from Azure DevOps into Port are listed below.
Feature Flag In Environment entity in Port
+ +```json showLineNumbers +{ + "identifier": "olulufe-shadow", + "title": "olulufe-shadow", + "blueprint": "launchDarklyFFInEnvironment", + "properties": { + "status": "new" + }, + "relations": { + "environment": "shadow-fourth-project", + "featureFlag": "olulufe-fourth-project" + } + } +``` +- -:::tip WIQL Support -The Ocean Azure DevOps integration supports querying objects from the `work-item` kind using [WIQL](https://learn.microsoft.com/en-us/azure/devops/boards/queries/wiql-syntax?view=azure-devops), providing fine-grained control over which work items are ingested into Port. - -To leverage WIQL filtering, add a `wiql` key with your WIQL query as the value within the `selector` object. For example: - -```yaml showLineNumbers -resources: - - kind: work-item # WIQL filtering can only be used with the "work-item" kind - selector: - query: "true" - wiql: "[System.WorkItemType] = 'Task' AND [System.State] = 'Active'" # WIQL query, will only ingest work items of type "Task" whose state is "Active" - port: -``` - -::: - -The `port`, `entity` and the `mappings` keys open the section used to map the Azure DevOps API object fields to Port entities. To create multiple mappings of the same kind, you can add another item to the `resources` array; - - ```yaml showLineNumbers - resources: - - kind: repository - selector: - query: "true" - port: - # highlight-start - entity: - mappings: # Mappings between one Azure DevOps API object to a Port entity. Each value is a JQ query. - identifier: '.project.name + "/" + .name | gsub(" "; "")' - title: .name - blueprint: '"azureDevopsRepository"' - properties: - url: .url - readme: file://README.md - # highlight-end - - kind: repository # In this instance project is mapped again with a different filter - selector: - query: '.name == "MyRepositoryName"' - port: - entity: - mappings: ... - ``` - - :::tip - Pay attention to the value of the `blueprint` key, if you want to use a hardcoded string, you need to encapsulate it in 2 sets of quotes, for example use a pair of single-quotes (`'`) and then another pair of double-quotes (`"`) - ::: - -## Permissions - -Port's Azure DevOps integration requires a personal access token, follow the instructions in the [installation](./installation.md#create-a-personal-access-token) guide. + +## Setup + +To install Port's Azure DevOps integration, see the [installation](./installation.md#setup) page. + +## Configuration + +Port integrations use a [YAML mapping block](/build-your-software-catalog/customize-integrations/configure-mapping#configuration-structure) to ingest data from the third-party api into Port. + +The mapping makes use of the [JQ JSON processor](https://stedolan.github.io/jq/manual/) to select, modify, concatenate, transform and perform other operations on existing fields and values from the integration API. + ## Examples Refer to the [examples](./examples.md) page for practical configurations and their corresponding blueprint definitions. +## Relevant Guides +For relevant guides and examples, see the [guides section](https://docs.getport.io/guides?tags=AzureDevops). + ## GitOps Port's Azure DevOps integration also provides GitOps capabilities, refer to the [GitOps](./gitops/gitops.md) page to learn more. diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/installation.md b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/installation.md index 3ca09912f..a9da2598c 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/installation.md +++ b/docs/build-your-software-catalog/sync-data-to-catalog/git/azure-devops/installation.md @@ -4,11 +4,14 @@ sidebar_position: 1 import Tabs from "@theme/Tabs" import TabItem from "@theme/TabItem" +import Prerequisites from "../../templates/\_ocean_helm_prerequisites_block.mdx" import HelmParameters from "../../templates/\_ocean-advanced-parameters-helm.mdx" import DockerParameters from "./\_azuredevops_one_time_docker_parameters.mdx" import AdvancedConfig from '../../../../generalTemplates/_ocean_advanced_configuration_note.md' import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md" import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx" +import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx" + # Installation @@ -18,24 +21,24 @@ This page details how to install Port's Azure DevOps integration (powered by the - How to [configure](#configure-the-integration) and customize the integration before deploying it. - How to [deploy](#deploy-the-integration) the integration in the configuration that fits your use case. -:::note Prerequisites +## Prerequisites - An Azure DevOps account with admin privileges. - If you choose the real time & always on installation method, you will need a kubernetes cluster on which to install the integration. - Your Port user role is set to `Admin`. -::: -## Create a personal access token +## Setup + +### Create a personal access token The integration requires a personal access token to authenticate with your Azure DevOps account. You can create one by following [these steps](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows#create-a-pat). The token should either have `admin` permissions, or `read` permissions for each of the supported resources you want to ingest into Port. -## Configure the integration -### `appHost` & listening to hooks +### AppHost & listening to hooks :::tip The `appHost` parameter is used specifically to enable the real-time functionality of the integration. @@ -58,52 +61,28 @@ Choose one of the following installation methods:
Prerequisites
-| Parameter | Description | Example | Required | -| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- | -| `port.clientId` | Your port [client id](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.clientSecret` | Your port [client secret](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | -| `integration.secrets.personalAccessToken` | The [personal access token](#tokenmapping) used to query authenticate with your Azure Devops account | | ✅ | -| `integration.secrets.organizationUrl` | The URL of your Azure DevOps organization | https://dev.azure.com/organizationName | ✅ | -| `integration.secrets.isProjectsLimited` | If using a project-scoped personal access token, this setting is enabled to create webhooks for individual projects. Enabled by default | | ❌ | -| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Azure DevOps | https://my-ocean-integration.com | ✅ | ++
Prerequisites
-| Parameter | Description | Example | Required | -| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------- | -| `port.clientId` | Your Port [client id](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.clientSecret` | Your Port [client secret](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | -| `integration.secrets.tokenMapping` | The [token mapping](#tokenmapping) configuration used to query GitLab | | ✅ | -| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in GitLab | https://my-ocean-integration.com | ✅ | -| `integration.config.gitlabHost` | (for self-hosted GitLab) the URL of your GitLab instance | https://my-gitlab.com | ❌ | -| `integration.secrets.tokenGroupHooksOverrideMapping` | The [token group hooks override mapping](#tokengrouphooksoverridemapping) configuration used to create custom webhooks on groups | | ❌ | ++
+
+
+Team blueprint
+ +```json showLineNumbers +{ + "identifier": "opsGenieTeam", + "description": "This blueprint represents an OpsGenie team in our software catalog", + "title": "OpsGenie Team", + "icon": "OpsGenie", + "schema": { + "properties": { + "description": { + "type": "string", + "title": "Description", + "icon": "DefaultProperty" + }, + "url": { + "title": "URL", + "type": "string", + "description": "URL to the service", + "format": "url", + "icon": "DefaultProperty" + }, + "oncallUsers": { + "type": "array", + "title": "Current Oncalls", + "items": { + "type": "string", + "format": "user" + } + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} +} +``` + +
+
+
+
+## Schedule
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: team + selector: + query: 'true' + port: + entity: + mappings: + identifier: .id + title: .name + blueprint: '"opsGenieTeam"' + properties: + description: .description + url: .links.web +``` + +
+
+
+Schedule blueprint
+ +```json showLineNumbers +{ + "identifier": "opsGenieSchedule", + "description": "This blueprint represents a OpsGenie schedule in our software catalog", + "title": "OpsGenie Schedule", + "icon": "OpsGenie", + "schema": { + "properties": { + "timezone": { + "title": "Timezone", + "type": "string" + }, + "description": { + "title": "Description", + "type": "string" + }, + "users": { + "title": "Users", + "type": "array", + "items": { + "type": "string", + "format": "user" + } + }, + "startDate": { + "title": "Start Date", + "type": "string", + "format": "date-time" + }, + "endDate": { + "title": "End Date", + "type": "string", + "format": "date-time" + }, + "rotationType": { + "type": "string", + "title": "Rotation Type" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "ownerTeam": { + "title": "Owner Team", + "target": "opsGenieTeam", + "required": false, + "many": false + } + } +} +``` + +
+
+
+
+## Service
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: schedule + selector: + query: 'true' + apiQueryParams: + expand: rotation + port: + itemsToParse: .rotations + entity: + mappings: + identifier: .id + "_" + .item.id + title: .name + "_" + .item.name + blueprint: '"opsGenieSchedule"' + properties: + timezone: .timezone + description: .description + startDate: .item.startDate + endDate: .item.endDate + rotationType: .item.type + users: '[.item.participants[] | select(has("username")) | .username]' + relations: + ownerTeam: .ownerTeam.id +``` + +
+
+
+Service blueprint
+ +```json showLineNumbers +{ + "identifier": "opsGenieService", + "description": "This blueprint represents an OpsGenie service in our software catalog", + "title": "OpsGenie Service", + "icon": "OpsGenie", + "schema": { + "properties": { + "description": { + "type": "string", + "title": "Description", + "icon": "DefaultProperty" + }, + "url": { + "title": "URL", + "type": "string", + "description": "URL to the service", + "format": "url", + "icon": "DefaultProperty" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "title": "Tags", + "icon": "DefaultProperty" + } + }, + "required": [] + }, + "mirrorProperties": { + "oncallUsers": { + "title": "Current Oncalls", + "path": "ownerTeam.oncallUsers" + } + }, + "calculationProperties": { + }, + "aggregationProperties": { + "numberOfOpenIncidents": { + "title": "Number of open incidents", + "type": "number", + "target": "opsGenieIncident", + "query": { + "combinator": "and", + "rules": [ + { + "property": "status", + "operator": "=", + "value": "open" + } + ] + }, + "calculationSpec": { + "calculationBy": "entities", + "func": "count" + } + } + }, + "relations": { + "ownerTeam": { + "title": "Owner Team", + "target": "opsGenieTeam", + "required": false, + "many": false + } + } +} +``` + +
+
+
+## Incident
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: service + selector: + query: 'true' + port: + entity: + mappings: + identifier: .id + title: .name + blueprint: '"opsGenieService"' + properties: + description: .description + url: .links.web + tags: .tags + relations: + ownerTeam: .teamId +``` + +
+
+
+Incident blueprint
+ +```json showLineNumbers +{ + "identifier": "opsGenieIncident", + "description": "This blueprint represents an OpsGenie incident in our software catalog", + "title": "OpsGenie Incident", + "icon": "OpsGenie", + "schema": { + "properties": { + "description": { + "title": "Description", + "type": "string" + }, + "status": { + "type": "string", + "title": "Status", + "enum": [ + "closed", + "open", + "resolved" + ], + "enumColors": { + "closed": "blue", + "open": "red", + "resolved": "green" + }, + "description": "The status of the incident" + }, + "url": { + "type": "string", + "format": "url", + "title": "URL" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "title": "Tags" + }, + "responders": { + "type": "array", + "title": "Responders", + "description": "Responders to the alert" + }, + "priority": { + "type": "string", + "title": "Priority" + }, + "createdAt": { + "title": "Create At", + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "title": "Updated At", + "type": "string", + "format": "date-time" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "services": { + "title": "Impacted Services", + "target": "opsGenieService", + "many": true, + "required": false + } + } +} +``` + +
+
+
+## Alert
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: incident + selector: + query: 'true' + apiQueryParams: + status: open + port: + entity: + mappings: + identifier: .id + title: .message + blueprint: '"opsGenieIncident"' + properties: + status: .status + responders: .responders + priority: .priority + tags: .tags + url: .links.web + createdAt: .createdAt + updatedAt: .updatedAt + description: .description + relations: + services: .impactedServices +``` + +
+
+
+Alert blueprint
+ +```json showLineNumbers +{ + "identifier": "opsGenieAlert", + "description": "This blueprint represents an OpsGenie alert in our software catalog", + "title": "OpsGenie Alert", + "icon": "OpsGenie", + "schema": { + "properties": { + "description": { + "title": "Description", + "type": "string" + }, + "status": { + "type": "string", + "title": "Status", + "enum": [ + "closed", + "open" + ], + "enumColors": { + "closed": "green", + "open": "red" + }, + "description": "The status of the alert" + }, + "acknowledged": { + "type": "boolean", + "title": "Acknowledged" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "title": "Tags" + }, + "responders": { + "type": "array", + "title": "Responders", + "description": "Responders to the alert" + }, + "integration": { + "type": "string", + "title": "Integration", + "description": "The name of the Integration" + }, + "priority": { + "type": "string", + "title": "Priority" + }, + "sourceName": { + "type": "string", + "title": "Source Name", + "description": "Alert source name" + }, + "createdBy": { + "title": "Created By", + "type": "string", + "format": "user" + }, + "createdAt": { + "title": "Create At", + "type": "string", + "format": "date-time" + }, + "updatedAt": { + "title": "Updated At", + "type": "string", + "format": "date-time" + }, + "count": { + "title": "Count", + "type": "number" + } + }, + "required": [] + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "relations": { + "relatedIncident": { + "title": "Related Incident", + "target": "opsGenieIncident", + "required": false, + "many": false + } + } +} +``` + +
+
+
+:::tip filter alerts and incidents
+The integration provides an option to filter the data that is retrieved from the OpsGenie API using the following attributes:
+
+1. `createdAt`: The date and time the alert or incident was created
+2. `lastOccurredAt`: The date and time the alert or incident was last occurred
+3. `snoozedUntil`: The date and time the alert or incident was snoozed until
+4. `priority`: The priority of the alert or incident. Accepts values such as `P1`, `P2`, `P3`, `P4` and `P5`
+5. `status`: The status of the alert or incident. Accepts values such as `open`, `closed` and `resolved`
+6. `isSeen`: Whether the alert or incident has been seen. Accepts a boolean `true` or `false`
+7. `acknowledged`: Whether the alert or incident has been acknowledged. Accepts a boolean `true` or `false`
+8. `snoozed`: Whether the alert or incident has been snoozed. Accepts a boolean `true` or `false`
+9. `owner`: The owner of the alert or incident. Accepts an OpsGenie username
+10. `teams`: The teams associated with the alert or incident
+11. `acknowledgedBy`: The user who acknowledged the alert or incident
+12. `closedBy`: The user who closed the alert or incident
+13. `message`: The message of the alert or incident
+
+These attributes can be enabled using the path: `selector.apiQueryParams`. By default, the integration fetches `open` alerts and incidents.
+:::
+
+## Current On-call
+To bring the current on-call users, update your configuration mapping to populate the `OpsGenieTeam` blueprint with team and on-call data. This will enable you to view on-call information at the service level:
+
+Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: alert + selector: + query: 'true' + apiQueryParams: + status: open + port: + entity: + mappings: + identifier: .id + title: .message + blueprint: '"opsGenieAlert"' + properties: + status: .status + acknowledged: .acknowledged + responders: .responders + priority: .priority + sourceName: .source + tags: .tags + count: .count + createdBy: .owner + createdAt: .createdAt + updatedAt: .updatedAt + description: .description + integration: .integration.name + relations: + relatedIncident: 'if (.alias | contains("_")) then (.alias | split("_")[0]) else null end' +``` + +
+
\ No newline at end of file
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/opsgenie.md b/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/opsgenie/opsgenie.md
similarity index 66%
rename from docs/build-your-software-catalog/sync-data-to-catalog/incident-management/opsgenie.md
rename to docs/build-your-software-catalog/sync-data-to-catalog/incident-management/opsgenie/opsgenie.md
index dd606d5b5..6712db05b 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/opsgenie.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/opsgenie/opsgenie.md
@@ -4,32 +4,43 @@ sidebar_position: 2
import Tabs from "@theme/Tabs"
import TabItem from "@theme/TabItem"
-import Prerequisites from "../templates/\_ocean_helm_prerequisites_block.mdx"
-import AzurePremise from "../templates/\_ocean_azure_premise.mdx"
+import Prerequisites from "../../templates/\_ocean_helm_prerequisites_block.mdx"
+import AzurePremise from "../../templates/\_ocean_azure_premise.mdx"
import DockerParameters from "./\_opsgenie_docker_params.mdx"
-import AdvancedConfig from '../../../generalTemplates/_ocean_advanced_configuration_note.md'
+import AdvancedConfig from '../../../../generalTemplates/_ocean_advanced_configuration_note.md'
import OpsGenieAlertBlueprint from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/opsgenie/\_example_opsgenie_alert_blueprint.mdx";
import OpsGenieAlertConfiguration from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/opsgenie/\_example_opsgenie_alert_configuration.mdx";
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+
# Opsgenie
-Port's Opsgenie integration allows you to import `alert`, `incident`, `service`, `team`, `schedule` and `schedule-oncall` from your Opsgenie account into Port, according to your mapping and definitions.
+Port's Opsgenie integration allows you to model Opsgenie resources in your software catalog and ingest data into them.
-## Common use cases
+## Overview
-- Map `alert`, `incident`, `service`, `team`, `schedule`, and `schedule-oncall` in your Opsgenie account.
-- Watch for object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
+This integration allows you to:
-## Prerequisites
-:::info API Token
-An OpsGenie API token with the `read` and `configuration access` scopes is required. Port requires the `read` permission to allow the integration to access incidents and alerts. Port also needs the `configuraton access` permission to allow the integration to access service, teams, and schedules. See [here](https://support.atlassian.com/opsgenie/docs/api-key-management/) for more information on OpsGenie API key management.
-:::
+- Map and organize your desired Opsgenie resources and their metadata in Port (see supported resources below).
+- Watch for Opsgenie object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
+
+
+### Supported Resources
+
+The resources that can be ingested from Opsgenie into Port are listed below. It is possible to reference any field that appears in the API responses linked below in the mapping configuration.
+
+- [`Alert`](https://docs.opsgenie.com/docs/alert-api#list-alerts)
+- [`Incident`](https://docs.opsgenie.com/docs/incident-api#list-incidents)
+- [`Service`](https://docs.opsgenie.com/docs/service-api#list-services)
+- [`Team`](https://docs.opsgenie.com/docs/team-api#list-teams)
+- [`Service`](https://docs.opsgenie.com/docs/service-api#list-services)
+- [`Schedule`](https://docs.opsgenie.com/docs/schedule-api#list-schedules)
+- [`Schedule-Oncall`](https://docs.opsgenie.com/docs/who-is-on-call-api#get-on-calls)
-Integration configuration
+ +```yaml showLineNumbers +createMissingRelatedEntities: true +deleteDependentEntities: true +resources: + - kind: schedule-oncall + selector: + query: 'true' + port: + entity: + mappings: + identifier: .ownerTeam.id + title: .ownerTeam.name + blueprint: '"opsGenieTeam"' + properties: + oncallUsers: .__currentOncalls.onCallRecipients +``` + +Prerequisites
+ +:::info API Token +An OpsGenie API token with the `read` and `configuration access` scopes is required. Port requires the `read` permission to allow the integration to access incidents and alerts. Port also needs the `configuraton access` permission to allow the integration to access service, teams, and schedules. See [here](https://support.atlassian.com/opsgenie/docs/api-key-management/) for more information on OpsGenie API key management. +::: + ++
-
-
-Team blueprint
- -```json showLineNumbers -{ - "identifier": "opsGenieTeam", - "description": "This blueprint represents an OpsGenie team in our software catalog", - "title": "OpsGenie Team", - "icon": "OpsGenie", - "schema": { - "properties": { - "description": { - "type": "string", - "title": "Description", - "icon": "DefaultProperty" - }, - "url": { - "title": "URL", - "type": "string", - "description": "URL to the service", - "format": "url", - "icon": "DefaultProperty" - }, - "oncallUsers": { - "type": "array", - "title": "Current Oncalls", - "items": { - "type": "string", - "format": "user" - } - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": {} -} -``` - -
-
-
-
-### Schedule
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: team - selector: - query: 'true' - port: - entity: - mappings: - identifier: .id - title: .name - blueprint: '"opsGenieTeam"' - properties: - description: .description - url: .links.web -``` - -
-
-
-Schedule blueprint
- -```json showLineNumbers -{ - "identifier": "opsGenieSchedule", - "description": "This blueprint represents a OpsGenie schedule in our software catalog", - "title": "OpsGenie Schedule", - "icon": "OpsGenie", - "schema": { - "properties": { - "timezone": { - "title": "Timezone", - "type": "string" - }, - "description": { - "title": "Description", - "type": "string" - }, - "users": { - "title": "Users", - "type": "array", - "items": { - "type": "string", - "format": "user" - } - }, - "startDate": { - "title": "Start Date", - "type": "string", - "format": "date-time" - }, - "endDate": { - "title": "End Date", - "type": "string", - "format": "date-time" - }, - "rotationType": { - "type": "string", - "title": "Rotation Type" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "ownerTeam": { - "title": "Owner Team", - "target": "opsGenieTeam", - "required": false, - "many": false - } - } -} -``` - -
-
-
-
-### Service
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: schedule - selector: - query: 'true' - apiQueryParams: - expand: rotation - port: - itemsToParse: .rotations - entity: - mappings: - identifier: .id + "_" + .item.id - title: .name + "_" + .item.name - blueprint: '"opsGenieSchedule"' - properties: - timezone: .timezone - description: .description - startDate: .item.startDate - endDate: .item.endDate - rotationType: .item.type - users: '[.item.participants[] | select(has("username")) | .username]' - relations: - ownerTeam: .ownerTeam.id -``` - -
-
-
-Service blueprint
- -```json showLineNumbers -{ - "identifier": "opsGenieService", - "description": "This blueprint represents an OpsGenie service in our software catalog", - "title": "OpsGenie Service", - "icon": "OpsGenie", - "schema": { - "properties": { - "description": { - "type": "string", - "title": "Description", - "icon": "DefaultProperty" - }, - "url": { - "title": "URL", - "type": "string", - "description": "URL to the service", - "format": "url", - "icon": "DefaultProperty" - }, - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "title": "Tags", - "icon": "DefaultProperty" - } - }, - "required": [] - }, - "mirrorProperties": { - "oncallUsers": { - "title": "Current Oncalls", - "path": "ownerTeam.oncallUsers" - } - }, - "calculationProperties": { - }, - "aggregationProperties": { - "numberOfOpenIncidents": { - "title": "Number of open incidents", - "type": "number", - "target": "opsGenieIncident", - "query": { - "combinator": "and", - "rules": [ - { - "property": "status", - "operator": "=", - "value": "open" - } - ] - }, - "calculationSpec": { - "calculationBy": "entities", - "func": "count" - } - } - }, - "relations": { - "ownerTeam": { - "title": "Owner Team", - "target": "opsGenieTeam", - "required": false, - "many": false - } - } -} -``` - -
-
-
-### Incident
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: service - selector: - query: 'true' - port: - entity: - mappings: - identifier: .id - title: .name - blueprint: '"opsGenieService"' - properties: - description: .description - url: .links.web - tags: .tags - relations: - ownerTeam: .teamId -``` - -
-
-
-Incident blueprint
- -```json showLineNumbers -{ - "identifier": "opsGenieIncident", - "description": "This blueprint represents an OpsGenie incident in our software catalog", - "title": "OpsGenie Incident", - "icon": "OpsGenie", - "schema": { - "properties": { - "description": { - "title": "Description", - "type": "string" - }, - "status": { - "type": "string", - "title": "Status", - "enum": [ - "closed", - "open", - "resolved" - ], - "enumColors": { - "closed": "blue", - "open": "red", - "resolved": "green" - }, - "description": "The status of the incident" - }, - "url": { - "type": "string", - "format": "url", - "title": "URL" - }, - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "title": "Tags" - }, - "responders": { - "type": "array", - "title": "Responders", - "description": "Responders to the alert" - }, - "priority": { - "type": "string", - "title": "Priority" - }, - "createdAt": { - "title": "Create At", - "type": "string", - "format": "date-time" - }, - "updatedAt": { - "title": "Updated At", - "type": "string", - "format": "date-time" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "services": { - "title": "Impacted Services", - "target": "opsGenieService", - "many": true, - "required": false - } - } -} -``` - -
-
-
-### Alert
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: incident - selector: - query: 'true' - apiQueryParams: - status: open - port: - entity: - mappings: - identifier: .id - title: .message - blueprint: '"opsGenieIncident"' - properties: - status: .status - responders: .responders - priority: .priority - tags: .tags - url: .links.web - createdAt: .createdAt - updatedAt: .updatedAt - description: .description - relations: - services: .impactedServices -``` - -
-
-
-Alert blueprint
- -```json showLineNumbers -{ - "identifier": "opsGenieAlert", - "description": "This blueprint represents an OpsGenie alert in our software catalog", - "title": "OpsGenie Alert", - "icon": "OpsGenie", - "schema": { - "properties": { - "description": { - "title": "Description", - "type": "string" - }, - "status": { - "type": "string", - "title": "Status", - "enum": [ - "closed", - "open" - ], - "enumColors": { - "closed": "green", - "open": "red" - }, - "description": "The status of the alert" - }, - "acknowledged": { - "type": "boolean", - "title": "Acknowledged" - }, - "tags": { - "type": "array", - "items": { - "type": "string" - }, - "title": "Tags" - }, - "responders": { - "type": "array", - "title": "Responders", - "description": "Responders to the alert" - }, - "integration": { - "type": "string", - "title": "Integration", - "description": "The name of the Integration" - }, - "priority": { - "type": "string", - "title": "Priority" - }, - "sourceName": { - "type": "string", - "title": "Source Name", - "description": "Alert source name" - }, - "createdBy": { - "title": "Created By", - "type": "string", - "format": "user" - }, - "createdAt": { - "title": "Create At", - "type": "string", - "format": "date-time" - }, - "updatedAt": { - "title": "Updated At", - "type": "string", - "format": "date-time" - }, - "count": { - "title": "Count", - "type": "number" - } - }, - "required": [] - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "relations": { - "relatedIncident": { - "title": "Related Incident", - "target": "opsGenieIncident", - "required": false, - "many": false - } - } -} -``` - -
-
-
-:::tip filter alerts and incidents
-The integration provides an option to filter the data that is retrieved from the OpsGenie API using the following attributes:
-
-1. `createdAt`: The date and time the alert or incident was created
-2. `lastOccurredAt`: The date and time the alert or incident was last occurred
-3. `snoozedUntil`: The date and time the alert or incident was snoozed until
-4. `priority`: The priority of the alert or incident. Accepts values such as `P1`, `P2`, `P3`, `P4` and `P5`
-5. `status`: The status of the alert or incident. Accepts values such as `open`, `closed` and `resolved`
-6. `isSeen`: Whether the alert or incident has been seen. Accepts a boolean `true` or `false`
-7. `acknowledged`: Whether the alert or incident has been acknowledged. Accepts a boolean `true` or `false`
-8. `snoozed`: Whether the alert or incident has been snoozed. Accepts a boolean `true` or `false`
-9. `owner`: The owner of the alert or incident. Accepts an OpsGenie username
-10. `teams`: The teams associated with the alert or incident
-11. `acknowledgedBy`: The user who acknowledged the alert or incident
-12. `closedBy`: The user who closed the alert or incident
-13. `message`: The message of the alert or incident
-
-These attributes can be enabled using the path: `selector.apiQueryParams`. By default, the integration fetches `open` alerts and incidents.
-:::
-
-### Current On-call
-To bring the current on-call users, update your configuration mapping to populate the `OpsGenieTeam` blueprint with team and on-call data. This will enable you to view on-call information at the service level:
-
-Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: alert - selector: - query: 'true' - apiQueryParams: - status: open - port: - entity: - mappings: - identifier: .id - title: .message - blueprint: '"opsGenieAlert"' - properties: - status: .status - acknowledged: .acknowledged - responders: .responders - priority: .priority - sourceName: .source - tags: .tags - count: .count - createdBy: .owner - createdAt: .createdAt - updatedAt: .updatedAt - description: .description - integration: .integration.name - relations: - relatedIncident: 'if (.alias | contains("_")) then (.alias | split("_")[0]) else null end' -``` - -
-
+Examples of blueprints and the relevant integration configurations can be found on the opsgenie [examples page](examples.md)
## Let's Test It
@@ -1660,8 +1019,6 @@ The examples below pull data from the OpsGenie REST Api, in a defined scheduled
## Migration Guide to Version 0.2.0
This guide outlines how to update your existing OpsGenie integration configuration to take advantage of the performance improvements and breaking changes introduced in version 0.2.0.
-Below is an overview of changes in version 0.2.0
-
### Key Improvements
- **New Blueprints and Kinds**: Added new kinds for team, schedule, and schedule-oncall.
@@ -1676,7 +1033,8 @@ Below is an overview of changes in version 0.2.0
### Migration Steps
-#### Step 1: Understand Existing Configuration
+Integration configuration
- -```yaml showLineNumbers -createMissingRelatedEntities: true -deleteDependentEntities: true -resources: - - kind: schedule-oncall - selector: - query: 'true' - port: - entity: - mappings: - identifier: .ownerTeam.id - title: .ownerTeam.name - blueprint: '"opsGenieTeam"' - properties: - oncallUsers: .__currentOncalls.onCallRecipients -``` - -Step 1: Understand Existing Configuration
+ In versions prior to 0.2.0, your Port app's configuration may have used a mapping like the one below:
@@ -1749,7 +1107,8 @@ resources:
```
-#### Step 2: Update to New Configuration
+Step 2: Update to New Configuration
+ To adapt to version 0.2.0, you will need to update your configuration as follows:
@@ -1824,7 +1183,7 @@ resources:
In the updated configuration, the `opsGenieService` blueprint no longer includes properties like `oncallTeam`, `teamMembers`, and `oncallUsers`. These properties are now part of the new `OpsGenieTeam` blueprint. If you need to track on-call teams and users for each service, follow the steps below.
-#### Step 3: Create the OpsGenieTeam Blueprint
+
-#### Step 4: Update the OpsGenieService Blueprint
+Step 3: Create the OpsGenieTeam Blueprint
To manage team-related data, create a new `OpsGenieTeam` blueprint in Port using the following schema: @@ -1870,7 +1229,7 @@ To manage team-related data, create a new `OpsGenieTeam` blueprint in Port using ```Step 4: Update the OpsGenieService Blueprint
Next, update the `opsGenieService` blueprint to reference the `OpsGenieTeam` blueprint by establishing a relation and mirroring relevant properties: @@ -1949,7 +1308,7 @@ Next, update the `opsGenieService` blueprint to reference the `OpsGenieTeam` blu ``` -#### Step 5: Update the Mapping Configuration +Step 5: Update the Mapping Configuration
Update your configuration mapping to correctly populate the `OpsGenieTeam` blueprint with team and on-call data. This will enable you to view on-call team information at the service level: @@ -2001,7 +1360,7 @@ resources: ``` -#### Final Step: Full Configuration Example +Final Step: Full Configuration Example
After completing these changes, your configuration should look like this, incorporating blueprints for `team`, `service`, `alert` and `incident`:
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/example.md b/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/examples.md
similarity index 100%
rename from docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/example.md
rename to docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/examples.md
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/pagerduty.md b/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/pagerduty.md
index 514e87467..dec781e01 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/pagerduty.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/incident-management/pagerduty/pagerduty.md
@@ -57,6 +57,9 @@ Choose one of the following installation methods:
+Using this installation option means that the integration will be able to update Port in real time using webhooks.
+
+
-
-
-
-This workflow will run the PagerDuty integration once and then exit, this is useful for **scheduled** ingestion of data.
-:::warning
-If you want the integration to update Port in real time using webhooks you should use the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option
+This workflow/pipeline will run the PagerDuty integration once and then exit, this is useful for **scheduled** ingestion of data.
+
+:::warning Real-time updates
+If you want the integration to update Port in real time using webhooks you should use the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
:::
+
+
Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):
@@ -227,16 +231,11 @@ jobs:
-This pipeline will run the PagerDuty integration once and then exit, this is useful for **scheduled** ingestion of data.
:::tip
Your Jenkins agent should be able to run docker commands.
:::
-:::warning
-If you want the integration to update Port in real time using webhooks you should use
-the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
-:::
Make sure to configure the following [Jenkins Credentials](https://www.jenkins.io/doc/book/using/using-credentials/)
of `Secret Text` type:
@@ -290,7 +289,7 @@ pipeline {
-
-This workflow will run the PagerDuty integration once and then exit, this is useful for **scheduled** ingestion of data.
-
-:::warning Realtime updates in Port
-If you want the integration to update Port in real time using webhooks you should use the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
-:::
Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project):
@@ -772,7 +766,7 @@ To enrich your PagerDuty incident entities with analytics data, follow the steps
To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your [data sources page](https://app.getport.io/settings/data-sources). Find the integration in the list of data sources and click on it to open the playground.
-Additional examples of blueprints and the relevant integration configurations can be found on the pagerduty [examples page](example.md)
+Additional examples of blueprints and the relevant integration configurations can be found on the pagerduty [examples page](examples.md)
## Let's Test It
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/project-management/jira/jira.md b/docs/build-your-software-catalog/sync-data-to-catalog/project-management/jira/jira.md
index 5197e6323..3df3e5a4b 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/project-management/jira/jira.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/project-management/jira/jira.md
@@ -10,6 +10,8 @@ import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_expl
import JiraIssueBlueprint from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/jira/\_example_jira_issue_blueprint.mdx"
import JiraIssueConfiguration from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/jira/\_example_jira_issue_configuration.mdx"
import JiraIssueConfigurationPython from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/jira/\_example_jira_issue_configuration_python.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+
# Jira
@@ -50,49 +52,23 @@ Choose one of the following installation methods:
Using this installation option means that the integration will be able to update Port in real time using webhooks.
-This table summarizes the available parameters for the installation.
-Set them as you wish in the script below, then copy it and run it in your terminal:
+
-To install the integration using Helm, run the following command:
-
-```bash showLineNumbers
-helm repo add --force-update port-labs https://port-labs.github.io/helm-charts
-helm upgrade --install my-jira-integration port-labs/port-ocean \
- --set port.clientId="PORT_CLIENT_ID" \
- --set port.clientSecret="PORT_CLIENT_SECRET" \
- --set port.baseUrl="https://api.getport.io" \
- --set initializePortResources=true \
- --set sendRawDataExamples=true \
- --set scheduledResyncInterval=120 \
- --set integration.identifier="my-jira-integration" \
- --set integration.type="jira" \
- --set integration.eventListener.type="POLLING" \
- --set integration.config.jiraHost="string" \
- --set integration.secrets.atlassianUserEmail="string" \
- --set integration.secrets.atlassianUserToken="string"
-```
+
+
-To install the integration using ArgoCD, follow these steps:
+To install the integration using ArgoCD:
1. Create a `values.yaml` file in `argocd/my-ocean-jira-integration` in your git repository with the content:
@@ -184,35 +160,53 @@ kubectl apply -f my-ocean-jira-integration.yaml
+This table summarizes the available parameters for the installation.
+
+| Parameter | Description | Example | Required |
+|------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------|----------|
+| `port.clientId` | Your port [client id](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ |
+| `port.clientSecret` | Your port [client secret](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ |
+| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ |
+| `integration.secrets.atlassianUserEmail` | The email of the user used to query Jira | user@example.com | ✅ |
+| `integration.secrets.atlassianUserToken` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user | | ✅ |
+| `integration.config.jiraHost` | The URL of your Jira | https://example.atlassian.net | ✅ |
+| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Jira | https://my-ocean-integration.com | ✅ |
+| `integration.eventListener.type` | The event listener type. Read more about [event listeners](https://ocean.getport.io/framework/features/event-listener) | | ✅ |
+| `integration.type` | The integration to be installed | | ✅ |
+| `scheduledResyncInterval` | The number of minutes between each resync. When not set the integration will resync for each event listener resync event. Read more about [scheduledResyncInterval](https://ocean.getport.io/develop-an-integration/integration-configuration/#scheduledresyncinterval---run-scheduled-resync) | | ❌ |
+| `initializePortResources` | Default true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | | ❌ |
+| `sendRawDataExamples` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | | ❌ |
+
+
-
-
-This workflow will run the Jira integration once and then exit, this is useful for **scheduled** ingestion of data.
+This workflow/pipeline will run the Jira integration once and then exit, this is useful for **scheduled** ingestion of data.
-:::warning Realtime updates in Port
+:::warning Realtime updates
If you want the integration to update Port in real time using webhooks you should use the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
:::
+
+
+
Make sure to configure the following [Github Secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions):
| Parameter | Description | Example | Required |
|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|----------|
| `port_client_id` | Your Port client ([How to get the credentials](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) id | | ✅ |
| `port_client_secret` | Your Port client ([How to get the credentials](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials)) secret | | ✅ |
-| `port_base_url` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ |
+| `port_base_url` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ |
| `config -> jira_host` | The URL of your Jira | https://example.atlassian.net | ✅ |
| `config -> atlassian_user_email` | The email of the user used to query Jira | user@example.com | ✅ |
| `config -> atlassian_user_token` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user | | ✅ |
| `initialize_port_resources` | Default true, When set to true the integration will create default blueprints and the port App config Mapping. Read more about [initializePortResources](https://ocean.getport.io/develop-an-integration/integration-configuration/#initializeportresources---initialize-port-resources) | | ❌ |
-| `send_raw_data_examples` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | | ❌ |
-
+| `send_raw_data_examples` | Enable sending raw data examples from the third party API to port for testing and managing the integration mapping. Default is true | | ❌ |
| `identifier` | The identifier of the integration that will be installed | | ❌ |
-| `version` | The version of the integration that will be installed | latest | ❌ |`
+| `version` | The version of the integration that will be installed | latest | ❌ |
@@ -253,15 +247,11 @@ jobs:
-This pipeline will run the Jira integration once and then exit, this is useful for **scheduled** ingestion of data.
:::tip Tip for Jenkins agent
Your Jenkins agent should be able to run docker commands.
:::
-:::warning Realtime updates in Port
-If you want the integration to update Port in real time using webhooks you should use the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
-:::
Make sure to configure the following [Jenkins Credentials](https://www.jenkins.io/doc/book/using/using-credentials/) of `Secret Text` type:
@@ -316,7 +306,7 @@ pipeline {
-
-This workflow will run the Jira integration once and then exit, this is useful for **scheduled** ingestion of data.
-:::warning Realtime updates in Port
-If you want the integration to update Port in real time using webhooks you should use the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
-:::
+
Make sure to [configure the following GitLab variables](https://docs.gitlab.com/ee/ci/variables/#for-a-project):
@@ -680,6 +667,292 @@ resources:
+
+## Let's Test It
+
+This section includes a sample response data from Jira. In addition, it includes the entity created from the resync event based on the Ocean configuration provided in the previous section.
+
+### Payload
+
+Here is an example of the payload structure from Jira:
+
+Prerequisites
Prerequisites
-| Parameter | Description | Example | Required | -| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------- | -| `port.clientId` | Your port [client id](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.clientSecret` | Your port [client secret](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | -| `integration.secrets.atlassianUserEmail` | The email of the user used to query Jira | user@example.com | ✅ | -| `integration.secrets.atlassianUserToken` | [Jira API token](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/) generated by the user | | ✅ | -| `integration.config.jiraHost` | The URL of your Jira | https://example.atlassian.net | ✅ | -| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Jira | https://my-ocean-integration.com | ✅ | +@@ -253,15 +247,11 @@ jobs:
+
+
+Project response data
+ +```json showLineNumbers +{ + "expand": "description,lead,issueTypes,url,projectKeys,permissions,insight", + "self": "https://myaccount.atlassian.net/rest/api/3/project/10000", + "id": "10000", + "key": "PA", + "name": "Port-AI", + "avatarUrls": { + "48x48": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413", + "24x24": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=small", + "16x16": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=xsmall", + "32x32": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=medium" + }, + "projectTypeKey": "software", + "simplified": true, + "style": "next-gen", + "isPrivate": false, + "properties": {}, + "entityId": "7f4f8d6f-705b-4074-84be-46f0d012cd8e", + "uuid": "7f4f8d6f-705b-4074-84be-46f0d012cd8e" +} +``` + +
+
+
+### Mapping Result
+
+The combination of the sample payload and the Ocean configuration generates the following Port entity:
+
+Issue response data
+ +```json showLineNumbers +{ + "expand": "operations,versionedRepresentations,editmeta,changelog,customfield_10010.requestTypePractice,renderedFields", + "id": "10000", + "self": "https://myaccount.atlassian.net/rest/api/3/issue/10000", + "key": "PA-1", + "fields": { + "statuscategorychangedate": "2023-11-06T11:02:59.341+0000", + "issuetype": { + "self": "https://myaccount.atlassian.net/rest/api/3/issuetype/10001", + "id": "10001", + "description": "Tasks track small, distinct pieces of work.", + "iconUrl": "https://myaccount.atlassian.net/rest/api/2/universal_avatar/view/type/issuetype/avatar/10318?size=medium", + "name": "Task", + "subtask": false, + "avatarId": 10318, + "entityId": "a7309bf9-70c5-4237-bdaf-0261037b6ecc", + "hierarchyLevel": 0 + }, + "timespent": "None", + "customfield_10030": "None", + "project": { + "self": "https://myaccount.atlassian.net/rest/api/3/project/10000", + "id": "10000", + "key": "PA", + "name": "Port-AI", + "projectTypeKey": "software", + "simplified": true, + "avatarUrls": { + "48x48": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413", + "24x24": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=small", + "16x16": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=xsmall", + "32x32": "https://myaccount.atlassian.net/rest/api/3/universal_avatar/view/type/project/avatar/10413?size=medium" + } + }, + "customfield_10031": "None", + "customfield_10032": "None", + "fixVersions": [], + "aggregatetimespent": "None", + "resolution": "None", + "customfield_10027": "None", + "customfield_10028": "None", + "customfield_10029": "None", + "resolutiondate": "None", + "workratio": -1, + "watches": { + "self": "https://myaccount.atlassian.net/rest/api/3/issue/PA-1/watchers", + "watchCount": 1, + "isWatching": true + }, + "lastViewed": "None", + "created": "2023-11-06T11:02:59.000+0000", + "customfield_10020": "None", + "customfield_10021": "None", + "customfield_10022": "None", + "priority": { + "self": "https://myaccount.atlassian.net/rest/api/3/priority/3", + "iconUrl": "https://myaccount.atlassian.net/images/icons/priorities/medium.svg", + "name": "Medium", + "id": "3" + }, + "customfield_10023": "None", + "customfield_10024": "None", + "customfield_10025": "None", + "labels": ["infra"], + "customfield_10026": "None", + "customfield_10016": "None", + "customfield_10017": "None", + "customfield_10018": { + "hasEpicLinkFieldDependency": false, + "showField": false, + "nonEditableReason": { + "reason": "PLUGIN_LICENSE_ERROR", + "message": "The Parent Link is only available to Jira Premium users." + } + }, + "customfield_10019": "0|hzzzzz:", + "timeestimate": "None", + "aggregatetimeoriginalestimate": "None", + "versions": [], + "issuelinks": [], + "assignee": { + "self": "https://myaccount.atlassian.net/rest/api/3/user?accountId=712020%3A05acda87-42da-44d8-b21e-f71a508e5d11", + "accountId": "712020:05acda87-42da-44d8-b21e-f71a508e5d11", + "emailAddress": "username@example.com.io", + "avatarUrls": { + "48x48": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "24x24": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "16x16": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "32x32": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png" + }, + "displayName": "User Name", + "active": true, + "timeZone": "UTC", + "accountType": "atlassian" + }, + "updated": "2023-11-06T11:03:18.244+0000", + "status": { + "self": "https://myaccount.atlassian.net/rest/api/3/status/10000", + "description": "", + "iconUrl": "https://myaccount.atlassian.net/", + "name": "To Do", + "id": "10000", + "statusCategory": { + "self": "https://myaccount.atlassian.net/rest/api/3/statuscategory/2", + "id": 2, + "key": "new", + "colorName": "blue-gray", + "name": "To Do" + } + }, + "components": [], + "timeoriginalestimate": "None", + "description": "None", + "customfield_10010": "None", + "customfield_10014": "None", + "customfield_10015": "None", + "customfield_10005": "None", + "customfield_10006": "None", + "security": "None", + "customfield_10007": "None", + "customfield_10008": "None", + "aggregatetimeestimate": "None", + "customfield_10009": "None", + "summary": "Setup infra", + "creator": { + "self": "https://myaccount.atlassian.net/rest/api/3/user?accountId=712020%3A05acda87-42da-44d8-b21e-f71a508e5d11", + "accountId": "712020:05acda87-42da-44d8-b21e-f71a508e5d11", + "emailAddress": "username@example.com.io", + "avatarUrls": { + "48x48": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "24x24": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "16x16": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "32x32": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png" + }, + "displayName": "User Name", + "active": true, + "timeZone": "UTC", + "accountType": "atlassian" + }, + "subtasks": [], + "reporter": { + "self": "https://myaccount.atlassian.net/rest/api/3/user?accountId=712020%3A05acda87-42da-44d8-b21e-f71a508e5d11", + "accountId": "712020:05acda87-42da-44d8-b21e-f71a508e5d11", + "emailAddress": "username@example.com.io", + "avatarUrls": { + "48x48": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "24x24": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "16x16": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png", + "32x32": "https://secure.gravatar.com/avatar/0d5d34ceb820d324d69046a1b2f51dc0?d=https%3A%2F%2Favatar-management--avatars.us-west-2.prod.public.atl-paas.net%2Finitials%2FIC-3.png" + }, + "displayName": "User Name", + "active": true, + "timeZone": "UTC", + "accountType": "atlassian" + }, + "aggregateprogress": { + "progress": 0, + "total": 0 + }, + "customfield_10001": "None", + "customfield_10002": "None", + "customfield_10003": "None", + "customfield_10004": "None", + "environment": "None", + "duedate": "None", + "progress": { + "progress": 0, + "total": 0 + }, + "votes": { + "self": "https://myaccount.atlassian.net/rest/api/3/issue/PA-1/votes", + "votes": 0, + "hasVoted": false + } + } +} +``` + +
+
+
+Project entity in Port
+ +```json showLineNumbers +{ + "identifier": "PA", + "title": "Port-AI", + "icon": null, + "blueprint": "jiraProject", + "team": [], + "properties": { + "url": "https://myaccount.atlassian.net/projects/PA", + "totalIssues": 100 + }, + "relations": {}, + "createdAt": "2023-11-06T11:22:05.433Z", + "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW", + "updatedAt": "2023-11-06T11:22:05.433Z", + "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW" +} +``` + +
+
+
+
## Relevant Guides
For relevant guides and examples, see the [guides section](https://docs.getport.io/guides?tags=Jira).
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/project-management/linear/linear.md b/docs/build-your-software-catalog/sync-data-to-catalog/project-management/linear/linear.md
index ca61bffd0..a883baa63 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/project-management/linear/linear.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/project-management/linear/linear.md
@@ -10,6 +10,7 @@ import LinearIssueBlueprint from "/docs/build-your-software-catalog/custom-integ
import LinearIssueConfiguration from "/docs/build-your-software-catalog/custom-integration/webhook/examples/resources/linear/\_example_linear_issue_configuration.mdx"
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
# Linear
@@ -43,53 +44,27 @@ Choose one of the following installation methods:
Issue entity in Port
+ +```json showLineNumbers +{ + "identifier": "PA-1", + "title": "Setup infra", + "icon": null, + "blueprint": "jiraIssue", + "team": [], + "properties": { + "url": "https://myaccount.atlassian.net/browse/PA-1", + "status": "To Do", + "issueType": "Task", + "components": [], + "assignee": "username@example.com.io", + "reporter": "username@example.com.io", + "creator": "username@example.com.io", + "priority": "3", + "created": "2023-11-06T11:02:59.000+0000", + "updated": "2023-11-06T11:03:18.244+0000" + }, + "relations": { + "parentIssue": null, + "project": "PA", + "subtasks": [] + }, + "createdAt": "2023-11-06T11:22:07.550Z", + "createdBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW", + "updatedAt": "2023-11-06T11:22:07.550Z", + "updatedBy": "hBx3VFZjqgLPEoQLp7POx5XaoB0cgsxW" +} +``` + +Prerequisites
- -Prerequisites
-| Parameter | Description | Example | Required | -| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------- | ------- | -| `port.clientId` | Your port [client id](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.clientSecret` | Your port [client secret](https://docs.getport.io/build-your-software-catalog/custom-integration/api/#find-your-port-credentials) | | ✅ | -| `port.baseUrl` | Your Port API URL - `https://api.getport.io` for EU, `https://api.us.getport.io` for US | | ✅ | -| `integration.secrets.linearApiKey` | Linear [API key](https://developers.linear.app/docs/graphql/working-with-the-graphql-api#personal-api-keys) used to query the Linear GraphQL API | | ✅ | -| `integration.config.appHost` | The host of the Port Ocean app. Used to set up the integration endpoint as the target for webhooks created in Linear | https://my-ocean-integration.com | ✅ | ++
:::tip Ocean Sail Github Action @@ -240,15 +233,11 @@ jobs:
+
+
+Team response data
+ +```json showLineNumbers +{ + "id": "92d25fa4-fb1c-449f-b314-47f82e8f280d", + "name": "Port", + "key": "POR", + "description": null, + "organization": { + "id": "36968e1b-496c-4610-8c25-641364da172e", + "name": "Getport", + "urlKey": "getport" + } +} +``` + +
+
+
+
+Label response data
+ +```json showLineNumbers +{ + "id": "36f84d2c-7b7d-4a71-96f2-6ea4140004d5", + "createdAt": "2024-05-17T15:17:40.858Z", + "updatedAt": "2024-05-17T15:17:40.858Z", + "archivedAt": null, + "name": "New-sample-label", + "description": null, + "color": "#bec2c8", + "isGroup": true, + "parent": null, + "children": { + "edges": [ + { + "node": { + "id": "2e483c90-2aca-4db6-924d-b0571d49f691" + } + } + ] + } +} +``` + +
+
+
+### Mapping Result
+
+The combination of the sample payload and the Ocean configuration generates the following Port entity:
+
+Issue response data
+ +```json showLineNumbers +{ + "id": "9b4745c2-a8e6-4432-9e56-0fa97b79ccbf", + "createdAt": "2024-05-16T21:52:00.299Z", + "updatedAt": "2024-05-17T09:27:40.077Z", + "archivedAt": null, + "number": 2, + "title": "sub issue with new title", + "priority": 3, + "estimate": null, + "sortOrder": -991, + "startedAt": null, + "completedAt": null, + "startedTriageAt": null, + "triagedAt": null, + "canceledAt": null, + "autoClosedAt": null, + "autoArchivedAt": null, + "dueDate": null, + "slaStartedAt": null, + "slaBreachesAt": null, + "trashed": null, + "snoozedUntilAt": null, + "labelIds": [ + "402b218c-938c-4ddf-85db-0019bc632316" + ], + "previousIdentifiers": [], + "subIssueSortOrder": -56.17340471045278, + "priorityLabel": "Medium", + "integrationSourceType": null, + "identifier": "POR-2", + "url": "https://linear.app/getport/issue/POR-2/sub-issue-with-new-title", + "branchName": "mor/por-2-sub-issue-with-new-title", + "customerTicketCount": 0, + "description": "", + "descriptionState": "AQG/pOWPAgAHAQtwcm9zZW1pcnJvcgMJcGFyYWdyYXBoAA==", + "team": { + "id": "92d25fa4-fb1c-449f-b314-47f82e8f280d", + "name": "Port", + "key": "POR" + }, + "state": { + "name": "Todo" + }, + "creator": { + "name": "Mor Paz", + "email": "mor@getport.io" + }, + "assignee": { + "name": "Dudi Elhadad", + "email": "dudi@getport.io" + }, + "parent": { + "id": "5ddd8e85-ad89-4c96-b901-0b901b29100d", + "identifier": "POR-1" + } +} + +``` + +
+
+
+Team entity in Port
+ +```json showLineNumbers +{ + "identifier": "POR", + "title": "Port", + "icon": null, + "blueprint": "linearTeam", + "team": [], + "properties": { + "url": "https://linear.app/getport/team/POR", + "workspaceName": "Getport" + }, + "relations": {}, + "createdAt": "2024-05-19T16:19:15.232Z", + "createdBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE", + "updatedAt": "2024-05-19T16:19:15.232Z", + "updatedBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE" +} +``` + +
+
+
+Label entity in Port
+ +```json showLineNumbers +{ + "identifier": "36f84d2c-7b7d-4a71-96f2-6ea4140004d5", + "title": "New-sample-label", + "icon": null, + "blueprint": "linearLabel", + "team": [], + "properties": { + "isGroup": false + }, + "relations": { + "childLabels": [], + "parentLabel": null + }, + "createdAt": "2024-05-19T16:19:17.747Z", + "createdBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE", + "updatedAt": "2024-05-19T16:19:17.747Z", + "updatedBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE" +} +``` + +
+
+
## Alternative installation via webhook
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_azure_premise.mdx b/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_azure_premise.mdx
index 1a55fb191..342588ae5 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_azure_premise.mdx
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_azure_premise.mdx
@@ -1,27 +1,18 @@
-This pipeline will run the {props.name} integration once and then exit, this is useful for **scheduled** ingestion of data.
-
:::tip
Your Azure Devops agent should be able to run docker commands. Learn more about agents [here](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/agents?view=azure-devops&tabs=yaml%2Cbrowser).
:::
-:::warning
-If you want the integration to update Port in real time using webhooks you should use
-the [Real Time & Always On](?installation-methods=real-time-always-on#installation) installation option.
-:::
-
Issue entity in Port
+ +```json showLineNumbers +{ + "identifier": "POR-2", + "title": "sub issue with new title", + "icon": null, + "blueprint": "linearIssue", + "team": [], + "properties": { + "status": "Todo", + "url": "https://linear.app/getport/issue/POR-2/sub-issue-with-new-title", + "created": "2024-05-16T21:52:00.299Z", + "priority": "Medium", + "assignee": "dudi@getport.io", + "updated": "2024-05-17T09:27:40.077Z", + "creator": "mor@getport.io" + }, + "relations": { + "team": "POR", + "labels": [ + "402b218c-938c-4ddf-85db-0019bc632316" + ], + "parentIssue": "POR-1" + }, + "createdAt": "2024-05-19T16:19:21.143Z", + "createdBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE", + "updatedAt": "2024-05-19T16:19:21.143Z", + "updatedBy": "KZ5zDPudPshQMShUb4cLopBEE1fNSJGE" +} +``` + +-:::tip Configure the variables in a variable group Variable groups store values and secrets you'll use in your pipelines across your project. [Learn more](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups?view=azure-devops&tabs=yaml) **Setting Up Your Credentials** -1. Create a Variable Group: Name it **port-ocean-credentials**. Store the required variables from the table. -2. Authorize Your Pipeline: +1. Create a Variable Group: Name it **port-ocean-credentials**. +2. Store the required variables (see the table below). +3. Authorize Your Pipeline: - Go to **"Library" -> "Variable groups."** - Find **port-ocean-credentials** and click on it. - Select "Pipeline Permissions" and add your pipeline to the authorized list.
-:::
-
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/_category_.json b/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/_category_.json index 9b33d01ca..aec5cb1df 100644 --- a/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/_category_.json +++ b/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/_category_.json @@ -1,4 +1,4 @@ { - "label": "Terraform Cloud", + "label": "Terraform", "position": 12 } diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/examples.md b/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/examples.md new file mode 100644 index 000000000..30e7bc1a1 --- /dev/null +++ b/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/examples.md @@ -0,0 +1,475 @@ +--- +sidebar_position: 2 +--- + +# Examples +To view and test the integration's mapping against examples of the third-party API responses, use the jq playground in your [data sources page](https://app.getport.io/settings/data-sources). Find the integration in the list of data sources and click on it to open the playground. + +## Organization + +
+
+
+Organization blueprint
+ +```json showLineNumbers + { + "identifier": "terraformCloudOrganization", + "description": "This blueprint represents an organization in Terraform Cloud", + "title": "Terraform Cloud Organization", + "icon": "Terraform", + "schema": { + "properties": { + "externalId": { + "type": "string", + "title": "External ID", + "description": "The external ID of the organization" + }, + "ownerEmail": { + "type": "string", + "title": "Owner Email", + "description": "The email associated with the organization" + }, + "collaboratorAuthPolicy": { + "type": "string", + "title": "Collaborator Authentication Policy", + "description": "Policy for collaborator authentication" + }, + "planExpired": { + "type": "string", + "title": "Plan Expired", + "description": "Indicates if plan is expired" + }, + "planExpiresAt": { + "type": "string", + "format": "date-time", + "title": "Plan Expiry Date", + "description": "The data and time which the plan expires" + }, + "permissions": { + "type": "object", + "title": "Permissions", + "description": "Permissions associated with the organization" + }, + "samlEnabled": { + "type": "boolean", + "title": "SAML Enabled", + "description": "Indicates if SAML is enabled for the organization" + }, + "defaultExecutionMode": { + "type": "string", + "title": "Default Execution Mode", + "description": "The default execution mode for the organization" + } + } + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": {} + } +``` +
+
+
+## Project
+Integration configuration
+ +```yaml showLineNumbers +- kind: organization + selector: + query: "true" + port: + entity: + mappings: + identifier: .id + title: .attributes.name + blueprint: '"terraformCloudOrganization"' + properties: + externalId: .attributes."external-id" + ownerEmail: .attributes.email + collaboratorAuthPolicy: .attributes."collaborator-auth-policy" + planExpired: .attributes."plan-expired" + planExpiresAt: .attributes."plan-expires-at" + permissions: .attributes.permissions + samlEnabled: .attributes."saml-enabled" + defaultExecutionMode: .attributes."default-execution-mode" +``` +
+
+
+Project blueprint
+ +```json showLineNumbers + { + "identifier": "terraformCloudProject", + "description": "This blueprint represents a project in Terraform Cloud", + "title": "Terraform Cloud Project", + "icon": "Terraform", + "schema": { + "properties": { + "name": { + "type": "string", + "title": "Project Name", + "description": "The name of the Terraform Cloud project" + }, + "permissions": { + "type": "object", + "title": "Permissions", + "description": "The permisssions on the project" + } + } + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "organization": { + "title": "Terraform Cloud Organization", + "target": "terraformCloudOrganization", + "required": true, + "many": false + } + } + } +``` +
+
+
+## Workspace
+
+Integration configuration
+ +```yaml showLineNumbers +- kind: project + selector: + query: "true" + port: + entity: + mappings: + identifier: .id + title: .attributes.name + blueprint: '"terraformCloudProject"' + properties: + name: .attributes.name + permissions: .attributes.permissions + relations: + organization: .relationships.organization.data.id +``` +
+
+
+
+Workspace blueprint
+ +```json showLineNumbers + { + "identifier": "terraformCloudWorkspace", + "description": "This blueprint represents a workspace in Terraform Cloud", + "title": "Terraform Cloud Workspace", + "icon": "Terraform", + "schema": { + "properties": { + "organization": { + "type": "string", + "title": "Organization", + "description": "The organization within which the workspace belongs to" + }, + "createdAt": { + "type": "string", + "format": "date-time", + "title": "Creation Time", + "description": "The creation timestamp of the workspace" + }, + "updatedAt": { + "type": "string", + "format": "date-time", + "title": "Last Updated", + "description": "The last update timestamp of the workspace" + }, + "terraformVersion": { + "type": "string", + "title": "Terraform Cloud Version", + "description": "Version of Terraform cloud used by the workspace" + }, + "locked": { + "type": "boolean", + "title": "Locked Status", + "description": "Indicates whether the workspace is locked" + }, + "executionMode": { + "type": "string", + "title": "Execution Mode", + "description": "The execution mode of the workspace" + }, + "resourceCount": { + "type": "number", + "title": "Resource Count", + "description": "Number of resources managed by the workspace" + }, + "latestChangeAt": { + "type": "string", + "format": "date-time", + "title": "Latest Change", + "description": "Timestamp of the latest change in the workspace" + }, + "tags": { + "type": "array", + "title": "Workspace Tags", + "description": "Terraform workspace tags" + } + } + }, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {}, + "relations": { + "currentStateVersion": { + "title": "Current State Version", + "target": "terraformCloudStateVersion", + "required": false, + "many": false + }, + "project": { + "title": "Terraform Cloud Project", + "target": "terraformCloudProject", + "required": false, + "many": false + } + } + } +``` +
+
+
+## Run
+
+Integration configuration
+ +```yaml showLineNumbers +- kind: workspace + selector: + query: "true" + port: + entity: + mappings: + identifier: .id + title: .attributes.name + blueprint: '"terraformCloudWorkspace"' + properties: + organization: .relationships.organization.data.id + createdAt: .attributes."created-at" + updatedAt: .attributes."updated-at" + terraformVersion: .attributes."terraform-version" + locked: .attributes.locked + executionMode: .attributes."execution-mode" + resourceCount: .attributes."resource-count" + latestChangeAt: .attributes."latest-change-at" + tags: .__tags + relations: + currentStateVersion: .relationships."current-state-version".data.id + project: .relationships.project.data.id +``` + +
+
+
+Run blueprint
+ +```json showLineNumbers +{ + "identifier": "terraformCloudRun", + "description": "This blueprint represents a run in Terraform cloud", + "title": "Terraform Cloud Run", + "icon": "Terraform", + "schema": { + "properties": { + "createdAt": { + "type": "string", + "format": "date-time", + "title": "Creation Time", + "description": "The creation timestamp of the run" + }, + "status": { + "type": "string", + "title": "Run Status", + "description": "The current status of the run" + }, + "hasChanges": { + "type": "boolean", + "title": "Has Changes", + "description": "Indicates whether the run has changes" + }, + "isDestroy": { + "type": "boolean", + "title": "Is Destroy", + "description": "Indicates whether the run is a destroy operation" + }, + "message": { + "type": "string", + "title": "Run Message", + "description": "Message associated with the run" + }, + "terraformVersion": { + "type": "string", + "title": "Terraform Cloud Version", + "description": "Version of Terraform cloud used in the run" + }, + "appliedAt": { + "type": "string", + "format": "date-time", + "title": "Applied Time", + "description": "Timestamp when the run was applied" + }, + "plannedAt": { + "type": "string", + "format": "date-time", + "title": "Planned Time", + "description": "Timestamp when the run was planned" + }, + "source": { + "type": "string", + "title": "Run Source", + "description": "The source of the run initiation" + } + } + }, + "relations": { + "terraformCloudWorkspace": { + "title": "Terraform Cloud Workspace", + "target": "terraformCloudWorkspace", + "required": false, + "many": false + } + } +} +``` + +
+
+
+## State Version
+
+Integration configuration
+ +```yaml showLineNumbers +- kind: run + selector: + query: "true" + port: + entity: + mappings: + identifier: .id + title: .attributes.message + blueprint: '"terraformCloudRun"' + properties: + createdAt: .attributes."created-at" + status: .attributes.status + hasChanges: .attributes."has-changes" + isDestroy: .attributes."is-destroy" + message: .attributes.message + terraformVersion: .attributes."terraform-version" + appliedAt: .attributes."status-timestamps"."applied-at" + plannedAt: .attributes."status-timestamps"."planned-at" + source: .attributes.source + relations: + terraformCloudWorkspace: .relationships.workspace.data.id +``` + +
+
+
+State Version blueprint
+ +```json showLineNumbers +{ + "identifier": "terraformCloudStateVersion", + "description": "This blueprint represents a version of a Terraform state version", + "title": "Terraform Cloud State Versions", + "icon": "Terraform", + "schema": { + "properties": { + "createdAt": { + "type": "string", + "format": "date-time", + "title": "Creation Time", + "description": "Timestamp when the state version was created" + }, + "serial": { + "type": "number", + "title": "Serial Number", + "description": "A unique identifier for this version within the workspace" + }, + "status": { + "type": "string", + "title": "Status", + "description": "The current status of the state version (e.g., 'queued', 'finished')" + }, + "size": { + "type": "number", + "title": "Size", + "description": "The size of the resources" + }, + "isResourcesProcessed": { + "type": "boolean", + "title": "Is Resources Processed", + "description": "Whethere the resources has been processed" + }, + "hostedStateDownloadUrl": { + "type": "string", + "title": "Download Url", + "format": "url", + "description": "Hosted state version download url " + }, + "hostedJsonDownloadUrl": { + "type": "string", + "title": "Download Url", + "format": "url", + "description": "Url for downloading state version in json format" + }, + "outputData": { + "type": "array", + "title": "Output", + "description": "output returned from state version" + }, + "vcsCommitUrl": { + "type": "string", + "title": "VCS Commit URL", + "format": "url", + "description": "URL of the VCS commit that triggered this state version" + } + } + }, + "relations": {}, + "mirrorProperties": {}, + "calculationProperties": {}, + "aggregationProperties": {} +} +``` + +
+
\ No newline at end of file
diff --git a/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/terraform-cloud.md b/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/terraform-cloud.md
index 27d3158e7..f18cd9a59 100644
--- a/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/terraform-cloud.md
+++ b/docs/build-your-software-catalog/sync-data-to-catalog/terraform-cloud/terraform-cloud.md
@@ -1,6 +1,6 @@
---
sidebar_position: 1
-title: Terraform Cloud
+title: Terraform
description: Terraform integration in Port
---
@@ -9,41 +9,42 @@ import TabItem from "@theme/TabItem"
import DockerParameters from "./\_terraform_one_time_docker_parameters.mdx"
import PortApiRegionTip from "/docs/generalTemplates/_port_region_parameter_explanation_template.md"
import OceanSaasInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_saas_installation.mdx"
+import OceanRealtimeInstallation from "/docs/build-your-software-catalog/sync-data-to-catalog/templates/_ocean_realtime_installation.mdx"
+import Prerequisites from "../templates/\_ocean_helm_prerequisites_block.mdx"
-# Terraform Cloud and Terraform Enterprise
-
-The Terraform Cloud Integration for Port enables seamless import and synchronization of `organizations`, `projects`, `workspaces`, `runs`, and `state versions` from your Terraform infrastructure management into Port. This integration allows you to effectively monitor and manage your Terraform Cloud workspaces and runs within the Port platform.
-An `Organization` is a shared space for one or more teams to collaborate on workspaces.
-A `Project` in Terraform Cloud is a collection of infrastructure configurations, often corresponding to a code repository. It serves as the primary organizational unit, grouping related `workspaces`, `runs`, and `state versions` to manage and structure Terraform code for efficient deployment and collaboration.
-
-A `Workspace` represents a workspace in Terraform cloud. A workspace is a logical environment where Terraform manages infrastructure, such as a set of cloud resources.
+# Terraform Cloud and Terraform Enterprise
-A `Run` represents an instance of Terraform operations (plan, apply, or destroy) executed within a workspace. Each run holds information about the operation status, duration, and other relevant metadata.
+Port's Terraform Cloud integration allows you to model Terraform Cloud resources in your software catalog and ingest data into them.
-A `State Version` represents a versioned state file in Terraform. Each state version is immutable and represents the state of your managed infrastructure at a particular point in time. State versions are used to track the changes in your infrastructure and help with auditing, rollbacks, and historical analysis.
+## Overview
-## Common use cases
+This integration allows you to:
-- Synchronization of Infrastructure Management: Automatically synchronize workspace, run and state version data from Terraform Cloud into Port for centralized tracking and management.
-- Monitoring Run Statuses: Keep track of run outcomes (success, failure, etc.) and durations, providing insights into the health and performance of your infrastructure management processes.
-- Identify drifts between your Terraform configuration and what's effectively deployed in your Cloud.
+- Map and organize your desired Terraform Cloud resources and their metadata in Port (see supported resources below).
+- Watch for Terraform Cloud object changes (create/update/delete) in real-time, and automatically apply the changes to your entities in Port.
+- Automatically synchronize workspace, run and state version data from Terraform Cloud into Port for centralized tracking and management.
-## Terraform Enterprise (Self Hosted)
+:::info Terraform enterprise (self hosted)
Port supports both Terraform Cloud and Terraform Enterprise versions (self hosted). The following data model and use cases are common for both integrations.
If installing Port exporter for Terraform Enterprise, you will be required to specify your Terraform 's host URL by passing the following parameter to the installer: `integration.config.appHost`
+:::
+### Supported Resources
-## Prerequisites
+The resources that can be ingested from Terraform Cloud into Port are listed below. It is possible to reference any field that appears in the API responses linked below in the mapping configuration.
-To install the integration, you need a Kubernetes cluster that the integration's container chart will be deployed to.
+- [`Organization`](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/organizations)
+- [`Project`](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects)
+- [`Workspace`](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces)
+- [`Run`](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run)
+- [`State Version`](https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions)
-Please make sure that you have [`kubectl`](https://kubernetes.io/docs/tasks/tools/#kubectl) and [`helm`](https://helm.sh/) installed on your machine, and that your `kubectl` CLI is connected to the Kubernetes cluster where you plan to install the integration.
-## Installation
+## Setup
Choose one of the following installation methods:
@@ -55,53 +56,28 @@ Choose one of the following installation methods:
Integration configuration
+ +```yaml showLineNumbers +- kind: state-version + selector: + query: "true" + port: + entity: + mappings: + identifier: .id + title: .id + blueprint: '"terraformCloudStateVersion"' + properties: + createdAt: .attributes."created-at" + serial: .attributes.serial + status: .attributes.status + size: .attributes.size + isResourcesProcessed: .attributes."resources-processed" + hostedStateDownloadUrl: .attributes."hosted-state-download-url" + hostedJsonDownloadUrl: .attributes."hosted-json-state-download-url" + vcsCommitUrl: .attributes."vcs-commit-url" + outputData: .__output +``` + +Prerequisites
+ ++
Event listener
The integration uses polling to pull the configuration from Port every minute and check it for changes. If there is a change, a resync will occur.
-
-
-Organization blueprint
- -```json showLineNumbers - { - "identifier": "terraformCloudOrganization", - "description": "This blueprint represents an organization in Terraform Cloud", - "title": "Terraform Cloud Organization", - "icon": "Terraform", - "schema": { - "properties": { - "externalId": { - "type": "string", - "title": "External ID", - "description": "The external ID of the organization" - }, - "ownerEmail": { - "type": "string", - "title": "Owner Email", - "description": "The email associated with the organization" - }, - "collaboratorAuthPolicy": { - "type": "string", - "title": "Collaborator Authentication Policy", - "description": "Policy for collaborator authentication" - }, - "planExpired": { - "type": "string", - "title": "Plan Expired", - "description": "Indicates if plan is expired" - }, - "planExpiresAt": { - "type": "string", - "format": "date-time", - "title": "Plan Expiry Date", - "description": "The data and time which the plan expires" - }, - "permissions": { - "type": "object", - "title": "Permissions", - "description": "Permissions associated with the organization" - }, - "samlEnabled": { - "type": "boolean", - "title": "SAML Enabled", - "description": "Indicates if SAML is enabled for the organization" - }, - "defaultExecutionMode": { - "type": "string", - "title": "Default Execution Mode", - "description": "The default execution mode for the organization" - } - } - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": {} - } -``` -
-
-
-### Project
-Integration configuration
- -```yaml showLineNumbers -- kind: organization - selector: - query: "true" - port: - entity: - mappings: - identifier: .id - title: .attributes.name - blueprint: '"terraformCloudOrganization"' - properties: - externalId: .attributes."external-id" - ownerEmail: .attributes.email - collaboratorAuthPolicy: .attributes."collaborator-auth-policy" - planExpired: .attributes."plan-expired" - planExpiresAt: .attributes."plan-expires-at" - permissions: .attributes.permissions - samlEnabled: .attributes."saml-enabled" - defaultExecutionMode: .attributes."default-execution-mode" -``` -
-
-
-Project blueprint
- -```json showLineNumbers - { - "identifier": "terraformCloudProject", - "description": "This blueprint represents a project in Terraform Cloud", - "title": "Terraform Cloud Project", - "icon": "Terraform", - "schema": { - "properties": { - "name": { - "type": "string", - "title": "Project Name", - "description": "The name of the Terraform Cloud project" - }, - "permissions": { - "type": "object", - "title": "Permissions", - "description": "The permisssions on the project" - } - } - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "organization": { - "title": "Terraform Cloud Organization", - "target": "terraformCloudOrganization", - "required": true, - "many": false - } - } - } -``` -
-
-
-### Workspace
-
-Integration configuration
- -```yaml showLineNumbers -- kind: project - selector: - query: "true" - port: - entity: - mappings: - identifier: .id - title: .attributes.name - blueprint: '"terraformCloudProject"' - properties: - name: .attributes.name - permissions: .attributes.permissions - relations: - organization: .relationships.organization.data.id -``` -
-
-
-
-Workspace blueprint
- -```json showLineNumbers - { - "identifier": "terraformCloudWorkspace", - "description": "This blueprint represents a workspace in Terraform Cloud", - "title": "Terraform Cloud Workspace", - "icon": "Terraform", - "schema": { - "properties": { - "organization": { - "type": "string", - "title": "Organization", - "description": "The organization within which the workspace belongs to" - }, - "createdAt": { - "type": "string", - "format": "date-time", - "title": "Creation Time", - "description": "The creation timestamp of the workspace" - }, - "updatedAt": { - "type": "string", - "format": "date-time", - "title": "Last Updated", - "description": "The last update timestamp of the workspace" - }, - "terraformVersion": { - "type": "string", - "title": "Terraform Cloud Version", - "description": "Version of Terraform cloud used by the workspace" - }, - "locked": { - "type": "boolean", - "title": "Locked Status", - "description": "Indicates whether the workspace is locked" - }, - "executionMode": { - "type": "string", - "title": "Execution Mode", - "description": "The execution mode of the workspace" - }, - "resourceCount": { - "type": "number", - "title": "Resource Count", - "description": "Number of resources managed by the workspace" - }, - "latestChangeAt": { - "type": "string", - "format": "date-time", - "title": "Latest Change", - "description": "Timestamp of the latest change in the workspace" - }, - "tags": { - "type": "array", - "title": "Workspace Tags", - "description": "Terraform workspace tags" - } - } - }, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {}, - "relations": { - "currentStateVersion": { - "title": "Current State Version", - "target": "terraformCloudStateVersion", - "required": false, - "many": false - }, - "project": { - "title": "Terraform Cloud Project", - "target": "terraformCloudProject", - "required": false, - "many": false - } - } - } -``` -
-
-
-### Run
-
-Integration configuration
- -```yaml showLineNumbers -- kind: workspace - selector: - query: "true" - port: - entity: - mappings: - identifier: .id - title: .attributes.name - blueprint: '"terraformCloudWorkspace"' - properties: - organization: .relationships.organization.data.id - createdAt: .attributes."created-at" - updatedAt: .attributes."updated-at" - terraformVersion: .attributes."terraform-version" - locked: .attributes.locked - executionMode: .attributes."execution-mode" - resourceCount: .attributes."resource-count" - latestChangeAt: .attributes."latest-change-at" - tags: .__tags - relations: - currentStateVersion: .relationships."current-state-version".data.id - project: .relationships.project.data.id -``` - -
-
-
-Run blueprint
- -```json showLineNumbers -{ - "identifier": "terraformCloudRun", - "description": "This blueprint represents a run in Terraform cloud", - "title": "Terraform Cloud Run", - "icon": "Terraform", - "schema": { - "properties": { - "createdAt": { - "type": "string", - "format": "date-time", - "title": "Creation Time", - "description": "The creation timestamp of the run" - }, - "status": { - "type": "string", - "title": "Run Status", - "description": "The current status of the run" - }, - "hasChanges": { - "type": "boolean", - "title": "Has Changes", - "description": "Indicates whether the run has changes" - }, - "isDestroy": { - "type": "boolean", - "title": "Is Destroy", - "description": "Indicates whether the run is a destroy operation" - }, - "message": { - "type": "string", - "title": "Run Message", - "description": "Message associated with the run" - }, - "terraformVersion": { - "type": "string", - "title": "Terraform Cloud Version", - "description": "Version of Terraform cloud used in the run" - }, - "appliedAt": { - "type": "string", - "format": "date-time", - "title": "Applied Time", - "description": "Timestamp when the run was applied" - }, - "plannedAt": { - "type": "string", - "format": "date-time", - "title": "Planned Time", - "description": "Timestamp when the run was planned" - }, - "source": { - "type": "string", - "title": "Run Source", - "description": "The source of the run initiation" - } - } - }, - "relations": { - "terraformCloudWorkspace": { - "title": "Terraform Cloud Workspace", - "target": "terraformCloudWorkspace", - "required": false, - "many": false - } - } -} -``` - -
-
-
-### State Version
-
-Integration configuration
- -```yaml showLineNumbers -- kind: run - selector: - query: "true" - port: - entity: - mappings: - identifier: .id - title: .attributes.message - blueprint: '"terraformCloudRun"' - properties: - createdAt: .attributes."created-at" - status: .attributes.status - hasChanges: .attributes."has-changes" - isDestroy: .attributes."is-destroy" - message: .attributes.message - terraformVersion: .attributes."terraform-version" - appliedAt: .attributes."status-timestamps"."applied-at" - plannedAt: .attributes."status-timestamps"."planned-at" - source: .attributes.source - relations: - terraformCloudWorkspace: .relationships.workspace.data.id -``` - -
-
-
-State Version blueprint
- -```json showLineNumbers -{ - "identifier": "terraformCloudStateVersion", - "description": "This blueprint represents a version of a Terraform state version", - "title": "Terraform Cloud State Versions", - "icon": "Terraform", - "schema": { - "properties": { - "createdAt": { - "type": "string", - "format": "date-time", - "title": "Creation Time", - "description": "Timestamp when the state version was created" - }, - "serial": { - "type": "number", - "title": "Serial Number", - "description": "A unique identifier for this version within the workspace" - }, - "status": { - "type": "string", - "title": "Status", - "description": "The current status of the state version (e.g., 'queued', 'finished')" - }, - "size": { - "type": "number", - "title": "Size", - "description": "The size of the resources" - }, - "isResourcesProcessed": { - "type": "boolean", - "title": "Is Resources Processed", - "description": "Whethere the resources has been processed" - }, - "hostedStateDownloadUrl": { - "type": "string", - "title": "Download Url", - "format": "url", - "description": "Hosted state version download url " - }, - "hostedJsonDownloadUrl": { - "type": "string", - "title": "Download Url", - "format": "url", - "description": "Url for downloading state version in json format" - }, - "outputData": { - "type": "array", - "title": "Output", - "description": "output returned from state version" - }, - "vcsCommitUrl": { - "type": "string", - "title": "VCS Commit URL", - "format": "url", - "description": "URL of the VCS commit that triggered this state version" - } - } - }, - "relations": {}, - "mirrorProperties": {}, - "calculationProperties": {}, - "aggregationProperties": {} -} -``` - -
-
## Let's Test It
@@ -2053,3 +1476,8 @@ The combination of the sample payload and the Ocean configuration generates the
```
+
+
+## Relevant Guides
+
+For relevant guides and examples, see the [guides section](https://docs.getport.io/guides?tags=Terraform).
\ No newline at end of file
diff --git a/docs/generalTemplates/_integration_template.md b/docs/generalTemplates/_integration_template.md
index 9bb9ce8c9..309dae866 100644
--- a/docs/generalTemplates/_integration_template.md
+++ b/docs/generalTemplates/_integration_template.md
@@ -50,6 +50,8 @@ Choose one of the following installation methods: