Version: 3.0
Date: December 2, 2025
Audience: TeamForm Customers using Jira Cloud

Overview

This guide helps you link Jira issues to TeamForm teams based on a "Team" dropdown field in your Jira issues. The linkage happens through Jira's issue properties, which TeamForm reads during its scheduled imports.

How It Works

1. Store Team Linkage: A TeamForm Team ID is stored in each Jira issue's properties

2. TeamForm Syncs: During the next scheduled import, TeamForm reads these properties

3. Teams Are Linked: Issues appear associated with the correct teams in TeamForm

Two Approaches

This guide covers two ways to link issues to teams:

Part A: Bulk Linking Existing Issues (Immediate, Required)

• Link all your current issues that already have team assignments

• Uses a manual trigger automation rule

• Start here to link your existing backlog

Part B: Ongoing Automation (Optional, For Future Issues)

• Automatically link new issues as they're created or team assignments change

• Requires creating a Jira automation rule

• Recommended after completing Part A

Prerequisites

Before you begin, ensure you have:

• [ ] Jira Cloud account with admin permissions

• [ ] A "Team" custom field (dropdown/select list) configured in your Jira project

• [ ] TeamForm integration already configured and importing Jira data

• [ ] The Team Name → TeamForm ID mapping table (provided in Section 1 below)

• [ ] A Jira API token (you'll create this in Part A)

Note: Jira Automation (used in Part B) requires Jira Cloud Premium or Standard. Part A can be completed on any Jira Cloud plan.

Quick Reference: Working Configuration

Once you've completed the setup, your web request will look like this:

URL:

Method: PUT

Headers:

Body:

Success Response: 200 OK or 201 Created

Section 1: Team Mapping Reference

All approaches in this guide use the following mapping to convert team names to TeamForm IDs. These values have been pre-configured for your organization.

Your Team Mappings

Important: These mappings are case-sensitive. Ensure the team names in your Jira dropdown field match exactly as exist in your Jira instance and TeamForm respectively.

PART A: Bulk Linking Existing Issues

Goal: Link all your current Jira issues that already have team assignments to their corresponding TeamForm teams.

Time Required: 15-30 minutes (depending on project size)

Step 1: Create the Manual Trigger Automation

This creates a simple automation rule that you'll run once to link existing issues, then can keep for future bulk operations.

1. Navigate to your Jira project

2. Click Project Settings (gear icon in left sidebar)

3. Under "Project," select Automation

4. Click Create rule (blue button in top-right)

Configure Manual Trigger

1. Select trigger type: "Manual"

2. Click Save

Add JQL Filter (Optional but Recommended)

1. Click Add component → If/Else condition

2. Select JQL condition

3. JQL Query:

   "Team" IS NOT EMPTY

   This ensures the rule only runs on issues that have a team assigned

4. Click Save

Note: This initial filter is optional but recommended to avoid unnecessary executions on issues without team assignments.

Add Branching Logic for Each Team

Now add the conditional logic that maps team names to TeamForm IDs.

For Each Team in Your Mapping:

1. Click Add component → New branch

2. Type: Conditional branch

3. Add condition: "Issue fields condition"

   • Field: Team (your custom field)

   • Condition: equals

   • Value: Backend Engineering (first team name from your mapping)

4. Click Then: Add component → Send web request

   Configure the web request as follows:

   Webhook URL:

   https://YOUR-INSTANCE.atlassian.net/rest/api/3/issue/{{issue.key}}/properties/teamform-team-id

   Replace YOUR-INSTANCE with your actual Jira instance name (e.g., teamform)

   HTTP method: PUT ⚠️ CRITICAL: Must be PUT, not POST

   Headers:

   Content-Type: application/json Authorization: Basic YOUR_BASE64_CREDENTIALS

   Request body:

   "WXYZ1234"

   (Use the TeamForm ID from your mapping)

   Delay execution: 200 milliseconds

⚠️ Critical Notes:

• You must hardcode your Jira instance URL - smart values like {{baseUrl}} do not work reliably in web requests

• HTTP method must be PUT (not POST) or you'll get "405 Method Not Allowed"

• You must include authentication (see Step 1.5 below for setup)

5. Click Save

6. Repeat for each team in your mapping table (Section 1)

Step 1.5: Set Up Authentication (REQUIRED)

To allow the automation to set issue properties, you need to configure authentication.

Create a Jira API Token

1. Go to: https://id.atlassian.com/manage-profile/security/api-tokens

2. Click Create API token

3. Name it: "TeamForm Automation"

4. Click Create

5. Copy the token and save it securely

Encode Your Credentials

You need to Base64 encode your email and API token in the format: email:api_token

Run this command in your terminal (replace with your actual email and token):

This will output a Base64-encoded string like:

Add Authorization Header

Go back to each "Send web request" component in your automation and update the Headers:

Replace YOUR_BASE64_STRING with the output from the base64 command above.

Security Best Practice: After testing, store your token in Secret Keys:

1. Go to Project Settings → Automation → Manage secret keys

2. Create a secret with your Base64-encoded credentials

3. Update the Authorization header to: Basic {{secrets.yourSecretName}}

Add an "Else" Branch for Unknown Teams

1. Click Else at the bottom of the branching

2. Add component → Log action

   • Message: Unknown team: {{issue.customfield_10050}}

Name and Save the Rule

1. Rule name: TeamForm - Bulk Link Issues (Manual)

2. Description: Manual rule to bulk link Jira issues to TeamForm teams

3. Click Save

4. Leave it OFF (don't toggle "Turn it on" - manual rules don't need to be "on")

Step 2: Run the Manual Rule

1. Go to Project Settings → Automation

2. Find your rule: "TeamForm - Bulk Link Issues (Manual)"

3. Click Run rule (play button icon on the right)

4. Confirm the execution in the dialog

5. Wait for the rule to complete (you'll see progress in the UI)

Monitor Execution

1. Click on your rule name

2. Click Audit log tab

3. You should see:

   • Multiple successful executions (one per issue)

   • Green checkmarks for successful web requests

   • Web request response showing "200" or "201" (success)

Expected Result:

• Each issue with a team assignment gets a teamform-team-id property set

• Number of successful executions = number of issues with team assignments

• Each execution shows "Response 200" or "Response 201" in the audit log

Success Indicators:

• 200 OK = Property was updated (already existed)

• 201 Created = Property was created (first time)

• Both are successful - the property is now set!

Step 3: Verify Bulk Linking Worked

Check Automation Executions

1. Go to Project Settings → Automation

2. Click on your automation rule

3. Click Audit log

4. Verify:

   • Number of executions matches number of issues processed

   • All show green checkmarks (success)

   • Check any red errors and retry those issues

Spot-Check Individual Issues

Verify Issue Property Was Set

The issue property is set immediately, but you can verify it via API:

1. Get your Base64-encoded credentials from Step 1.5

2. Run this command (replace with your issue key and credentials):

Expected response (200 OK):

This confirms the property was successfully set in Jira.

TeamForm UI Will Update After Sync

Important: The TeamForm for Jira panel in the issue view will show "No team linked" until TeamForm's next scheduled import. This is normal behavior:

1. Automation runs → Issue property is set in Jira ✅

2. TeamForm syncs (every 30-60 minutes) → Reads property and links team

3. UI updates → "TeamForm Team" panel shows the linked team

Don't be concerned if you see "No team linked" immediately after the automation runs - this will update after the next TeamForm import.

Wait for TeamForm Sync

1. TeamForm imports run on a schedule (typically every 30-60 minutes)

2. Wait for the next scheduled import

3. Check with your TeamForm administrator for the exact sync schedule

Verify in TeamForm

1. Log into TeamForm

2. Navigate to one of your teams (e.g., "Backend Engineering")

3. Go to the team's Objectives or Work Items view

4. Verify Jira issues appear linked to the correct team

5. Spot-check 3-5 teams to ensure linkages are working

Step 4: Handle Large Projects (1000+ Issues)

If you have many issues, process them in batches to avoid timeouts and rate limits.

Batch by Team

Process one team at a time:

Run the manual automation or bulk edit for each team separately.

Batch by Date Range

Process issues by creation date:

Process month by month until all issues are linked.

Batch by Count

Process 100-500 issues at a time:

1. Use JQL: project = YOUR_PROJECT AND "Team" IS NOT EMPTY ORDER BY created ASC

2. In bulk edit, select first 100 issues

3. Process them

4. Repeat with next 100 issues

Troubleshooting Bulk Linking

Issue: "500 ProtocolException: Target host is not specified"

Symptom: Error shows Target host is not specified and request URL is missing the domain (e.g., /rest/api/3/...)

Cause: The webhook URL is using a relative path or smart value instead of a full URL.

Solution:

1. Edit your automation rule

2. Find the "Send web request" component

3. Change the URL to: https://YOUR-INSTANCE.atlassian.net/rest/api/3/issue/{{issue.key}}/properties/teamform-team-id

4. Replace YOUR-INSTANCE with your actual Jira instance name

5. Save and re-run

Important: Smart values like {{baseUrl}} and {{issue.baseUrl}} have known bugs in Jira Automation web requests. You must hardcode the full URL.

Issue: "405 Method Not Allowed" error

Symptom: Error with response headers showing Allow: GET,PUT,DELETE

Cause: Web request is using POST method instead of PUT.

Solution:

1. Edit your automation rule

2. Find the "Send web request" component

3. Change HTTP method to PUT

4. Save and re-run

Critical: Jira's issue properties API only accepts GET, PUT, or DELETE. POST is not supported.

Issue: "403 Forbidden" or "Failed to parse Connect Session Auth Token"

Symptom: 403 error with message about authentication or session token

Cause: Missing or incorrect authentication headers.

Solution:

1. Create a Jira API token (see Part A Step 1.5)

2. Base64 encode your credentials: echo -n "email:token" | base64

3. Add Authorization header to web request:

   Authorization: Basic YOUR_BASE64_STRING

4. Ensure both Content-Type and Authorization headers are present

5. Save and re-run

Issue: "404 Not Found" or "Issue does not exist"

Possible Causes:

Cause 1: URL path is incorrect

Solution: Verify URL is exactly:

Cause 2: Authentication issue (even though it says 404)

Solution: Add or fix the Authorization header (see "403 Forbidden" solution above)

Cause 3: Issue actually doesn't exist or you don't have permission

Solution: Verify the issue exists and your account has permission to view/edit it

Issue: No executions appear in audit log

Possible Causes:

• Manual rule wasn't run

• Rule is disabled

Solution:

• Click "Run rule" button on the manual trigger rule

• Verify rule shows as active/enabled

Issue: "Too many automation executions" error

Cause: Jira plan has automation execution limits (e.g., 100/month on Free, 500/month on Standard).

Solution:

• Check your current usage: Project Settings → Automation → Usage

• Process issues in smaller batches spread over time

• Upgrade Jira plan for higher limits

• Contact Atlassian support for temporary limit increase

Issue: Some issues didn't get linked

Cause:

• Automation failed for specific issues

• Rate limiting

• Permission issues

Solution:

1. Check audit log for failed executions

2. Note which issues failed (issue key shown in logs)

3. Re-run for failed issues only:

   issue in (PROJ-123, PROJ-456, PROJ-789)

4. Or manually open each issue, change team to different value, change back

Issue: Team names don't match exactly

Cause: Team name in Jira doesn't match the mapping (case-sensitive, spaces matter).

Solution:

1. Check your Jira Team field options: Jira Settings → Issues → Custom fields → Team → Edit

2. Compare exact names with mapping in Section 1

3. Update either:

   • Jira field options to match mapping, OR

   • Automation rule conditions to match actual Jira values

Recommended Bulk Linking Strategy

For best results, follow this sequence:

1. ✅ Review team mappings (Section 1) - Verify all teams are listed

2. ✅ Set up the manual rule (Step 1)

3. ✅ Test with small batch (10 issues from one team)

4. ✅ Run the rule and verify (Steps 2-3)

5. ✅ Confirm in TeamForm after next sync

6. ✅ Process all remaining issues (in batches if needed)

7. ✅ Final spot-check across all teams

This staged approach catches issues early before processing thousands of issues.

PART B: Ongoing Automation (Optional)

Goal: Automatically link new Jira issues to TeamForm teams as they're created or when team assignments change.

Time Required: 20-30 minutes

Prerequisites:

• Jira Cloud Premium or Standard (for Jira Automation)

• Part A completed and verified

Note: Part B is optional but recommended. It ensures future issues are automatically linked without manual intervention.

Step 1: Create the Automation Rule

1. Navigate to your Jira project

2. Click Project Settings → Automation

3. Click Create rule

Step 2: Configure Field Value Changed Trigger

1. Select trigger type: "Field value changed"

2. Configure:

   • Fields to monitor: Select your "Team" custom field

   • Issues to monitor: All issues in this project

3. Click Save

![Screenshot placeholder - Field value changed trigger]

Step 3: Add Branching Logic

Add the same team mapping logic from Part A.

For Each Team:

1. Click Add component → Branch rule/Related issues

2. Select Advanced branching