Flow Analyzer — organization administrator manual

This guide is for the customer-side administrator inside Flow Analyzer: the person who sets up the organization, connects Jira Cloud, Jira Data Center, ClickUp, Asana, Linear, Trello, or ScrumDesk Start, creates workspaces, invites teammates, and keeps integrations healthy.

Related docs: End-user SaaS manual (dashboards, findings, coaching flows) · Platform administrator manual (hosting and deployment secrets) · Org-wide Jira sharing

In the app: open Help & guide in the top header — use the Jira Cloud, Jira Data Center, ClickUp, Asana, Linear, Trello, or ScrumDesk Start section under Sources & hosting for connection setup.

Your role vs platform admin vs members

In v1, every person you invite receives `org_admin` powers: they can change connections, workspaces, and invitations. Plan onboarding copy accordingly — adding a ClickUp or Jira connection affects the whole organization, not just you.

Signing in

Email and password

1. Open your organization's Flow Analyzer URL (from your platform team or invitation email).
2. Choose Sign in.
3. Enter the email and password for your account.
4. If your organization already has workspaces, you land on the Brief home. If not, you are guided to Organization and workspaces to create your first workspace.

Create organization appears on the marketing home only when your deployment allows self-serve registration. Otherwise ask your platform administrator for access or an invitation.

Enterprise SSO (when enabled)

Some deployments configure single sign-on (OIDC or SAML) per organization. On the sign-in page you may see Continue with SSO (or similar) after entering your work email. SSO users are provisioned on first successful login; role mapping may come from your identity provider groups.

If SSO is enforced for your org, password login may be disabled except for designated break-glass accounts. SSO setup is a platform task — see SSO migration guide for operators.

Signing out

Use Sign out on a shared computer when you are done. After sign-out, protected screens require authentication again.

Organization and workspaces overview

Open Organization and workspaces from the sidebar footer, the Workspaces catalog footer, or after first login when no workspace exists.

The workspace selector in the sidebar chooses which workspace's snapshot and configuration load for dashboards, findings, and analysis. Switching workspace switches data; it does not change your organization.

If you belong to more than one company, use the organization switcher so workspace lists never mix tenants.

Source connections (Jira Cloud, Jira Data Center, ClickUp, Asana, Linear, Trello, and ScrumDesk Start)

Source connections are stored once per organization and shared by all members. Secrets are encrypted at rest; the UI shows connection name, site or team, health status, and validation time — never the raw token or OAuth secret.

Jira Cloud

Optional: webhook signing secret per connection for faster live updates (see Freshness for live Jira in the user manual).

The connections table shows Status, Last validated, Last webhook, credential errors, and the latest failed analysis job for workspaces using that connection.

Jira Data Center

Who this is for: teams running self-hosted Jira Data Center (or supported Server 8.14+) on your own network instead of Atlassian Cloud.

Where to add it: Organization and workspaces → Source connections → Add connection → Jira Data Center. Enter the URL exactly as users open Jira in the browser (for example https://jira.company.com/jira).

Reachability matters:

• On-prem Flow Analyzer on the same network as Jira is the simplest path — your platform team installs Flow Analyzer beside Jira; internal URLs and custom ports work.
• Hosted (SaaS) Flow Analyzer can reach Jira only when your security team exposes Jira to Flow Analyzer's published egress IPs (HTTPS on ports 443 or 8443) or provides a private link. If Jira is not reachable from the internet, validation explains the three supported topologies instead of a generic timeout.

Version notes: Jira 9.12 LTS and later is the certified path. Older 8.14–9.11 installs may connect in best-effort mode with a banner. Atlassian Cloud sites must use the Jira Cloud connector, not this one.

Live workspaces that use a DC connection are still `jira_live` workspaces — the same configuration wizard, JQL scope, and rule catalogue as Cloud; only the connection type differs.

ClickUp

ClickUp OAuth tokens do not expire; if someone revokes access in ClickUp, the connection shows unhealthy with an authentication error until you reconnect.

On-prem / air-gapped networks: ClickUp is a cloud-only API. If your Flow Analyzer host cannot reach api.clickup.com, validation fails immediately with an internet egress required message — not a generic timeout. Your platform team must allow outbound HTTPS or you should use a connector that runs on your internal network (for example Jira Data Center when available).

Asana

Asana OAuth tokens can be refreshed when configured; if validation fails, reconnect or rotate the personal token.

On-prem / air-gapped networks: Asana is cloud-only. If the host cannot reach app.asana.com, you see an internet egress required message when adding or validating a connection. Allow outbound HTTPS from the Flow Analyzer server or use an internal work source instead.

Linear

Linear OAuth token refresh automation is deferred; if validation fails, reconnect or rotate the personal API key.

Trello

Trello uses a deployment-wide API key plus per-org member tokens stored encrypted. Webhooks register against your public app URL when you scope boards in the connect wizard.

ScrumDesk Start (cloud)

Request project-scoped integration tokens from support@scrumdesk.com when your ScrumDesk admin does not issue personal tokens. This connector does not use the legacy Windows OData API.

Policy reminder: rotating or deleting a connection affects every workspace that uses it. See Org-wide Jira sharing (same sharing model applies to ClickUp, Asana, Linear, Trello, and ScrumDesk connections).

Connect ClickUp — OAuth path

Prerequisite: Your platform administrator must set CLICKUP_CLIENT_ID, CLICKUP_CLIENT_SECRET, and CLICKUP_OAUTH_REDIRECT_URI on the deployment. If OAuth is not configured, the UI offers only the personal token path (or shows an error when starting OAuth).

1. Open Organization and workspaces.
2. In Source connections, choose Add connection → ClickUp.
3. Enter a display name your team will recognize (for example Delivery ClickUp).
4. Choose Connect with ClickUp (OAuth).
5. Complete the ClickUp authorization in the browser; you return to Flow Analyzer with the connection saved.
6. Confirm Status shows healthy after validation (may take a few seconds).

You can add the connection here first, or start from the Connect ClickUp wizard (next section) which can open the same dialog.

Connect ClickUp — personal API token path

Use this when OAuth is unavailable or you use a dedicated ClickUp service account.

1. In ClickUp, open Settings → Apps (or your workspace settings) and create a personal API token with access to the teams and lists you need.
2. Note your ClickUp Team ID (Workspace ID) from ClickUp settings or URL.
3. In Flow Analyzer, Organization and workspaces → Source connections → Add connection → ClickUp.
4. Enter display name, personal API token, and Team ID.
5. Save. Fix any validation error shown in the table before creating live workspaces.

Tokens are stored encrypted; they are not shown again after save. To rotate, edit the connection and paste a new token.

Create a live ClickUp workspace (connect wizard)

After at least one healthy ClickUp connection exists:

1. Open Workspaces in the sidebar (or go to Connect ClickUp from the live ClickUp group placeholder).
2. Start the Connect ClickUp wizard.
3. Connection — select the ClickUp connection to use.
4. Hierarchy — expand Team → Space → Folder → List and check the lists whose tasks you want in this workspace. Only selected lists are ingested.
5. Statuses — review how ClickUp status types map to todo, in progress, and done. Adjust per list if your workflow uses custom statuses.
6. Sprints — confirm which lists are sprint iterations (lists with sprint-like folder names or date bounds are suggested; you confirm the final set). Sprint-dependent rules use only lists you mark here.
7. Review — read the Rule coverage preview (see below), name the workspace, and create it.

The new workspace type is `clickup_live`. Open it from Workspaces, then run analysis from the dashboard.

After connect:

• Changed tasks refresh via ClickUp webhooks (with API re-fetch) and a scheduled safety-net poll your platform team configures.
• Resource Sankey and RA- rules need time entries in ClickUp; run analysis after ingest completes.

Connect Asana — OAuth path

Prerequisite: Your platform administrator must set ASANA_CLIENT_ID, ASANA_CLIENT_SECRET, and ASANA_OAUTH_REDIRECT_URI on the deployment.

1. Organization and workspaces → Source connections → Add connection → Asana.
2. Enter a display name and choose Connect with Asana (OAuth).
3. Complete authorization; confirm Status is healthy.

Connect Asana — personal access token path

1. In Asana, create a personal access token with access to the workspaces and projects you need.
2. In Flow Analyzer, add an Asana connection with display name, token, and workspace GID when prompted.
3. Save and fix validation errors before creating live workspaces.

Create a live Asana workspace (connect wizard)

1. Open Connect Asana (/flow-analyzer/connect-asana).
2. Connection — select the Asana connection.
3. Projects — check the projects whose tasks belong in this workspace.
4. Statuses — choose sections or enum-field mode and confirm categories (todo / in progress / done).
5. Review — read Rule coverage preview, name the workspace, create `asana_live`.

Connect Linear — OAuth path

Prerequisite: Your platform administrator must set LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET, and LINEAR_OAUTH_REDIRECT_URI on the deployment.

1. Organization and workspaces → Source connections → Add connection → Linear.
2. Enter a display name and choose Connect with Linear (OAuth).
3. Complete authorization; confirm Status is healthy.

Connect Linear — personal API key path

1. In Linear, create a personal API key with access to the teams and projects you need.
2. In Flow Analyzer, add a Linear connection with display name, API key, and optional default team ID for webhook registration.
3. Save and fix validation errors before creating live workspaces.

Create a live Linear workspace (connect wizard)

1. Open Connect Linear (/flow-analyzer/connect-linear).
2. Connection — select the Linear connection.
3. Teams — check the teams whose issues belong in this workspace.
4. Projects — optionally narrow to specific projects (leave empty for all team issues).
5. Statuses — confirm workflow state categories (todo / in progress / done).
6. Review — read Rule coverage preview, name the workspace, create `linear_live`.

Connect Trello (API token)

Your platform operator must set `TRELLO_API_KEY` on the deployment. Each org admin then:

1. Organization and workspaces → Source connections → Add connection → Trello.
2. Enter a display name and paste the member API token from trello.com/app-key.
3. Open Connect Trello (/flow-analyzer/connect-trello), select boards, map lists to categories, and create `trello_live`.

Webhook registration uses the public app URL; list moves on scoped boards trigger incremental ingest.

Connect ScrumDesk Start (API token)

1. Organization and workspaces → Source connections → Add connection → ScrumDesk.
2. Enter a display name and paste the integration or personal API token from ScrumDesk Start cloud.
3. Open Connect ScrumDesk (/flow-analyzer/connect-scrumdesk), select projects, map workflow steps to categories, and create `scrumdesk_live`.

Freshness relies on manual or scheduled re-ingest until ScrumDesk cloud webhooks are available.

Connect Jira Cloud (live workspaces)

Jira setup is documented in depth in the user manual — workspaces and shared Jira. Summary for org admins:

When your organization has more than one Jira connection (for example Jira Cloud and Jira Data Center, or two different sites), creating a `jira_live` workspace opens a Choose Jira connection dialog — pick the site and connector type before the workspace is created. If you have only one Jira connection, Flow Analyzer links it automatically.

1. Organization and workspaces → Source connections → Add connection → Jira Cloud.
2. Connect with OAuth or API token (see table above).
3. Create a `jira_live` workspace from Workspaces or Organization settings:

• Link the Jira connection.
• Set project scope or JQL as prompted.

1. Open Configuration for that workspace and use Configure from source (live Jira, ClickUp, Asana, Linear, or Trello workspaces) to pick issue types, workflow stages, and buckets from live metadata.
2. Optionally configure webhooks for freshness (Jira webhooks doc).

For offline portfolios, create a `jira_export` workspace and use Import data — see Jira export import workspaces in the user manual.

Connect Jira Data Center (live workspaces)

Who this is for: delivery leads and org admins whose work lives in self-hosted Jira, not *.atlassian.net.

Why: The same flow-health analysis, findings, and configuration wizard as Jira Cloud — without moving issues to Atlassian Cloud.

Where to find it:

1. Organization and workspaces → Source connections → Add connection → Jira Data Center.
2. Enter a display name, your Jira base URL (with context path if applicable), and a PAT (recommended) or Basic credentials.
3. After validation shows healthy, create a `jira_live` workspace from Workspaces (use the connection picker when more than one Jira connection exists), link the DC connection, and set project scope or JQL.
4. Open Configuration and use Configure from source to map issue types, workflow stages, and buckets from live metadata.

How it differs from Jira Cloud:

• No Atlassian OAuth site picker — you type the server URL yourself.
• Credentials are a PAT or Basic pair, not an Atlassian API token.
• Webhooks work best when Flow Analyzer runs on-prem on the same network as Jira; SaaS tenants often rely on scheduled polling when Jira cannot call back to the public internet.
• If validation fails with a reachability message, read the topology guidance in the error and coordinate with your platform administrator — opening arbitrary outbound internet access is not required when both products run internally.

Shared credentials: like Cloud, a DC connection is stored once per organization and shared by all members who can access workspaces using that connection.

Workspace types

Demo vs live is determined by the active workspace, not a browser-wide data-source switch (SaaS mode disables the old operator banner switcher).

Workspace configuration

Who this is for: Organization administrators (and Scrum Masters who hand off to admins) after you create a live or import workspace.

Where: Sidebar → Configuration for the active workspace. Use Configure from source to map issue types, workflow stages, and buckets from your connector catalog.

AI Chat configuration coach: Open AI Chat → skill Workspace config coach. The coach asks one question at a time with quick-answer chips, grounded in your live catalog and current configuration. Review the summary, then Apply to workspace (organization administrators only). Members without admin rights can complete the interview and open Configuration or copy the recommendation for an admin. Applying does not replace the Configuration screen — use it when you want full control or to verify what the coach saved.

After major configuration changes, run Run analysis again when you are ready so findings reflect the new mappings.

Running analysis and background jobs

Analysis ingests fresh data from the connected source (for live workspaces) and runs the rule catalogue on the workspace snapshot. Findings, charts, and exports use the latest successful run.

From the UI

1. Select the target workspace in the sidebar selector.
2. On the Brief dashboard (or analysis panel), choose Run analysis.
3. Wait for the job to finish — status moves from queued → running → succeeded or failed.
4. Open Findings, Map, Resource Sankey, and other screens after success.

If ingest fails, check Organization settings on the connection row for the latest error and failed job hint.

What happens in the background

• Live Jira: webhooks and scheduled polls enqueue ingest jobs when issues change or on a timer.
• Live ClickUp: webhooks mark tasks dirty; ingest re-fetches via API; the same scheduled poll covers ClickUp live workspaces.
• Live Asana, Linear, and Trello: webhooks mark changed work items dirty; ingest re-fetches via API.
• Live ScrumDesk: re-ingest via manual analysis runs or scheduled poll when your operator enables it (no outbound webhooks yet).
• Import workspaces: upload triggers a parse + analysis job.

Automation without the browser (CI, Slack) uses a deployment-level headless token — ask your platform administrator; contract: headless analyze API.

Inviting members and roles

1. Open Organization and workspaces → People & invitations.
2. Enter the teammate's email and choose Send invitation.
3. Copy the one-time token shown on screen and send it through a channel you trust (email delivery depends on SMTP configuration by your platform team).
4. The invitee signs in (or registers) with the same email, opens Accept invitation, pastes the token, and confirms.

v1 roles: everyone is `org_admin`. A future member or analyst role with reduced settings access is not productized yet — document internally that all invitees can manage connections.

Rule coverage preview

When you configure a workspace from Jira or finish the ClickUp wizard, Flow Analyzer shows Rule coverage preview:

> N of M catalogue rules will run with this source.

Why it matters: ClickUp and partial Jira scopes are honest about limits — you see upfront which coaching signals will not appear until you expand scope or enrich data (for example enable time tracking for resource rules).

The preview is informational. Analysis still runs all applicable rules for the workspace configuration; skipped rules do not produce false findings.

If the preview fails to load, you can still save configuration; retry after connection health is green.

Troubleshooting

Connection shows unhealthy

1. Open Organization and workspaces → Source connections.
2. Read Status and the latest error message on the row.
3. Choose Edit / re-validate: refresh OAuth, paste a new token, or fix Team ID / site URL.
4. Check whether a failed analysis job is linked on the Jira connections table (ingest errors often surface there).

ClickUp returns 401 / authentication failed

"Internet egress required" (ClickUp or Asana)

Your Flow Analyzer deployment runs on-premise or on a network that blocks outbound HTTPS to the vendor cloud. ClickUp needs `api.clickup.com`; Asana needs `app.asana.com`.

This is expected behavior — the product explains the requirement instead of hanging on a timeout.

License expired banner (on-prem deployments)

On some self-hosted installs, a yellow banner at the top of the app means the offline license has expired or is missing. You can still view existing dashboards and snapshots, but new analyses are paused until your platform administrator installs a renewed license file. Contact them — this is not fixed from Organization settings.

"OAuth not available" or OAuth start fails

Your deployment is missing ClickUp OAuth env vars. Use personal API token instead, or open Help & guide → ClickUp under Sources & hosting (or ask your platform administrator to register a ClickUp OAuth app per the platform manual).

Missing webhooks / stale data

• Jira: confirm webhook URL and signing secret; see Jira webhook freshness. Last webhook on the connection should update after Jira changes.
• ClickUp: platform must allow inbound HTTPS to the deployment; poll cron must run (platform task).
• Run Run analysis manually to force a full ingest after fixing configuration.

No findings after analysis

• Confirm analysis job succeeded (not failed mid-ingest).
• For new workspaces, wait for first ingest to complete (large backlogs take longer).
• Check rule coverage preview — many rules may be skipped for minimal scope.
• Demo seed workspaces always have findings after analysis; live workspaces need tasks in selected lists/projects.

Cannot create organization or sign in

• Self-serve registration may be disabled — contact platform admin.
• SSO enforcement may require the SSO button instead of password.
• Repeated failed logins or registration may hit rate limits — wait and retry.

Need host-level help

Escalate to your platform administrator with: workspace name, connection display name, approximate time of failure, and whether the issue affects all users. They check migrations, cron secrets, and deployment logs — not your ClickUp list picks.

Security reminders (org admin)

• Do not share API tokens in public chat or tickets; use your company's secret channel.
• Treat invitation tokens like passwords until accepted.
• Removing a member revokes access to all org workspaces immediately.
• The UI never displays stored secrets; if you need to rotate credentials, edit the connection and supply new values.

Operators and auditors: NFR-03 checklist · Jira-derived persistence allow-list.

License, billing, invoices, and privacy

Open Organization and workspaces → License & billing (org admins only for billing changes).

Invoices: Paid, open, and overdue invoices appear in the sortable table. Use Download PDF or Pay now when Stripe or bank-transfer payment is configured.

Organization export: JSON bundle includes profile, members, workspace summaries (no connector secrets), billing events, invoices, usage snapshots, evaluation notes, security audit events, and workspace org roster metadata (config.org — names or codes, FTE, employment type, identity mode; credentials redacted) for your company. It excludes invite tokens, credentials, and raw analysis snapshot blobs.

Workforce roster & org structure: On the Organization tab, org admins can turn Workforce roster storage off for the whole company (roster imports and edits blocked; read-only org structure remains). By default it is on (unlike AI Agents, which stay off until enabled). Per workspace, choose an identity mode (named, pseudonymous codes, or structure-only) on the Org structure screen. Storing real names requires an in-product authority acknowledgment — confirm your organization is authorized and has informed staff as required by law. Pseudonymous mode still processes work-tracker account identifiers from snapshots for capacity joins; it is not full anonymity. Details: GDPR workforce plan and Privacy Policy. For a Data Processing Agreement or workforce privacy questions, use the note on Privacy & data (email privacy@scrumdesk.com).

Organization deletion: Schedules a 90-day grace period (operator-configurable) before hard purge. Open invoices are voided; active Stripe subscriptions are canceled when possible. Member user accounts are not deleted — only the organization and its workspaces, connections, and billing data. For legal hold or cross-org requests, contact privacy@scrumdesk.com.

Related documentation