Design Spec: atlassian-org-license-utilization
Parent: #117
Target: runwhen-contrib/rw-cli-codecollection
Spec
codebundle_name: "atlassian-org-license-utilization"
target_collection: "runwhen-contrib/rw-cli-codecollection"
display_name: "Atlassian Organization License Utilization Report"
author: "rw-codebundle-agent"
purpose: |
Monitors Atlassian Cloud organization license utilization across Jira, Confluence,
Jira Service Management, Loom, and other entitled products. Computes active-user
versus billable-user ratios, tracks proximity to purchased user-tier limits, and
raises issues when utilization falls below operator thresholds — the primary signal
for SaaS license waste and tier-upgrade risk.
tasks:
- name: "Generate Atlassian License Utilization Report for Organization `${ATLASSIAN_ORG_NAME}`"
description: |
Queries the Atlassian Organizations REST API (managed accounts, user stats, and
per-user product_access) to build a per-product breakdown of billable users,
recently active users, and utilization percentage. Includes organization-wide
summary tables suitable for finance and IT admin review.
script_name: "generate-atlassian-license-utilization-report.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
- name: "Analyze Billable User Counts Versus Tier Limits for Organization `${ATLASSIAN_ORG_NAME}`"
description: |
Correlates billable user counts with contract or entitlement tier quantities
(via Admin contracts/entitlements APIs where available). Flags products at or
above the configured tier-proximity threshold (default 80%) and products with
billable counts exceeding purchased tier (overage risk).
script_name: "analyze-atlassian-tier-proximity.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
- name: "Evaluate License Utilization Thresholds for Organization `${ATLASSIAN_ORG_NAME}`"
description: |
Compares per-product active/billable utilization ratios against
LICENSE_UTILIZATION_MIN_PERCENT. Emits structured issues with expected vs
actual utilization, affected product keys, and remediation hints (review
inactive users, suspend access, right-size tier).
script_name: "evaluate-atlassian-utilization-thresholds.sh"
expected_issue_severity: [3, 4]
access_level: "read-only"
data_type: "config"
- name: "Report Active User Trends Across Atlassian Products for Organization `${ATLASSIAN_ORG_NAME}`"
description: |
Summarizes unique active users per product using last_active timestamps from
managed accounts and last-active-dates API samples. Highlights products with
declining active-user share versus billable seats to guide renewal decisions.
script_name: "report-atlassian-active-user-trends.sh"
expected_issue_severity: [2, 3]
access_level: "read-only"
data_type: "config"
scope:
level: "Account"
qualifiers:
- ATLASSIAN_ORG_ID
- ATLASSIAN_ORG_NAME
iteration_pattern: |
One SLX per Atlassian Cloud organization. Operators supply ATLASSIAN_ORG_ID and
ATLASSIAN_ORG_NAME. The bundle paginates through organization directories and
managed accounts; no per-user qualifier is required.
resource_types:
- "atlassian_organization"
generation_strategy: |
One SLX per Atlassian organization registered in RunWhen. Qualifier: organization
name or ID. Resource match: atlassian_organization. Generation rules should
target organizations discovered via manual registration or a future org-list
discovery task using the Organizations API.
env_vars:
- name: ATLASSIAN_ORG_ID
description: "Atlassian Cloud organization UUID from Atlassian Administration"
required: true
- name: ATLASSIAN_ORG_NAME
description: "Human-readable organization name for reports and task titles"
required: true
- name: ATLASSIAN_DIRECTORY_ID
description: "Primary user directory ID when the org has multiple directories (default: discover first directory)"
required: false
default: ""
- name: LICENSE_UTILIZATION_MIN_PERCENT
description: "Minimum acceptable active/billable utilization percentage per product before raising an issue"
required: false
default: "70"
- name: USER_TIER_PROXIMITY_PERCENT
description: "Billable-user count as a percentage of purchased tier that triggers proximity alerts"
required: false
default: "80"
- name: INACTIVE_DAYS_THRESHOLD
description: "Days without product activity before a user is treated as inactive for utilization math"
required: false
default: "90"
- name: PRODUCTS
description: "Comma-separated product keys to include (e.g. jira-software,confluence,loom) or 'All'"
required: false
default: "All"
- name: TIMEOUT_SECONDS
description: "Per-task timeout; orgs with large user bases may need higher values"
required: false
default: "600"
secrets:
- name: atlassian_org_api_key
description: "Organization Admin API key used as Bearer token for Organizations REST API"
format: "Plain text API key string (Bearer token)"
platform:
name: "atlassian"
cli_tools:
- "curl"
- "jq"
auth_methods:
- "Organization Admin API key (atlassian_org_api_key Bearer token)"
api_docs: "https://developer.atlassian.com/cloud/admin/organization/rest/intro/"
related_bundles:
- name: "aws-account-cost-health"
relationship: "complements"
notes: "Covers cloud infrastructure spend; this bundle covers Atlassian SaaS seat utilization."
- name: "azure-subscription-cost-report"
relationship: "complements"
notes: "Azure dollar-based cost reporting; different cost domain but similar reporting patterns."
- name: "gcp-project-cost-health"
relationship: "complements"
notes: "GCP dollar-based cost reporting with threshold alerts; reuse issue JSON and report structure patterns."
- name: "atlassian-org-license-optimization"
relationship: "extends"
notes: "Companion bundle focused on inactive users, overlap, and reclamation recommendations."
test_scenarios:
- name: "healthy_high_utilization"
description: "Org with >80% active/billable ratio across all monitored products and tier headroom"
expected_issues: 0
- name: "low_utilization_jira"
description: "Jira Software billable seats high but active users below LICENSE_UTILIZATION_MIN_PERCENT"
expected_issues: 2
expected_severities: [3, 4]
- name: "tier_proximity_confluence"
description: "Confluence billable users at 85% of purchased tier"
expected_issues: 1
expected_severities: [3]
notes: |
- Requires Organization Admin role and at least one paid subscription for full API access.
- Prefer Organizations API v2 directory endpoints; v1 managed-accounts includes
product_access.last_active and access_billable fields critical for utilization math.
- Last-active data may lag up to 24 hours; document this in README and issue details.
- Rate limits (HTTP 429) require cursor pagination and respectful backoff — batch
last-active-dates calls only for users flagged inactive in the primary pass.
- Loom and newer products appear as product_access keys; filter via PRODUCTS env var.
- Commerce/Admin contracts APIs may require separate scopes; degrade gracefully when
tier quantities are unavailable (report utilization only, skip tier-proximity task section).
- Do NOT call suspend/revoke/remove endpoints — this bundle is read-only reporting.
- Match structural quality of gcp-project-cost-health (scorer reference: 94/100).
Design Spec: atlassian-org-license-utilization
Parent: #117
Target:
runwhen-contrib/rw-cli-codecollectionSpec