Configuring ActivityPulse

The Settings area is where you configure your ActivityPulse organization — users and roles, LLM providers, data source connections, sync schedules, and email delivery. Access it from the sidebar by clicking Settings.

What you can see and change depends on your role:

Role	Settings access
Owner	Full access to all settings, including user management and organization deletion
Admin	All settings except promoting users to Owner or deleting the organization
Manager	Cannot access settings; uses Settings > Email Reports to configure their own email preferences
Viewer	Cannot access settings; uses Settings > Email Reports to configure their own email preferences

Server Configuration

Some settings are configured as environment variables by the system administrator rather than through the web interface.

Variable	Required	Default	Description
`DATABASE_URL`	Yes	—	PostgreSQL connection string
`JWT_SECRET`	Yes	—	Secret key used to sign authentication tokens
`APP_URL`	No	Derived from request	Base URL of the ActivityPulse instance (e.g. `https://activitypulse.example.com`). Used to construct user invitation links and SSO redirect URIs. When not set, the server falls back to the `Origin` or `Referer` header from the browser request.
`HOST`	No	`0.0.0.0`	Network interface the server listens on
`PORT`	No	`8080`	Port the server listens on

Recommendation: Set APP_URL in production. It is required for SSO and ensures invitation links always point to the correct address regardless of how the request reaches the server (e.g. behind a reverse proxy).

Where to set environment variables

The configuration file location depends on how ActivityPulse was deployed:

Deployment method	Configuration file	Apply changes
Debian package	`/etc/activitypulse/activitypulse.conf`	`sudo systemctl restart activitypulse`
Tarball	`/opt/activitypulse/activitypulse.conf`	`sudo systemctl restart activitypulse`
Docker	`.env` next to `docker-compose.yml` (typically `/opt/activitypulse/.env`)	`docker compose up -d`

The installer automatically generates DATABASE_URL, JWT_SECRET, and APP_URL during first-time setup. APP_URL is auto-detected from the machine’s hostname — update it to match your actual domain or URL if you use DNS or TLS.

User Management

Navigate to Settings > Users to manage who has access to your organization.

A fresh deployment ships with public sign-up enabled so the first administrator can register an account and bootstrap their organization. As soon as that first registration succeeds, ActivityPulse automatically disables public sign-up — additional users can only join through invitations from then on.

Owners can review or override this behaviour from Settings > General, in the System card. The Allow public sign-up switch reflects the current state and lets owners re-open registration if a second bootstrap is ever needed (rare; most deployments leave it disabled). When public sign-up is disabled, the Sign up link on the login page is hidden and the /register API returns 403.

Inviting users

The primary way to add new people is by invitation. Click Invite user, enter the person’s email address, display name, and select a role. ActivityPulse sends an email with a unique invite link that expires after 7 days.

Prerequisite: Email delivery must be configured before you can send invitations. See Email Settings below.

The Users page shows pending invitations alongside active users. For each pending invite you can:

Resend — generates a fresh token and sends a new email (useful if the original expired)
Cancel — revokes the invitation so the link can no longer be used

When the recipient clicks the invite link, they are guided through account creation and are automatically added to your organization with the role you selected.

Inviting existing teammates as users

If someone is already a Teammate, you can invite them by selecting the teammate from the list. Click Invite User, search for the teammate, and assign a role.

Roles

ActivityPulse uses four roles with a clear permission hierarchy:

Permission	Owner	Admin	Manager	Viewer
View own/team activity data	Yes	Yes	Yes	Linked only
View direct reports (if configured)	Yes	Yes	Yes	No
Configure own email reports	Yes	Yes	Yes	Yes
Manage teammates and external IDs	Yes	Yes	No	No
Manage teams	Yes	Yes	No	No
Configure team access (direct reports)	Yes	Yes	Yes	No
Configure data sources	Yes	Yes	No	No
Change LLM, sync, and email settings	Yes	Yes	No	No
Add, invite, and remove users	Yes	Yes	No	No
Promote or demote Managers or Viewers	Yes	Yes	No	No
Promote or demote Admins	Yes	Yes	No	No
Promote or demote Owners	Yes	No	No	No
Delete the organization	Yes	No	No	No

An organization must always have at least one Owner.

Viewer role note: Viewers see only their own activity data by default after being linked to a teammate record. Their visibility can be extended by granting them team access (see Roles and Access Control → Viewer for the full data-visibility rules). ActivityPulse links them automatically when a teammate with the same email exists; if it doesn’t (or if the email is ambiguous), open Manage teammate link from the row’s ⋮ menu — see Linking users to teammates below.

Team access

Users and teammates are different concepts in ActivityPulse. A user is someone who logs in to the application; a teammate is a person whose activity is being tracked across data sources. A user does not have to be a teammate, and a teammate does not need a user account. When both exist for the same person, they are linked by email address.

Teams are groups of teammates — users cannot be added to teams. From the Users page, you can scope a Manager’s or Viewer’s view to one or more teams by clicking the team access action on their row. For a Manager, the grants narrow what they can see (with the fail-open default of “all teammates” when no grants exist). For a Viewer, the grants extend visibility beyond self-only to include the granted teams’ teammates.

For details on creating and managing teams and teammates, see the Teammates and Teams section of the features overview.

Linking users to teammates

Every user account can be linked to the teammate record that represents the same person. This mapping is what lets a Viewer see their own activity (determined by their linked teammate) — the default visibility for the Viewer role — and is also used by Manager scoping. A Viewer can additionally be granted team access to extend their view beyond self-only; see Roles and Access Control → Viewer.

The link state is shown in the Teammate column of the Users page. ActivityPulse links automatically whenever a user and a teammate with the same email exist in the org — no admin action is needed in the common case:

When a user is added or an invitee accepts, ActivityPulse checks for a teammate with the same email and links them immediately.
When a teammate is created, ActivityPulse links them to a matching org user immediately.
The Teammate column then shows either Not linked or the linked teammate’s name.

For the cases auto-link can’t handle (typos / aliases / second accounts, ambiguous email matches across multiple teammates, or correcting an existing link), open the row’s ⋮ menu → Manage teammate link to pick a teammate from a dropdown — or pick No link to clear an existing link.

When adding or inviting a user, the dialog includes a checkbox Add teammate with the same email (checked by default). When enabled:

On Add User, a teammate with the same email is created (or reused if one already exists) and linked to the new user.
On Invite User, the teammate is created up-front so the link can be established the moment the invitee accepts.

Note on Viewers: If a Viewer remains unlinked (typically because their email is ambiguous across multiple teammates), they cannot see their own activity. If the Viewer also has no team grants, they see nothing at all. Open the row’s ⋮ menu → Manage teammate link to pick the right teammate.

LLM Configuration

Navigate to Settings > LLM to configure the language model that powers activity summaries.

Provider and model:

Select a provider — Anthropic (Claude) or OpenAI
Enter your API key and click Validate. ActivityPulse checks the key against the provider’s API and, on success, populates the model dropdown with available models.
Choose the model you want to use for generating summaries.

Response settings:

Setting	Range	Default	Description
Max response tokens	256 – 16,384	Provider default	Controls the maximum length of generated summaries
Debug mode	On / Off	Off	When enabled, shows the raw prompt sent to the LLM alongside the generated summary — useful for prompt tuning

Custom summary prompts:

Next to the provider settings, the Summary Prompts card lets you edit the prompt templates that ActivityPulse sends to the LLM. An Individual / Team selector at the top of the card switches between two templates:

Individual — used when generating an individual teammate’s summary.
Team — used when generating a team summary (a combined review across two or more teammates).

Use these to tailor the output to your organization’s tone, focus areas, or formatting preferences. Each has its own Reset to default button that restores the built-in prompt at any time. Switching the selector keeps any unsaved edits to the other template.

Data Sources

Navigate to Settings > Data Sources to connect ActivityPulse to the tools your team uses.

Available sources

Source	What it fetches
GitLab	Commits, merge requests, code reviews, issues, pipelines
GitHub	Pull requests, commits, issues, reviews, branches
Atlassian (Jira & Confluence)	Issues, worklogs, comments, Confluence pages and edits
Azure DevOps	Commits, pushes, pull requests, work items (Boards), wiki edits, pipeline runs
Microsoft 365	Email volume, Teams calls and meetings, OneDrive/SharePoint activity, calendar events
Salesforce	Logged calls, emails, and meetings, opportunity, lead, case, and account activity, and Chatter posts

Configuring a data source

Select a source from the list to open its configuration form. Each source requires its own credentials — typically a URL and an API token or app registration. Fill in the required fields and click Save.

For step-by-step setup instructions including required permissions and scopes, see the dedicated configuration guides:

Testing a data source

After saving, click Validate to verify that ActivityPulse can connect to the source using the credentials you provided. Validation checks authentication and basic API access — if it fails, review the error message and confirm your token, URL, and permissions.

Syncing data

Once a source is configured and validated, you can trigger a manual sync:

Fetch all — syncs every configured source at once
Fetch (per source) — syncs only the selected source

After a fetch completes, ActivityPulse reports the number of activities and signals retrieved, the duration, and any errors. For ongoing data collection, configure the automatic sync schedule under Data Sync Settings.

Data Sync Settings

Navigate to Settings > Data Sync to control how ActivityPulse fetches and retains data from your connected sources.

Setting	Range	Default	Description
Sync frequency	1 – 168 hours	24 hours	How often ActivityPulse automatically pulls new data from each source
Historical data window	1 – 365 days	30 days	How far back each sync reaches when fetching data
Data retention	1 – 365 days	90 days	How long activity data is kept before automatic cleanup

How background sync works:

ActivityPulse runs a scheduled background job at the configured frequency. Each run fetches data from all enabled sources for all teammates whose sync is active. Built-in guards prevent overlapping fetches — if a sync for a particular organization and source is already in progress, the scheduler skips it rather than starting a duplicate.

You can always trigger an immediate sync from the Data Sources settings without waiting for the next scheduled run.

Email Settings

Navigate to Settings > Email to configure how ActivityPulse sends emails. Email delivery is used for user invitations, password resets, and scheduled summary reports.

ActivityPulse supports two email transports:

Transport	Best for	Requirements
SMTP	Any email provider with SMTP access	SMTP server credentials
Microsoft Graph API	Microsoft 365 organizations	MS365 data source configured with `Mail.Send` permission

If your organization uses Microsoft 365 and has already configured the MS365 data source, the Graph API transport is recommended — it reuses your existing Azure AD app registration and bypasses SMTP authentication restrictions that many organizations enforce.

After selecting a transport and entering the required settings, use the Send test email button to verify that delivery works before relying on it for invitations or reports.

For complete setup instructions — including Office 365 SMTP configuration, app password setup, Graph API permissions, and troubleshooting — see the Email Configuration guide.

Tip: Configure email before inviting users. Without a working email transport, invitations cannot be sent.

Single Sign-On (SSO)

Navigate to Settings > SSO to allow users in your organization to sign in with their Microsoft account instead of an email and password.

Prerequisites

Before enabling SSO, two things must be in place:

Microsoft 365 data source configured — SSO reuses the Azure AD app registration (tenant ID, client ID, and client secret) from your MS365 data source plugin configuration. See Microsoft 365 plugin configuration for setup instructions.
APP_URL environment variable set — the server uses this to construct the OAuth redirect URI. See Server Configuration above.

Enabling SSO

Once the prerequisites are met, toggle Enable SSO on and click Save configuration. Users will see a Login with Microsoft button on the login page.

When a user clicks Login with Microsoft:

Single-organization deployments — the user is redirected to Microsoft sign-in immediately. No email address is needed.
Multi-organization deployments — the user must first enter their email address so ActivityPulse can identify which organization (and which Azure AD tenant) to authenticate against.

After successful authentication with Microsoft, the user is logged in automatically. The user must already have an ActivityPulse account — SSO authenticates existing users but does not create new accounts.

Azure AD app registration requirements

The Azure AD app registration used for SSO must have a redirect URI configured. Add the following URI to the app’s Authentication > Web > Redirect URIs in the Azure portal:

{APP_URL}/auth/microsoft/callback

Replace {APP_URL} with your ActivityPulse instance URL (for example, https://activitypulse.example.com).

The app registration must also have the following API permissions:

Permission	Type	Purpose
`openid`	Delegated	Sign users in
`profile`	Delegated	Read basic profile
`email`	Delegated	Read user email address
`User.Read`	Delegated	Read signed-in user profile from Microsoft Graph

These permissions are typically already granted if you have configured the MS365 data source.

Field Length Limits

Text fields across Settings have a maximum length. If you exceed it, the form shows an inline error and the value is not saved — nothing is submitted and dialogs stay open so you can shorten the text without retyping the rest.

Field	Maximum
Display name (user)	50 characters
Email address	254 characters
Password	128 characters
Organization name	100 characters
Teammate name	100 characters
Team name	100 characters
Team description	500 characters
LLM provider	50 characters
LLM model	100 characters
SMTP host / username	255 characters
From address	254 characters
From name	100 characters
Summary prompt	20,000 characters
Feedback subject	200 characters
Feedback message	5,000 characters

Lengths count characters, not bytes — an emoji or an accented letter counts as one character, the same way it does when displayed.