Appearance

Configuration Templates ​

Define centrally managed, reusable constraints that allow users to configure shared environments (such as Perforce settings and depot mounts) which are then securely integrated across authorized applications.

What You'll Learn

  • Define reusable, enterprise-governed constraints for environment variables and mounts (user-provided mounts are validated against template mount rules)
  • Link apps to one or more templates to surface user configurations for those apps
  • Validate user-provided values against enterprise constraints (regex/glob)

Overview ​

User-defined Configurations

End users create per-user configurations that reference these templates. Configurations are stored at %LOCALAPPDATA%\\Turbo\\Launcher\\user-profiles.json and appear for apps that link the same template via apps[].configurationTemplates. See: User Configurations

Configuration Templates provide a secure way to:

  • Centralize reusable constraints for environment variables and mounts (e.g., P4 settings and depot/workspace paths). User configurations may supply mounts that are validated against these constraints.
  • Allow users to create or select “user configurations” within the Launcher UI based on these templates.
  • Share the same constrained configuration across multiple apps by linking apps to the same template id(s).

User-provided inputs (environment variables and mounts) are validated against enterprise constraints. If validation fails, the user configuration cannot be created or applied.

Structure ​

Top-level property (enterprise policy root):

  • configurationTemplates: Array of template objects available globally

Template fields:

  • id (string, required): Stable, kebab-case identifier (unique among templates)
  • description (string, optional)
  • constraints (object, optional):
    • environmentVariables (array):
      • key (string, required): Environment variable name (e.g., P4PORT)
      • required (boolean, optional): If true, user must supply a value
      • validationPattern (string, optional): Pattern to validate user-provided value
      • patternDescription (string, optional): User-friendly description of the pattern (displayed in UI instead of raw regex)
      • patternType (string, optional): "regex" or "exact" (use "regex" for value validation)
    • mounts (object, optional):
      • rules (array):
        • description (string, optional)
        • allowedSourcePatterns (array): Each entry has:
          • pattern (string)
          • patternType (string): "glob" or "regex"
        • allowedDestinationPatterns (array): Same shape as above
        • allowedOptions (array): Constrained list of allowed mount options, e.g., ["read-write","read-only"]

Linking apps to templates:

  • Each app can specify configurationTemplates: ["template-id", ...] to enable user configurations based on those templates for that app.

Validation behavior and resolution:

  • For environment variable constraints, user-supplied values must satisfy validationPattern (when present).
  • Environment variables inside patterns are resolved at validation time.
  • Mount constraints in templates are applied to user configurations at validation time.
  • Pattern recommendations: Use glob for Windows paths and regex for value validation.
  • Case sensitivity follows the general pattern rules (path-oriented matching is case-insensitive by default). See: Matchers & Patterns (case sensitivity)

Example: Define Configuration Templates (Enterprise Policy) ​

Location: %PROGRAMDATA%\\Turbo\\Launcher\\policy.json

json
{
  "configurationTemplates": [
    {
      "id": "p4-shared-environment",
      "description": "Standard P4 connection settings and allowed depot mounts.",
      "constraints": {
        
        // --- Environment Variable Constraints (e.g., P4 settings) ---
        "environmentVariables": [
          {
            "key": "P4PORT",
            "required": true,
            // Security: Validate the VALUE provided by the user
            "validationPattern": "^(ssl|tcp):.*\\.trusted\\.com:[0-9]+$",
            "patternDescription": "Must be a trusted SSL or TCP connection string (e.g., ssl:p4.trusted.com:1666)",
            "patternType": "regex"
          },
          { "key": "P4USER", "required": true },
          { "key": "P4CLIENT" } // Key allowed, any value permitted
        ],
        
        // --- Mount Constraints (e.g., Depot Roots) ---
        "mounts": {
          "rules": [
            {
              "description": "Allowed P4 Depot Locations",
              
              // Security: Restrict where the user can mount FROM (Host Source).
              "allowedSourcePatterns": [
                // Environment variables in the pattern are resolved at validation time.
                {"pattern": "%USERPROFILE%\\P4_Workspaces\\**", "patternType": "glob"},
                {"pattern": "D:\\P4_Depots\\**", "patternType": "glob"}
              ],

              // Security: Restrict where the user can mount TO (Container Destination).
              "allowedDestinationPatterns": [
                {"pattern": "P:\\Depots\\**", "patternType": "glob"}
              ],
              
              "allowedOptions": ["read-write", "read-only"]
            }
          ]
        }
      }
    }
  ]
}

Linking Apps to Templates ​

Applications specify which templates they can utilize. The presence of the configurationTemplates array enables user configuration integration for that specific app.

json
{
  // ... (configurationTemplates definition) ...
  "apps": [
    {
      "id": "p4v-client",
      "displayName": "Perforce P4V Client",
      // ... (matchAll, action: "allow") ...
      
      // If this array is present, user configurations based on these 
      // templates will appear in the context menu for this app.
      "configurationTemplates": ["p4-shared-environment"]
    },
    {
      "id": "dev-ide-containerized",
      "displayName": "Developer IDE",
      // ... (matchAll, action: "allow") ...
      
      // This app shares the P4 configuration by referencing the same template.
      "configurationTemplates": ["p4-shared-environment"]
    }
  ]
}

Policy-Level Structured Mounts ​

Structured mounts are supported at policy scope.

  • Authoring
    • Policy: configuration.launch.mounts, apps[].modifications.mounts, apps[].profiles[].mounts
  • User configurations: user-provided mounts validated by linked templates.
  • Validation
    • Well-known tokens (e.g., "@DESKTOP@", "@DOCUMENTS@") and Windows environment variables resolve at validation time.
  • Precedence

UI Behavior ​

When an app links one or more templates:

  • The Launcher automatically generates separate entries for each user configuration that references the linked template(s).
  • Each configuration appears as a distinct launcher entry with the format: {AppName} - {ConfigurationDisplayName}
  • User configurations are validated at creation and launch time against the enterprise constraints.
  • Only apps that are discoverable and authorized (allowed) will generate configuration entries.
  • Configuration entries automatically appear/disappear as configurations are created/deleted.

Security Considerations ​

  • Validation enforcement:
    • Environment variable values: Constrained by validationPattern (e.g., enforce trusted hostname domains, required protocols, and port format).
    • Mounts: Constrained by template mount rules (allowedSourcePatterns, allowedDestinationPatterns, allowedOptions) and validated at creation and launch.
  • Users cannot directly add or override VM flags through templates. Runtime and device-level flags remain under policy control (Launch Profile/Policy/Global scopes).
  • Templates do not bypass authorization. The app must still be matched and allowed by an application policy; hidden apps can still be used by routing when referenced accordingly.

Complementary topics:

Troubleshooting ​

  • Configuration not showing:
    • Ensure the base app is enabled, authorized (action: "allow"), and discoverable via shortcut scan.
    • Confirm the app policy includes a non-empty configurationTemplates array with valid template ids.
  • Validation failures:
    • Check validationPattern and patternType for environment variables; ensure user values match the intended format.

Best Practices ​

  • Define all template constraints in the enterprise policy to ensure consistent enforcement.
  • Prefer glob for Windows path patterns; use regex for value formats such as hostnames or P4 connection strings.
  • Keep template id stable; use kebab-case (e.g., p4-shared-environment).
  • Use clear description fields to aid administrators and auditors.

Next Steps ​

Turbo.net © 2025