Calendar Preferences

Overview

Calendar preferences control how timezone-sensitive operations work across Semaphor dashboards. They affect:

• Relative date filters such as "this week", "last month", and "year to date"
• Date aggregations like "group by week" or "group by month"
• Date formatting in visualizations and exports

By default, Semaphor uses UTC with Monday as the first day of the week. You can override these defaults at multiple levels to match your users' locale and reporting conventions.

Preference Hierarchy

Semaphor resolves calendar preferences using a multi-level hierarchy. The first level that defines a property wins, checked from top to bottom:

1. Org User / Tenant User Preferences -- Individual org users and tenant users can set their own timezone and week start via the preferences dialog in the dashboard toolbar. These take the highest priority.
2. Token Context -- Passed programmatically via params.calendarContext in the token request. Use this when you, as the developer, want to set the default timezone and week start for your customers in embedded dashboards.
3. Tenant Defaults -- Defaults for all tenant users within a specific tenant, set by admins via the Management API.
4. Organization Defaults -- Defaults for all org users and tenant users across the organization, set by admins via the Management API.
5. System Default -- { tz: 'UTC', weekStart: 1, anchor: 'now' }

Resolution for Tenant Users

For a tenant user, Semaphor checks in this order:

1. Tenant user's own preferences
2. Token calendarContext
3. Tenant defaults
4. Organization defaults
5. System default

Resolution for Org Users

For an org user, Semaphor checks in this order:

1. Org user's own preferences
2. Token calendarContext
3. Organization defaults
4. System default

Tenant defaults do not apply to org users since they are not associated with a specific tenant.

Setting Calendar Preferences

Via Token Request (Developer)

Pass calendarContext inside params when requesting an authentication token. This is the most common approach for embedded dashboards where your application already knows the user's timezone.

const requestBody = {
  dashboardId: DASHBOARD_ID,
  dashboardSecret: DASHBOARD_SECRET,
  params: {
    calendarContext: { 
      tz: 'America/Chicago', 
      weekStart: 0, 
    }, 
  },
};
 
const response = await fetch(TOKEN_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(requestBody),
});

Organization Defaults (Admin)

Set default calendar preferences for all org users and tenant users across the organization using the Management API:

curl -X PUT https://semaphor.cloud/api/management/v1/organizations/{orgId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "defaultCalendarContext": {
      "tz": "America/New_York",
      "weekStart": 0
    }
  }'

Tenant Defaults (Admin)

Override organization defaults for all tenant users within a specific tenant:

curl -X PUT https://semaphor.cloud/api/management/v1/tenants/{tenantId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer {token}" \
  -d '{
    "defaultCalendarContext": {
      "tz": "Europe/London",
      "weekStart": 1
    }
  }'

Org User and Tenant User Preferences

Individual org users and tenant users can set their own preferences through the calendar preferences dialog in the dashboard toolbar. These preferences take the highest priority and override token, tenant, and organization defaults.

How It Affects Your Dashboard

Week Start and Relative Date Filters

The weekStart value determines how "this week" and other week-relative filters are calculated.

For the week containing January 8, 2025:

This also affects "group by week" aggregations -- each bucket starts on the configured weekStart day.

Timezone and Date Boundaries

Timezone determines which calendar date a timestamp falls on. Consider a sale recorded at 11:00 PM EST on January 15:

Setting the correct timezone ensures records appear on the date your org users and tenant users expect.

Date Anchoring

By default, anchor is set to 'now', meaning relative date filters use the current time. For reproducible or historical views, pass a fixed ISO timestamp:

{
  "calendarContext": {
    "tz": "America/New_York",
    "anchor": { "iso": "2025-01-15T00:00:00" }
  }
}

With this configuration, "last 7 days" always resolves relative to January 15, 2025 -- regardless of when the dashboard is viewed.

Calendar Context Properties

Calendar preferences are expressed as a calendarContext object with three properties:

Common weekStart Values

Related

• Tokens API -- Full API reference for calendar context in token requests
• Filters -- How date filters work with calendar preferences
• Token Options -- All available options when generating embed tokens