Session Context¶

Session context provides pre-filled data to VIBE templates before the interview begins. This data typically represents information about the user's organization, their permissions, or configuration settings that shouldn't be collected during the interview itself.

Overview¶

Session context is data that:

Is available when the interview starts
Cannot be modified by the user during the interview
Originates from external sources (authentication tokens, administrator configuration)
Is used just like any other variable in templates

Examples of session context:

Organization name, address, and identification numbers
User permissions and role settings
Service availability flags (which features are enabled)
Default values for contracts (insurance amounts, liability limits)
Contact information for various departments

For Template Authors¶

Using Session Context Variables¶

Session context variables are used exactly like any other VIBE variable:

{{ organization.name }}

{% if services.procurement %}
This section only appears for organizations with procurement enabled.
{% endif %}

Declaring Session Context Requirements¶

Templates declare which session context they need using the uses key in config.yml:

# config.yml
uses:
  - organization           # Simple reference - alias matches component name
  - services               # Another component
  - upphandling: procurement  # Custom alias: use 'procurement' in templates

questions:
  contract_value:
    type: number
    label: Contract value

Each entry in uses references a definition-only component that describes the structure of the expected data.

Definition-Only Components¶

Definition-only components define the shape of session context data without providing UI fields. They're marked with definition_only: true:

# components/organization.yml
definition_only: true

definitions:
  namn:
    type: text
    label: Organization name

  kortnamn:
    type: text
    label: Short name

  kontakt:
    type: structured
    label: Contact information
    fields:
      default:
        type: structured
        label: Default contact
        fields:
          namn:
            type: text
            label: Name
          email:
            type: text
            label: Email

When a template declares uses: [organization], VIBE:

Loads the definition from components/organization.yml
Makes the structure available as organization.* variables
Validates incoming session context against these definitions
Performs type coercion (e.g., string "true" → boolean true)

Aliasing Components¶

You can use a different name in your templates than the component file name:

uses:
  - organization             # Available as organization.*
  - services: tjanster       # Available as tjanster.* (Swedish alias)

Nested Structures¶

Definition components can define deeply nested structures:

# In the definition
definitions:
  upphandling:
    type: structured
    fields:
      kvalificeringskrav:
        type: structured
        fields:
          obligatorisk_registrering:
            type: bool
            default: true

{# In the template #}
{% if upphandling.kvalificeringskrav.obligatorisk_registrering %}
Registration with Bolagsverket is required.
{% endif %}

For Administrators¶

Production: PASETO Token Configuration¶

In production, session context is provided via PASETO tokens from your authentication system. The token payload should include a vibe_config key:

{
  "email": "user@example.com",
  "name": "John Doe",
  "vibe_grants": ["app_procurement", "app_avtalsgeneratorn"],
  "vibe_config": {
    "organization": {
      "namn": "Example Corp AB",
      "kortnamn": "Example",
      "orgnr": "556123-4567",
      "kontakt": {
        "default": {
          "namn": "Jane Smith",
          "email": "jane@example.com"
        }
      }
    },
    "services": {
      "procurement": true,
      "avtalsgeneratorn": true,
      "upphandlatavtal": {
        "ramavtal": true,
        "leveransavtal": false
      }
    }
  }
}

The token is typically set as a cookie by your SSO system before redirecting to VIBE.

Development: dev_settings Configuration¶

For local development and testing, configure session context in config.yml:

dev_settings:
  user:
    name: Fred Bloggs
    email: fred@example.com

  session_context:
    organization:
      namn: Test Organization AB
      kortnamn: TestOrg
      orgnr: "556000-0000"
      kontakt:
        default:
          namn: Developer
          email: dev@example.com

    services:
      procurement: true
      avtalsgeneratorn: true
      upphandlatavtal:
        ramavtal: true
        leveransavtal: true

  grants:
    - app_procurement
    - bolagsjurist

Important: dev_settings is only used when:

The application is running in debug mode (debug: true)
No PASETO token is present

Session Initialization Flow¶

When a user starts an interview, VIBE initializes the session context in this order:

Check for PASETO token - If present, extract vibe_config from the token
Fall back to dev_settings - If no token and debug mode is active, use dev_settings.session_context
Empty context - If neither is available, start with empty session context

Type Coercion¶

PASETO tokens encode all values as strings. VIBE automatically coerces values to their correct types based on the definition:

Definition Type	String Value	Coerced Value
`bool`	"true", "1", "yes"	`True`
`bool`	"false", "0", "no"	`False`
`number`	"42"	`42`
`number`	"3.14"	`3.14`
`text`	"hello"	`"hello"`

Validation¶

At session start, VIBE validates the provided session context against the template's declared requirements:

Required fields: Fields without required: false must be present
Type checking: Values must match their declared types (after coercion)
Structure: Nested structures must match the definition hierarchy

Validation errors are logged and may prevent the interview from starting.

Component Organization¶

A typical component structure for session context:

templates/my-template/
├── config.yml
├── template.md
└── components/
    ├── organization.yml        # Organization details (name, address, etc.)
    ├── organization-flags.yml  # Boolean flags about the organization
    ├── services.yml           # Which services/features are available
    ├── upphandling.yml        # Procurement settings
    ├── ramavtal.yml           # Framework agreement settings
    └── inkop.yml              # Purchasing settings

Example: Complete Session Context Setup¶

Template config.yml:

uses:
  - organization
  - organization-flags: flags
  - services: tjanster
  - upphandling
  - ramavtal
  - inkop

questions:
  contract_type:
    type: radio
    label: Type of contract
    choices:
      - Framework agreement: ramavtal
      - Delivery agreement: leveransavtal

Template usage:

# Contract for {{ organization.namn }}

{% if flags.inkopscentral %}
*This organization is a central purchasing body.*
{% endif %}

{% if tjanster.upphandlatavtal.ramavtal %}
## Framework Agreement Terms
{{ organization.kortnamn }} enters into this framework agreement...
{% endif %}

Best Practices¶

Separate concerns: Create focused components (organization, services, settings) rather than one monolithic definition
Use meaningful aliases: If your internal terminology differs from file names, use aliases for clarity
Document defaults: Include default values in definitions to document expected behavior
Group related settings: Use structured types to group related fields logically
Keep dev_settings realistic: Use real-world test data in dev_settings to catch issues early
Validate early: Session context is validated at session start, so errors surface immediately