getCustomSetting

This function retrieves a value from the brixxbox workspace custom settings. These settings are stored at the workspace level and can be accessed by any app within the workspace, making them useful for global configuration values, shared parameters, and application-wide settings.

Syntax

app.getCustomSetting(settingName)

Parameters

Parameter	Type	Description
settingName	String	The key (name) of the setting to retrieve

Return Value

Returns a Promise that resolves to:

• The value of the requested setting (can be a String, Number, Boolean, or null)
• undefined if the setting does not exist

Setting Name Format

Setting names can be organized hierarchically using dot notation. For example:

• "email.smtp.server" - Access the server value within the smtp group within the email group
• "theme.colors.primary" - Access the primary color within the colors group within the theme group
• "companyInfo.name" - Access the company name within the companyInfo group

Examples

Example 1: Basic usage to retrieve a simple setting:

// Get the company name from settings
const companyName = app.getCustomSetting("companyInfo.name");

// Display the company name in a field
app.setFieldValue("companyNameField", companyName);

Example 2: Using custom settings for API configuration:

// Get API endpoint and key from settings
const apiEndpoint = app.getCustomSetting("api.invoicing.endpoint");
const apiKey = app.getCustomSetting("api.invoicing.key");

// Use these settings to make an API call
const response = fetch(apiEndpoint, {
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json"
  }
  // Additional fetch options...
});

Example 3: Conditional logic based on feature flags in settings:

// Check if a feature is enabled in settings
const isAdvancedReportingEnabled = app.getCustomSetting("features.advancedReporting");

if (isAdvancedReportingEnabled === "true" || isAdvancedReportingEnabled === true) {
  // Show advanced reporting controls
  app.setVisible("advancedReportingSection", true);
  app.refresh("reportingGrid");
} else {
  // Hide advanced features
  app.setVisible("advancedReportingSection", false);
}

Related Functions

• setCustomSetting() - For storing values in the workspace custom settings (admin users only)
• getFieldValue() - For retrieving values from form controls rather than settings
• getConfigRecord() - For retrieving configuration data stored in database records
• loadConfigRecordById() - For loading complete configuration records
• getCustomMessage() - For retrieving localized messages from the message manager

Notes

• Custom settings are read-only for regular users; only administrators can modify them
• Settings are workspace-specific, not application-specific
• Settings are often used for:
  • Application configuration without code changes
  • Centralized management of shared values
  • Feature flags to enable/disable functionality
  • External API credentials and endpoints
  • Business rules that may change over time
• For user-specific settings, consider using user preferences or local storage instead