Building a Page Tree

AutoPage - Sample Configuration: Building a Page Tree Reflecting the Issue Hierarchy

This sample configuration demonstrates how to replicate a parent-child hierarchy from Jira within your Confluence page tree. The goal is to achieve a Confluence page tree that is hierarchically identical to your Jira issues, such as Epic, Standard Issue Types, and Subtask Issue Types.

Our example configuration focuses on a simple two-level hierarchy: Epic and Story.

---

Instructions Overview

• Custom Field Configuration: Add a custom field to store Confluence Page IDs for parent issues.
• AutoPage Rules:
  • Parent Rule: Create a rule for the Epic hierarchy level.
  • Child Rule: Create a rule for the Story hierarchy level, placing these pages under their linked Epic issue pages.
• Jira Automation Rule: Configure an automation rule to update the parent page ID.
• API Token Generation: Generate a Personal Access Token for Jira Automation’s web requests.

---

Custom Field Configuration

1. Add a Single Line Text Custom Field named “ParentIssuePageId”.
2. Ensure this custom field is added to the context of your projects and assigned to the relevant issue types.

---

AutoPage Rules

Parent Rule: “Epic Hierarchy - Parent Issue Rule”

This rule creates pages for the Epic hierarchy level. We assume these pages will be placed under a static page in Confluence.

1. Create Trigger

Triggers initiate the execution of a rule and respond to events in Jira (e.g., Issue created).

• Issue Events: Select “Issue created” as the relevant issue event. Multiple events may be selected.
• Incoming Webhook: Optionally, enable this to trigger the rule via REST API, ideal for Jira Automation integration.

Example Screenshots of the “Create Trigger” section.

2. Create Condition

The condition acts as a filter to specify which Jira issues should trigger the rule.

• Project: Select the relevant project (e.g., “Ultimate AutoPage Staging Test Project”).
• Issue Type: Select “Epic” as the issue type.
• Status: Optionally, select a status for your issues.
• JQL Condition: You can use a JQL query to refine the condition. You can also execute your configured JQL to test it.

Example Screenshot of the “Create Condition” section with JQL condition.

3. Create Action

This step defines the template, title, labels, and position of the new Confluence page.

• Choose Your Template Page:

  • Select “Static Page” and choose your Confluence template page (e.g., “Ultimate AutoPage Template (Ultimate AutoPage Testspace)”).
  • The author must have permission to create pages in this area, and personal spaces are ignored.
  • View permissions for the template page must be granted to the “AutoPage helper app for Confluence-User” and the Rule Actor.

• Configure Page Details:

  • Page Title: Set the title dynamically using Smart Values (e.g., EPIC ${key}-Summary: ${summary}).
  • Page Labels: Add labels for the Confluence page.

• Target Page Configuration:

  • Confluence Space of the Target Page: Select the Confluence space where the new page should be created (e.g., “Ultimate AutoPage Testspace”).
  • Confluence Target Page: Select the parent page for the new page (e.g., “Epic Hierarchy Documentation Root Page (Ultimate AutoPage Testspace)”).
  • Edit permissions for the target page must be granted to the “AutoPage helper app for Confluence-User”.

Example Screenshots of the “Create Action” section.

Child Rule: “Epic Hierarchy - Child Issue Rule”

This rule creates pages for the Story hierarchy level. These pages are designed to be placed underneath the pages belonging to the linked Epic issue.

1. Create Trigger

• Issue Events: Select “Issue created” as the relevant issue event.
• Incoming Webhook: Enable this to trigger the rule via REST API, ideal for Jira Automation integration.
  • Header Key: Add the provided header key (e.g., x-autopage-api-key).
  • Webhook Endpoint URL: Use the provided URL (e.g., https://1dc73707-6849-40cb-98f8-a4860a2f0757.hello.atlassian-dev.net/x1/TSR1m8mye9U3XxOq_tBjNdeguSw?method=triggerRule). Remember to replace the {{issue.id}} placeholder if you’re not using Jira Automation.

Example Screenshots of the “Create Trigger” section for the Child Rule.

2. Create Action

This step defines the template, title, labels, and position for the new Confluence page.

• Choose Your Template Page:

  • Select “Static Page” and choose your Confluence template page (e.g., “Template Demoproject (Demo)”).
  • The author must have permission to create pages in this area, and personal spaces are ignored.
  • View permissions for the template page must be granted to the “AutoPage helper app for Confluence-User” and the Rule Actor.

• Configure Page Details:

  • Page Title: Set the title dynamically using Smart Values (e.g., Story ${key} - Summary ${summary}).
  • Page Labels: Add labels for the Confluence page.

• Target Page Configuration:

  • Custom Field with Target Information: Use the “Custom Field” mode to define the target parent page. Select the “ParentIssuePageId” custom field (e.g., customfield_10207). This custom field must have been created in advance.

Example Screenshots of the “Create Action” section for the Child Rule.

---

Jira Automation Rule

The Jira Automation Rule involves a web request to the Jira API, which requires a Personal Access Token.

API Token Generation

Step 1: Generate an API Token

1. Navigate to your User Account and open the Security Tab.
2. Click on “Create and manage API tokens” to create a new token.
3. Configure the token:
   • Label: Enter a descriptive name (e.g., “Jira Automation”).
   • Expiry date: Set a reasonable expiration date for security reasons.
   • Permissions: Select the appropriate permissions for the token to perform API actions.
4. Generate the token: Click “Generate” and copy the token. Save it securely, as you will not be able to view it again once the screen is closed.

Step 2: Use the Personal Access Token in Jira Automation

1. In your Jira Automation rule, when configuring the “Send Web Request” action, set the following HTTP header:
   • Authorization: Bearer <your-personal-access-token> (e.g., Authorization: Bearer abc123def456ghi789).
2. Set the Content-Type header:
   • Add header: Content-Type: application/json.

Step 3: Secure and Manage Your Token

• Treat the API Token as a sensitive credential. Do not share or expose it in insecure locations.
• Revoke the token if it is no longer needed or compromised by going to Profile > Personal Access Tokens and selecting Revoke.

---

Jira Automation Rule - Detail Configuration

Overview

Example Screenshot of the Jira Automation Rule Overview.

This example rule, “Autopage - Epic Hierarchy Documentation,” is enabled.

• When: “Value changes for Parent”
• If: “Compare two values” (checks if {{fieldChange.toString}} does not equal Empty)
• Then:
  • Send web request (GET to Jira API)
  • Create variable pageid
  • Edit work item fields (set ParentissuePageId to {{pageid.trim}})
  • Send web request (POST to AutoPage webhook)

Detailed Configuration Steps

Field Value Changed Trigger

• Fields to monitor for changes (required): Select “Parent”.
• Change type (required): Select “Any changes to the field value”.
• For (optional): Leave blank for all work item operations.

Example Screenshot of the “Field value changed” trigger configuration.

Conditional Logic

• First value (required): {{fieldChange.toString}}
• Condition: does not equal
• Second value: Empty

Example Screenshot of the conditional logic configuration.

Send Web Request (GET - Retrieve Remote Links)

This action sends an HTTP GET request to the Jira API to retrieve remote links of parent issues.

• Web request URL (required): https://coderay.atlassian.net/rest/api/3/issue/{issue.parent.key.urlencode}/remotelink
  • Request parameters must be URL encoded, and smart values should use {{value.urlEncode}}.
• HTTP method (required): GET
• Web request body (required): Empty
• Headers (optional):
  • Authorization: Bearer <your-personal-access-token> (Value is hidden).
  • Content-Type: application/json.

Example Screenshot of the “Send web request” action (GET) configuration.

Create Variable (pageid)

This action creates a smart value variable named pageid that can be used in other actions.

• Variable name (required): pageid
• Smart value (required):

  {{#webhookResponse.body}}
      {{#if(relationship.startsWith("mentioned"))}}
          {{object.url.match("pageId=([0-9]+)").replace("pageId=", "").trim}}
      {{/}}
  {{/}}

  This smart value extracts the pageId from the webhook response body if the relationship starts with “mentioned”.

Example Screenshot of the “Create variable” action configuration.

Edit Work Item Fields

This action sets values for fields on the work item.

• Field to set: ParentissuePageId
• Value: {{pageid.trim}}

Example Screenshot of the “Edit work item” fields action configuration.

Send Web Request (POST - Trigger AutoPage Rule)

This action sends an HTTP POST request to the AutoPage incoming webhook URL to trigger the AutoPage rule.

• Web request URL (required): https://1dc73707-b849-40cb-98f8-04860a2f0757.hello.atlassian-dev.net/x1/TSR1m8mye9U3Xx0q_tBjNdeguSw?method=triggerRule&ruleId=20137d2b-8030-4910-9036
  • Request parameters must be URL encoded, and smart values should use {{value.urlencode}}.
• HTTP method (required): POST
• Web request body (required): Issue data (Automation format)
• Headers (optional):
  • x-autopage-api-key: {{header_value}} (Value is hidden).
• You can find more information on how to set up an Incoming Webhook [here].

Example Screenshot of the “Send web request” action (POST) configuration.