Onboarding Tutorial

This tutorial takes you through the complete lifecycle of bringing a new client onto Causeloop: provisioning the tenant, the owner’s first login, the onboarding wizard, inviting teammates, connecting data sources, reviewing insights, configuring alert rules, and generating the first report.

This tutorial covers both the operator steps (database provisioning, run by your platform team) and the owner/user steps (UI walkthrough, performed by the client). Steps that require database or API access are clearly marked.

Before you begin

Make sure you have:

Access to the Causeloop PostgreSQL database (or ask your platform team to run the provisioning step)
The owner’s email address and display name
A decision on which plan to assign (free, starter, growth, or enterprise)

Step 1 — Provision the tenant

This step is performed by your platform team. If you are the workspace owner, skip to Step 2.

Causeloop provisions a new client in a single atomic database transaction using the onboard_client() function. This creates the organization, workspace, owner user, and membership in one call.

SELECT * FROM onboard_client(
    p_org_name       => 'Acme Corp',
    p_org_slug       => 'acme',
    p_owner_email    => 'founder@acme.com',
    p_owner_name     => 'Dana Founder',
    p_workspace_name => 'Acme Engineering',
    p_plan           => 'growth',
    p_timezone       => 'America/New_York',
    p_seats          => 25
);

The function returns four identifiers:

        organization_id         |         workspace_id          |         owner_user_id          |         membership_id
--------------------------------+-------------------------------+--------------------------------+--------------------------------
 org_01KV1PX3NNV29S67D9NT816VBS | ws_01KV1PX3NQ3B497SHK7JTNT525 | usr_01KV1PX3NR96XJRGD48NNHH431 | mem_01KV1PX3NR9KJ4NDD096HA97J3

Parameters:

Parameter	Required	Notes
`p_org_name`	Yes	Display name of the organization
`p_org_slug`	Yes	URL-safe unique identifier (e.g. `acme`) — must be globally unique
`p_owner_email`	Yes	Email address of the workspace owner
`p_owner_name`	Yes	Display name of the owner
`p_workspace_name`	Yes	Display name of the first workspace
`p_plan`	No	Defaults to `starter`
`p_timezone`	No	IANA timezone string; defaults to `UTC`
`p_seats`	No	Seat cap; defaults to plan minimum

A duplicate p_org_slug raises an error and rolls back the entire transaction. Verify the slug is unused before running the command.

Verify the provisioning:

-- Confirm org and workspace
SELECT o.slug, o.plan, w.id AS workspace_id, w.timezone
FROM organizations o JOIN workspaces w ON w.organization_id = o.id
WHERE o.slug = 'acme';

-- Confirm owner membership
SELECT u.email, m.role, m.status
FROM memberships m JOIN users u ON u.id = m.user_id
WHERE m.workspace_id = (SELECT id FROM workspaces WHERE slug = 'acme-engineering');

-- Confirm onboarding is ready
SELECT current_step, is_complete
FROM onboarding_state
WHERE workspace_id = (SELECT id FROM workspaces WHERE slug = 'acme-engineering');

Expected: owner role owner / status active, current_step = connect_source, is_complete = false. For the full provisioning runbook including bulk onboarding, offboarding, and GDPR erasure, see Client Provisioning.

Receive the invitation

The workspace owner receives a welcome email with a link to app.causeloop.ai. The link opens the Clerk sign-in page.

The owner signs in with the email address set in p_owner_email. On first sign-in, Clerk creates a credential for them. The backend syncs the Clerk identity to the pre-created user record via POST /auth/sync.

Land on the onboarding wizard

After the Clerk session is exchanged for a platform JWT (POST /auth/exchange), the owner lands on the onboarding wizard at /onboarding. The wizard reads the workspace’s onboarding_state and starts at the connect_source step.

Step 3 — Complete the onboarding wizard

The wizard has five steps. The backend tracks progress in onboarding_state. Each step is marked complete by calling POST /onboarding/steps/{step}/complete.

Welcome

The wizard greets the owner by name and explains the five steps. The owner clicks Get started to proceed.

Connect a source

The owner connects at least one data source. The wizard offers these sources from the connector catalog:

Connector	Type
Jira	Issue tracker
GitHub	Code repository
PagerDuty	Incident management
ServiceNow	ITSM
Linear	Issue tracker
Opsgenie	Alerting
Zendesk	Support

Clicking a source creates a connector via POST /connectors. The connector’s first sync begins asynchronously — issues start appearing in the workspace within a few minutes.

You can connect multiple sources at this step. Additional connectors can be added later from Settings → Integrations.

Set alert thresholds

The owner configures an alert rule that fires when a pattern’s recurrence probability exceeds a threshold.The default configuration (from GET /onboarding/config) is:

Probability threshold: 75%
Window: 7 days

Adjusting the slider and clicking Create alert rule calls POST /alert-rules. The alert rule will notify configured channels whenever a prediction crosses the threshold.

Invite teammates

The owner invites up to three teammates by email with their role. The default invite role is analyst. Available roles:

Role	Suggested for
`analyst`	Engineers and SREs who investigate issues and act on recommendations
`viewer`	Stakeholders who need read-only access to dashboards and reports
`admin`	Team leads who manage settings and connectors

Each invite triggers POST /v1/invitations. Invitees receive an email and complete their own sign-up via Clerk.

Done

The wizard displays a summary of what was set up — connected sources, alert rule, and team invites sent. The owner clicks Go to dashboard to enter the product.The onboarding_state.is_complete flag is set to true and POST /onboarding/steps/review_first_pattern/complete is called when the owner views their first pattern.

Step 4 — Invite additional teammates

If more teammates need access after the wizard, an admin or owner can invite them from Settings → Members, or directly via the API:

Via the UI
Via the API

Go to Settings → Members
Click Invite member
Enter the email address and select a role
Click Send invite

The invitee receives an email link. When they accept, Causeloop creates their user record and membership automatically.

curl -X POST https://api.causeloop.ai/v1/invitations \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sre@acme.com",
    "role": "analyst"
  }'

The role must be one of admin, analyst, or viewer. You can optionally pass team_ids to add the invitee to teams on acceptance. The endpoint returns the created invitation:

{
  "id": "inv_01J...",
  "email": "sre@acme.com",
  "role": "analyst",
  "status": "pending"
}

Step 5 — Connect the first data source (if skipped earlier)

If the owner skipped the connector step in the wizard, they can add a source from Settings → Integrations → Add connector. For a connector that uses API credentials:

curl -X POST https://api.causeloop.ai/v1/connectors \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "datadog",
    "name": "Production Datadog",
    "credentials": {
      "api_key": "dd_api_...",
      "app_key": "dd_app_..."
    },
    "poll_interval_seconds": 300
  }'

Test the credentials before the first sync:

curl -X POST https://api.causeloop.ai/v1/connectors/con_01J.../test \
  -H "Authorization: Bearer $TOKEN"

{"success": true, "message": "Connected successfully", "latency_ms": 142}

Trigger the first sync manually if you don’t want to wait for the schedule:

curl -X POST https://api.causeloop.ai/v1/connectors/con_01J.../sync \
  -H "Authorization: Bearer $TOKEN"

Step 6 — Review first insights

Once the first sync completes, navigate to Issues and then Patterns. Issues view: You will see the first batch of failure events from your connected source. Use the Severity and Status filters to focus on the most critical items. Click any issue to trigger an AI analysis (POST /issues/{id}/analyze) and see the root-cause explanation. Patterns view: After Causeloop has processed enough issues (typically within minutes of the first sync), patterns begin to appear. Each pattern shows:

The number of linked issues and the aggregate risk score
The AI-generated root-cause summary
A frequency chart with historical occurrences and a recurrence forecast
The top recommendation

Click a pattern to open the detail view. If the pattern has a recurrence prediction, you will see the probability and forecast horizon on the right panel.

Step 7 — Set up alert rules

Alert rules fire a notification when a prediction crosses a probability threshold. The owner may have created one in the wizard; here is how to create or refine rules:

Via the UI
Via the API

Go to Settings → Alert Rules → Create rule. Set the probability threshold, the forecast window, and the notification channels (email, Slack, PagerDuty webhook).

curl -X POST https://api.causeloop.ai/v1/alert-rules \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High recurrence risk",
    "threshold": 0.75,
    "window_days": 7,
    "channels": ["email", "slack"]
  }'

Alert rules are evaluated continuously as new predictions are generated. When a rule fires, a notification is dispatched to all configured channels and appears in the Activity Feed.

Step 8 — Generate the first report

Reports give stakeholders a narrative summary of issues, patterns, and recommendations over a time window. Navigate to Reports → New report and select a time range (e.g. last 7 days). The report is generated asynchronously and includes:

Issue volume by severity and source
Active and newly detected patterns
Top recommendations with expected loops prevented
Risk forecast for the next period

You can export reports as PDF or share a link with viewer-role teammates.

Troubleshooting

The owner cannot sign in after provisioning

No issues appear after the first connector sync

Check the sync run history: GET /connectors/{id}/sync-runs. A status: error entry will include a details field with the upstream error. Common causes: invalid credentials, insufficient permissions on the external tool, or a network firewall blocking outbound calls from the API to the integration.

Patterns don't appear after issues are ingested

Pattern detection runs asynchronously. If no patterns appear after 10–15 minutes, check that at least several issues share a common signal dimension (service name, error type, or team). Causeloop requires a minimum cluster size to surface a pattern. You can trigger analysis on an individual issue (POST /issues/{id}/analyze) to see the AI’s root-cause assessment before a full pattern is detected.

onboard_client() returns a duplicate slug error

Another organization already uses that slug. Choose a different p_org_slug and retry. The failed transaction leaves no partial records.

Client Provisioning Runbook

Full operator reference: bulk onboarding, offboarding, GDPR erasure, and verification queries.

Integrations Overview

Every connector type, credential formats, OAuth flows, and webhook setup.

Core Concepts

Roles, plans, seats, and the full entity reference.

API Reference

Complete endpoint documentation for programmatic onboarding and management.

​Before you begin

​Step 1 — Provision the tenant

​Step 2 — Owner first login

​Step 3 — Complete the onboarding wizard

​Step 4 — Invite additional teammates

​Step 5 — Connect the first data source (if skipped earlier)

​Step 6 — Review first insights

​Step 7 — Set up alert rules

​Step 8 — Generate the first report

​Troubleshooting

Client Provisioning Runbook

Integrations Overview

Core Concepts

API Reference

Before you begin

Step 1 — Provision the tenant

Step 2 — Owner first login

Step 3 — Complete the onboarding wizard

Step 4 — Invite additional teammates

Step 5 — Connect the first data source (if skipped earlier)

Step 6 — Review first insights

Step 7 — Set up alert rules

Step 8 — Generate the first report

Troubleshooting