Configure parameters

You can change the configuration of Planning Analytics Workspace Local by modifying the paw.ps1 (Windows) or paw.env (Linux®) configuration file.

When you change a paw configuration file, you must run ./scripts/paw for your operating system for your changes to take effect. Only services that the configuration change affects restarts.

Important: Do not change the values in defaults.ps1. Use paw.ps1 to override a value in defaults.ps1.

Do not change the values in defaults.env. Use paw.env to override a value in defaults.env.

The default values for the configuration parameters are stored in defaults.ps1 for the Microsoft Windows operating system and defaults.env for Linux. If you want to change any of the parameters, open the paw.ps1 file or paw.env in a text editor, and modify the parameters. If a parameter is specified in paw.ps1 or paw.env, the value in paw.ps1 or paw.env overrides the value in defaults.ps1 or defaults.env.

Tip: When you specify a parameter in paw.ps1, use the format that is shown in defaults.ps1. When you specify a parameter in paw.env, use the format that is shown in defaults.env. Some parameters are specified with quotation marks and some are not, depending on your operating system.

OIDC authentication

Planning Analytics Local requires OpenID Connect (OIDC) authentication for Planning Analytics Workspace. Configure OIDC by setting PAAuthMode to oidc and adding your provider values to paw.env. After you modify the paw.env file, run the platform script to apply changes (paw.sh on Linux or paw.ps1 on Windows).

For example, to enable OIDC authentication, add the following lines to the paw.env file and specify your own values for each parameter:

export PAAuthMode="oidc"
export OIDC_CLIENT_ID="<oidc_client_id>"
export OIDC_CLIENT_SECRET="<secret_string>"
export OIDC_REDIRECT_URI="https://pawhost.example.com:8443/login"
export OIDC_ISSUER="https://oidc-provider.example.com/oidc/endpoint/default"
export OIDC_DISCOVERY_URL="https://oidc-provider.example.com/oidc/endpoint/default/.well-known/openid-configuration"
export OIDC_LOGIN_ID_CLAIM="<oidc_claim_id>" # Optional
export OIDC_DISPLAY_NAME_CLAIM="<oidc_claim_name>" # Optional
export OIDC_GROUPS_CLAIM="<oidc_claim_name_for_groups>" # Optional
export OIDC_EXTRA_SCOPES="<extra_scope1> <extra_scope2> # Optional
export OIDC_FORCE_LOGIN_PROMPT=false # Optional, set to true to force login prompts

Most OIDC providers require TLS (HTTPS) for the redirect URI, such as https://pawhost.example.com:8443/login. Your identity provider supplies the values for OIDC_CLIENT_ID, OIDC_CLIENT_SECRET, and OIDC_ISSUER.

After OIDC authentication is configured, you must connect each environment to a TM1 12 database instance. For more information, see Connecting to the TM1 12 instance.

Configuration parameters

The following list describes the parameters in defaults.env and defaults.ps1.

API_ALLOW_ORIGINS

This parameter allows cross-origins to access API endpoints. Set to a space-separated list of domains. You can use * for global matching. By default, only same-origin is allowed. For example,

API_ALLOW_ORIGINS="*.example.com http://*.enterprise.com"

This parameter is required to embed URL links to Planning Analytics Workspace within an iframe in another product such as IBM® Cognos® Analytics. This technique is an example of Cross-Origin Resource Sharing (CORS).

For more information, see Access-Control-Allow-Origin and Same-origin policy.

CSP_FRAME_ANCESTORS

This parameter enables the HTTP Content Security Policy frame-ancestors directive. Enter values as the list of valid parent frame sources separated by a space. The default is self.

This parameter is required to embed URL links to Planning Analytics Workspace within an iframe in another product such as IBM Cognos Analytics. This technique is an example of Cross-Origin Resource Sharing (CORS).

For more information, see CSP: frame-ancestors.

DISABLED_SPREAD_OPTIONS

Use this parameter to disable select data spreading methods in cube views and single cell widgets.

When you disable a data spreading method, the method cannot be applied in a cube view or in a single cell widget. The method is grayed-out and cannot be selected in the Data spread options window and the spreading method cannot be applied using data spread keyboard shortcuts.

Important: This parameter disables data spreading only in a cube view or in a single cell widget in Planning Analytics Workspace. If Planning Analytics for Microsoft Excel is also available in your local environment, these settings have no impact on data spreading in Planning Analytics for Microsoft Excel.

Set the parameter to one of the following valid values:

Repeat
RepeatLeaves
EqualLeaves
StraightLine

If you specify multiple data spreading methods, separate each method by a comma and enclose the entire parameter value string in quotation marks. For example,

DISABLED_SPREAD_OPTIONS="Repeat,RepeatLeaves,EqualLeaves,StraightLine"

ENABLE_AUDIT_LOGGING

Set to TRUE to enable audit logging for Planning Analytics Workspace. When enabled, user activity is tracked and recorded in an audit log file.

The audit log records actions such as creating or editing books, changing security access, and performing administrative tasks. This provides visibility into how users interact with Planning Analytics Workspace, separate from TM1® database audit logging.

The audit log file is stored locally under log/wa-proxy/audit.log.

Default value: False

AUDIT_LOG_EVENT_CONFIG

Use this parameter to control which audit events are written to the log by disabling specific event types. This parameter is only used when ENABLE_AUDIT_LOGGING is set to TRUE.

Specify event types to disable as a comma-separated list. For example, to disable book creation and security change events, set the parameter as follows:

AUDIT_LOG_EVENT_CONFIG="book.create,security.change"

Default value: Empty (all event types are logged)

ENABLE_EMAIL

Set this property to true to enable the email service in Planning Analytics Workspace Local. Either EMAIL_SMTP_URL or SENDGRID_API_KEY parameter must also be specified. If both parameters are specified, EMAIL_SMTP_URL is used.

Default value: False

EMAIL_SMTP_URL

Use this parameter to enable the SMTP email service. The parameter specifies the SMTP server URL. The following are examples of such URLs:

smtp://username:password@smtp.example.com:587

smtp://username:password@smtp.example.com:587?secure=false

smtps://username:password@smtp.example.com:465

If you specify this parameter, the SENDGRID_API_KEY parameter is not used even if it is specified.

Default value: Empty (no URL is specified)

SENDGRID_API_KEY

Use this parameter to enable the SendGrid email service. The parameter specifies the API key for the SendGrid email account.

Note: You might need to contact the email administrator for your organization to obtain the API key that is specific to your email service.

If you specify this parameter, specify also EMAIL_FROM, but don't specify EMAIL_SMTP_URL.

Default value: Empty (no API key is specified)

EMAIL_FROM

Specifies the sender address if the email server requires it. This parameter is mandatory when SENDGRID_API_KEY is specified.

EnableIPv6

Flag to enable IPV6 on the bridge network.

Default is FALSE.

ENABLE_MULTI_ENV

Set to TRUE to enable multiple environments (multi-tenancy).

When is parameter is set to TRUE, the ENABLE_USER_IMPORT parameter is ignored and the behavior in all environments is the same as if ENABLE_USER_IMPORT=FALSE.

ENABLE_PASTE_SPECIAL

Set to TRUE to enable mixed cell paste. For more information, see Paste values to a mixed range of leaves and consolidated cells.

Default is FALSE.

EnableSSL

Set to TRUE if you are using SSL. Default is FALSE. Keep all other SSL options at default values if you want to run by using a self-signed test certificate.

ENABLE_VIEW_EXCHANGE

Set to TRUE to enable Exploration View exchanges between Planning Analytics Workspace and Planning Analytics for Microsoft Excel in the Content Store.

For more information, see Save to the Planning Analytics Workspace Content Store.

Note: If you are using Planning Analytics for Microsoft Excel 2.0.43 or earlier, setting this parameter to true prevents Planning Analytics for Microsoft Excel from connecting to TM1 and authentication servers with security modes 2 or 3 enabled.

FREE_SPACE_REQUIRED_GB

Indicates how much free space is required (in GB) before you are notified that it might be insufficient.

Set to "0" to suppress warning messages.

Default is "50".

If free space is less than this value, the script warns you but continues to load images because it is difficult to know how much space is required for the images. This check is done outside of the main container host validation because it is related to image loading instead, and it is not controlled by the $env:VALIDATE_HOST setting.

LOG_DIR

Host directory for storing service logs. Make sure that services can create directories here. Value is log.

PAGatewayHTTPPort

HTTP port that is mapped to the host by pa-gateway. The value is 80.

PAGatewayHTTPSPort

HTTPS port that is mapped to the host by pa-gateway. The value is 443.

PAW_NET

Name of the PAW bridge network. Value is paw_net.

PAW_V6_SUBNET

IPV6 subnet for Docker containers. Value is fdfb:297:e511:0:d0c::/80.

ProxyTimeoutSeconds

Maximum number of seconds the gateway waits for a backend service response. Value is 120.

ServerName

Domain name that is used to access Planning Analytics Workspace. This value is used by the gateway as the redirect target for non-SSL requests. The value is pa-gateway.

SessionTimeout

The amount of time a Planning Analytics Workspace login session can go unused before it is no longer valid. Specify a positive integer followed by a unit of time, which can be hours (h), minutes (m), or seconds (s).

For example, specify 30 seconds as 30s. You can include multiple values in a single entry. For example, 1m30s is equivalent to 90 seconds.

The default value is 60 minutes.

For example, SessionTimeout="60m".

SslCertificateFile

Path to a PEM-encoded file that contains the private key, server certificate, and optionally, the entire certificate Trust Chain. Value is config/ssl/pa-workspace.pem on Microsoft Windows Server 2016 OS or config/pa-workspace.pem on Linux OS.

TM1CredentialStoreKeyFile

Path to and name of the random credential store key, which is generated during the first time that you start Planning Analytics Workspace. The value is config/credential_store.key.

VALIDATE_HOST

Indicates whether to perform host validation and repair.

Set to "true" to validate until Start.ps1 is successful and then don't validate when Start.ps1 is run again. The default is "true".

Set to "always" to always validate.

Set to "false" to never validate.

Host validation runs as the first step of executing the Start.ps1 script. Successful validation is marked by writing the config/HostValidated file with the current time stamp. If $env:VALIDATE_HOST is true, validation is skipped if the confing/HostValidated file exists. If you are upgrading, validation is performed because that file is absent in the new kit.

VALIDATE_ANTI_VIRUS

Indicates whether to check for unsupported anti-virus software while validating the host. If anti-virus software is found, the validation process fails.

Set to "true" to check for anti-virus software. The default is "true".

Set to "false" to skip checks for anti-virus software.

X_FRAME_OPTIONS

This parameter enables the X-Frame-Options header as an alternative to Content-Security-Policy (CSP) frame-ancestors for browsers that don't support CSP (Internet Explorer). The default is sameorigin.

For more information, see X-Frame-Options.

You configure the following values as part of the Planning Analytics Workspace installation process by using the Planning Analytics Workspace administration tool. After the initial installation, you can change these values. Modify the paw.ps1 or paw.env file in a text editor.

After configuration

After you configure authentication and other parameters, you can configure the TM1 12 connection for each environment. For more information, see Connecting to the TM1 12 instance.