Calendar

Overview

Calendar preferences define how Semaphor interprets Calendar periods. They affect:

• relative date filters such as "this week", "last month", and "year to date";
• week boundaries and week-based grouping;
• the local date and offset used to display datetime values; and
• timezone-sensitive filtering and temporal grouping.

Open More options → Report preferences → Calendar to configure a personal timezone and first day of the week.

Calendar preferences do not select a date-format pattern such as DD/MM/YYYY. Locale-aware date and datetime style preferences are a separate display-format capability and are not active in built-in consumers yet.

Preference inheritance

Personal timezone and week-start preferences use the Report Preferences hierarchy. Each property resolves independently.

For a tenant user:

personal tenant-user preference
→ initial session value from the token
→ tenant default
→ tenant's organization default
→ system fallback

For an organization user:

personal user preference
→ initial session value from the token
→ user's organization default
→ system fallback

For example, a user can choose America/Chicago while continuing to inherit Monday as the first day of the week. Clearing the personal timezone reveals the next inherited timezone.

See Report Preferences for the complete inheritance model and live-session behavior.

Configure Calendar preferences

Personal preference

Open More options → Report preferences → Calendar. You can use the displayed inherited defaults or save a custom timezone and week start. A saved change updates the open report without generating a new token.

Initial embedded-session Calendar

Pass a complete calendarContext inside params when generating a token:

const requestBody = {
  dashboardId: DASHBOARD_ID,
  dashboardSecret: DASHBOARD_SECRET,
  params: {
    calendarContext: {
      tz: 'America/Chicago',
      weekStart: 0,
      anchor: 'now',
    },
  },
};

const response = await fetch(TOKEN_URL, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(requestBody),
});

Token generation belongs on your server. Never expose DASHBOARD_SECRET or PROJECT_SECRET in browser code.

Tenant default

Set the inherited Calendar default for a tenant through the Management API:

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
    }
  }'

Organization administrators can configure the corresponding organization default in Semaphor administration or with the Management API.

How Calendar settings affect a report

Week start and relative filters

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

For the week containing January 8, 2025:

It also determines the boundary of a week grouping.

Timezone and date boundaries

Timezone determines which local Calendar date contains an instant. Consider 2025-01-16T04:00:00Z:

The applicable timezone ensures filtering, grouping, and datetime display use the viewer's expected Calendar boundary.

Relative-date anchor

anchor defines the reference instant for relative date expressions. It is a session input, not an editable personal preference.

Use now for a live report:

{
  "tz": "America/New_York",
  "weekStart": 0,
  "anchor": "now"
}

Use a fixed ISO instant for a reproducible point-in-time session:

{
  "tz": "America/New_York",
  "weekStart": 0,
  "anchor": { "iso": "2025-01-15T00:00:00.000Z" }
}

Fiscal calendar

A token can optionally seed a month-aligned fiscal calendar:

{
  "tz": "America/New_York",
  "weekStart": 0,
  "anchor": "now",
  "fiscalCalendar": {
    "kind": "month_aligned",
    "yearStartMonth": 7
  }
}

Fiscal Calendar policy is not a personal Report Preferences field. Governed project or semantic-model policy can take precedence during query execution.

Calendar context properties

When provided in a token, calendarContext is a complete object:

The personal Report Preferences UI edits only tz and weekStart.

Related

• Report Preferences
• Display formats
• Filters
• Token API