Configure parameters

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

Note: When you change a paw configuration file, you must run ./scripts/paw for your operating system or click Start in the Planning Analytics Workspace administration tool for your changes to take effect. Only services that are affected by the configuration change will restart.
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.
The following list describes the parameters in defaults.env and defaults.ps1.
AdminAgentAPIKey
When a request is sent from Planning Analytics Workspace to a local agent, an authentication token is also sent. This token is created using a key that must be set to the same value in both the bootstrap.properties file for the local agent and Planning Analytics Workspace Local configuration file.
Set AdminAgentAPIKey to match the AGENT_API_KEY plain text property value in bootstrap.properties, as described in Set an agent API key.
ADMINTOOL_PORT
In IBM® Planning Analytics Workspace Local version 2.0.44 or later, you can access the Planning Analytics Workspace administration tool remotely on Windows Server by specifying the ADMINTOOL_PORT environment variable in the config/paw.ps1 file.
For example:
$env:ADMINTOOL_PORT="8888"
This configuration parameter applies to Planning Analytics Workspace Local installed on a Windows Server only.
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.
Valid parameter values are :
  • Repeat
  • RepeatLeaves
  • EqualLeaves
  • StraightLine

If specifying multiple data spreading methods, separate each method by a comma.

DISABLED_SPREAD_OPTIONS="Repeat,RepeatLeaves,EqualLeaves,StraightLine"

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: 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 is not used, even if it's specified.
Default: 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: empty (no API key is specified)
EMAIL_FROM
Specifies the sender address if it is required by the email server. This parameter is mandatory when SENDGRID_API_KEY is specified.
EnableIPv6
Set to FALSE to disable the natural language search on the intent bar. You might want to set this parameter to false to avoid long running search processes that are created with the intent bar.
Default is True.
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. Leave all other SSL options at default values if you want to run by using a self-signed test certificate.
ENABLE_USER_IMPORT
Default is TRUE. However, when ENABLE_MULTI_ENV=TRUE, this parameter is ignored and the behavior in all environments is the same as if ENABLE_USER_IMPORT=FALSE.
If set to TRUE, when a user logs in, they are immediately added as a user in Planning Analytics Workspace. When this parameter is set to true, you cannot activate, deactivate, or delete users from the Administer page of Planning Analytics Workspace.
If set to FALSE, a user must first be added to Planning Analytics Workspace before they can log in to Planning Analytics Workspace. If a user has not been added and tries to log in, they see an error message. Users are added by an administrator. For more information, see Add users.
When this parameter is set to FALSE, an administrator can activate, deactivate, and delete users. For more information, see Activate or deactivate a user and Delete a user.
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 version 2.0.43 or earlier, setting this parameter to true will prevent Planning Analytics for Microsoft Excel from connecting to TM1® and authentication servers with security modes 2 or 3 enabled.
ENABLE_WATSONX_ASSISTANT
Set to TRUE to enable the Planning Analytics AI assistant. When this parameter is enabled, you must also set the WATSONX_ASSISTANT_CONFIG parameter.
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. Ensure that services can create directories here. Value is log.
PA_KUBE_USE_POD_DISRUPTION_POLICIES
Set this property to true to enable PodDistruptionBudgets. If this property is not present in the configuration file, the default is false.
PAGatewayHTTPPort
HTTP port that is mapped to the host by pa-gateway. Value is 80.
PAGatewayHTTPSPort
HTTPS port that is mapped to the host by pa-gateway. 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.
REGISTRY
Docker registry. Value is pa-docker:5000/planninganalytics.
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. 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.
Default is 60 minutes.
For example, export 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.
TM1APIPort
Port for the TM1 Admin Host. The value is empty, which means to use the default port.
TM1CredentialStoreKeyFile
Path to and name of the random credential store key, which is generated the first time that you start Planning Analytics Workspace. 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.
VIRTUAL_BOX_AS_SERVICE
If you are running the VM as a service using VBoxVmService, set this parameter to true to suppress scripts from probing or starting the VM by using VirtualBox tools. Value is false.
WATSONX_ASSISTANT_CONFIG
This parameter must be set when ENABLE_WATSONX_ASSISTANT=TRUE.
Set this parameter to the licensing value that is provided when you purchase the Planning Analytics AI assistant. For example, WATSONX_ASSISTANT_CONFIG=license_value
.
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.

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 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 by modifying the paw.ps1 or paw.env file in a text editor or through the Planning Analytics Workspace administration tool. For more information about the Planning Analytics Workspace administration tool, see Connect to TM1 and authentication servers.
CAMLoginNamespace
IBM Cognos Analytics CAM authentication namespace ID. Specify only when PAAuthMode = cam.
IBMCognosGateway
Gateway URI of the IBM Cognos Analytics server. Specify only when PAAuthMode = cam. To enable SSO for Planning Analytics Workspace, you must enter a value in this field.
IBMCognosServlet
Dispatcher URI of your IBM Cognos Analytics server. Specify only when PAAuthMode = cam.
PAAuthMode
Supported authentication modes. Value must be cam for IBM Cognos Analytics security authentication or tm1 for standard TM1 authentication.
TM1ApplicationsLocation
URI of the TM1 Application Server. Value is http://tm1appshost:9510.
TM1Location
URI of the TM1 Admin Host. Value is https://tm1adminhost:5898.
TM1LoginServerURL
URI of the TM1 server to be used for Planning Analytics Workspace authentication. Specify only when PAAuthMode = tm1.