Added integration and mapping guides

docs/site/docs/data-security.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 7
+sidebar_position: 8
 ---
 
 # Data handling & security

docs/site/docs/examples/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Enterprise-Ready Plugins",
-  "position": 6
+  "position": 5
 }

docs/site/docs/examples/dev-daily.md

@@ -4,6 +4,9 @@ description: A dashboard that consolidates developers' daily activities like pul
 sidebar_position: 2
 ---
 
+import JiraIntegration from "../integrations/jira.mdx";
+import GithubIntegration from "../integrations/github.mdx";
+
 # Dev Daily Plugin
 
 The Dev Daily Plugin provides developers with a consolidated dashboard of their daily development activities, including pull requests, tasks, and reviews. This plugin helps developers efficiently plan and manage their day by bringing together key information in one place.
@@ -13,9 +16,205 @@ The Dev Daily Plugin provides developers with a consolidated dashboard of their
 ## Prerequisites
 
 - Complete the [Getting Started](/getting-started) guide
-- Jira and Github accounts
+- Jira and Github accounts with the necessary permissions
+  - For Jira obtain a [API Token](https://id.atlassian.com/manage-profile/security/api-tokens)
+
+## Setup integrations
+
+In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab.
+
+![Port Settings](/img/settings-page.png)
+
+Yours will be empty, so you'll need to add your Jira and Github integrations.
+
+Click on the **Add Integration** button, and follow the instructions to add both Jira and Github integrations.
+
+<GithubIntegration />
+
+<JiraIntegration />
+
+## Setup the mappings & blueprints
+
+In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab.
+
+### Add the blueprints - Pull Request & Task
+
+Click on **Add Blueprint** and add the following two blueprints:
+
+<details>
+<summary>Pull Request Blueprint</summary>
+
+```json
+{
+  "identifier": "dev-daily-pull-request",
+  "title": "Pull Request",
+  "icon": "Github",
+  "schema": {
+    "properties": {
+      "creator": {
+        "title": "Creator",
+        "type": "string"
+      },
+      "assignees": {
+        "title": "Assignees",
+        "type": "array"
+      },
+      "reviewers": {
+        "title": "Reviewers",
+        "type": "array"
+      },
+      "status": {
+        "title": "Status",
+        "type": "string",
+        "enum": ["merged", "open", "closed"],
+        "enumColors": {
+          "merged": "purple",
+          "open": "green",
+          "closed": "red"
+        }
+      },
+      "closedAt": {
+        "title": "Closed At",
+        "type": "string",
+        "format": "date-time"
+      },
+      "updatedAt": {
+        "title": "Updated At",
+        "type": "string",
+        "format": "date-time"
+      },
+      "mergedAt": {
+        "title": "Merged At",
+        "type": "string",
+        "format": "date-time"
+      },
+      "link": {
+        "format": "url",
+        "type": "string"
+      }
+    },
+    "required": []
+  },
+  "mirrorProperties": {},
+  "calculationProperties": {},
+  "aggregationProperties": {},
+  "relations": {}
+}
+```
+
+</details>
+
+<details>
+<summary>Task Blueprint</summary>
+
+```json
+{
+  "identifier": "dev-daily-task",
+  "title": "Task",
+  "icon": "Jira",
+  "schema": {
+    "properties": {
+      "assignee": {
+        "type": "string",
+        "title": "Assignee"
+      },
+      "status": {
+        "icon": "DefaultProperty",
+        "title": "Status",
+        "type": "string",
+        "enum": ["To Do", "In Progress", "Done"],
+        "enumColors": {
+          "To Do": "turquoise",
+          "In Progress": "yellow",
+          "Done": "green"
+        }
+      },
+      "link": {
+        "type": "string",
+        "title": "Link",
+        "format": "url"
+      }
+    },
+    "required": ["assignee", "status", "link"]
+  },
+  "mirrorProperties": {},
+  "calculationProperties": {},
+  "aggregationProperties": {},
+  "relations": {}
+}
+```
+
+</details>
+
+### Add the mappings
+
+Click on the `MAPPING` button near the **GitHub** integration. and paste the following YAML:
+
+<details>
+<summary>Pull Request Mapping</summary>
+
+```yaml
+resources:
+  - kind: pull-request
+    selector:
+      query: "true"
+    port:
+      entity:
+        mappings:
+          identifier: .head.repo.name + (.id|tostring)
+          title: .title
+          blueprint: '"dev-daily-pull-request"'
+          properties:
+            creator: .user.login
+            assignees: "[.assignees[].login]"
+            reviewers: "[.requested_reviewers[].login]"
+            status: .status
+            closedAt: .closed_at
+            updatedAt: .updated_at
+            mergedAt: .merged_at
+            prNumber: .id
+            link: .html_url
+```
+
+</details>
+
+Now click on the `MAPPING` button near the **Jira** integration. and paste the following YAML:
+
+<details>
+<summary>Task Mapping</summary>
+
+```yaml
+deleteDependentEntities: true
+createMissingRelatedEntities: true
+enableMergeEntity: true
+resources:
+  - kind: issue
+    selector:
+      query: "true"
+      jql: (created >= -1w) OR (updated >= -1w)
+    port:
+      entity:
+        mappings:
+          identifier: .key
+          title: .fields.summary
+          blueprint: '"dev-daily-task"'
+          properties:
+            link: (.self | split("/") | .[:3] | join("/")) + "/browse/" + .key
+            status: .fields.status.statusCategory.name
+            creator: .fields.creator.emailAddress
+            created: .fields.created
+            updated: .fields.updated
+            resolutionDate: .fields.resolutiondate
+            assignee: .fields.assignee.emailAddress
+```
+
+</details>
+
+:::note
+If you already have a mapping configured you should append the new mapping to the existing one.
+:::
 
-## Install
+## Install the plugin
 
 ```bash
 yarn --cwd packages/app add @port-labs/backstage-plugin-dev-daily

docs/site/docs/features/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Features",
-  "position": 5
+  "position": 6
 }

docs/site/docs/getting-started.md

@@ -12,7 +12,7 @@ Let's discover **Port's Backstage plugin in less than 5 minutes**.
 
 - A Backstage instance
 - A Port account
-  - Visit [Port's website](https://www.getport.io) to create your **free** account.
+  - Visit [Port's website](https://app.getport.io) to create your **free** account.
   - Follow the onboarding process to set up your organization.
 
 ### Install Plugins
@@ -75,6 +75,10 @@ import { SettingsPage } from "@port-labs/backstage-plugin-framework";
 </Route>;
 ```
 
+To view the settings page, click the **Settings** button on the bottom left and click on the **Port** tab.
+
+![Port Settings](/img/settings-page.png)
+
 ## Example out-of-the-box plugin - Dev Daily
 
 Follow the [Dev Daily Plugin documentation](./examples/dev-daily.md) to learn how to use the Dev Daily Plugin.

docs/site/docs/integrations/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Integrations",
+  "position": 7
+}

docs/site/docs/integrations/github.mdx

@@ -0,0 +1,12 @@
+---
+title: GitHub Integration
+---
+
+### Install GitHub Integration
+
+1. In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab.
+2. Click on the **Add Integration** button, in the settings page.
+3. In the **Git Providers** section, click on the **GitHub** button.
+4. Follow the instructions to install the GitHub app on your GitHub account.
+
+Read more about Port's GitHub integration [here](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/git/github/#setup).

docs/site/docs/integrations/jira.mdx

@@ -0,0 +1,20 @@
+---
+title: Jira Integration
+---
+
+### Install Jira Integration
+
+1. First, obtain a [API Token](https://id.atlassian.com/manage-profile/security/api-tokens) for the atlassian account you want to use to authenticate with Jira.
+2. In your Backstage instance, click the **Settings** button on the bottom left and click on the **Port** tab.
+3. Click on the **Add Integration** button, in the settings page.
+4. Scroll down to **Project Management** and select **Jira**.
+5. Fill out the form:
+   - **Name**: Give your integration a name.
+   - **Installation Method**: Select **Hosted by Port**. For more advanced setups, read [here](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/project-management/jira/?installation-methods=real-time-self-hosted#setup)
+   - **Jira Host**: Usually it's `https://<your-jira-instance>.atlassian.net`.
+   - **Atlassian User Email**: The email of the user you want to use to authenticate with Jira.
+   - **Atlassian API Token**: The API Token you obtained for the user.
+6. Click on the **Save** button.
+
+![Jira Integration](/img/jira-integration.png)
+Read more about Port's Jira integration [here](https://docs.getport.io/build-your-software-catalog/sync-data-to-catalog/project-management/jira/#setup).