Demand Planning (DEMAND)¶

This document describes how to set up your Demand Plan Server, Client and how to prepare your system to support a successful installation.

Installation Location¶

Demand Plan Server

The installation can be found on the IFS build home structure. For example ..\BuildHome\artifact\demand\ifs-demand-server.zip. For IFS internal access it could be found in the Jfrog repository.

Prerequisites for Demand Plan Server¶

The Demand Plan/IPR Server (DP Server) cannot be containerized and it must run on a MS Windows environment.

Certain systems and configurations must exist on your system prior to installation of IFS Demand Planning. Demand Planning Setup does not install or configure an IFS Cloud database.

1. The database that Demand Planning will run against must already be set up and your site with data (transaction and inventory parts) must exist in the database.

2. Install Oracle Client software if this is not already installed. Configure a SQL*Net connection to the database you want to connect your Demand Planning Server. This must be done only on the computer where the Demand Plan Server is to be installed.

3. You can run the Demand Plan Server with the Appowner user, or you can use the Demand Plan Server User (DemandServer). Make sure that the user is granted access to all tables and views needed. In order to do this, either you can use the scripts included in DEMAND (POST_Demand_DemandServerUser.sql) or you can use the schedule task "Set Demand Plan Server User Grants". If you are using the Demand Plan Server User ensure the user is in the Active state.

There are 2 ways to install the DP Server on a computer, manually or with a PowerShell script. Update/Patching can also be done either manually or through a PowerShell script.

Manual Installation/Manual Update/Patching Demand Plan Server¶

Manual Installation¶

The manual installation is started with running the SetupForecastServer.exe. Then follow the steps in the installer to complete the installation, 2 important steps in the installation have been mentioned below.

Add General Information

In this screen you will add the Name of the Company, the Environment (prod/test….)

The Company and Environment settings is the text that will be shown in the "http://<DP_SERVER:PORT>/metrics" web page

demand_server_status{ifsrole="dm", customercode=“IFS", environmenttype="prd", ifsversion="2020.1", buildversion=”20.1.3.23”, demandrole=’demand’} 1

Add Database Information

In the above screens you need to specify the database connection information.

Connection - This is the connection string to the database from the TNSNames.ora file

Application Owner - The Application owner user

User Name - The database user that the DP server should use for its database operations. Normally the Demand Planner service user or appowner user.

Password - The password for the database login for the user.

Follow the remaining steps in the installer to complete the installation.

Note:- A service will be automatically registered on the machine where the installation has been done.

Manual upgrade Demand Plan Server¶

An upgrade can be done by running the SetupForecastServer.exe of the newer version. Simply follow the installation steps.

Manual uninstall Demand Plan Server¶

The Demand Plan Server Installation can be removed by running the unistall.exe file which can be found in the installation location of the Demand Plan Server

PowerShell Script Installation Demand Plan Server¶

To be able to run the script you must open the PowerShell window in administrator mode and navigate into the folder which contains the dmsetup.ps1 script. You can use the below command to navigate to the correct folder.

*cd <path to folder which contains the dmsetup.ps1>Ex: - cd C:\Projects\demand\tools\DemandSetupScript*

Prerequisites¶

Make sure the below steps are followed before starting the installation.

Locate the path to SetupForecastServer.exe. Standard release package(zip) contains this in the default location (parent folder of the DemandSetupScript folder). Note If the server setup file is on a different location use "-path" parameter to specify the location during the installation. Use "-action help" command to see more details on this.
Locate the path to settings.json file and modify this file so that the Database connection related Information and environment information are updated. (Refer how to edit settings.json file section below in this guide). Note you can use an already existing settings.json file for this as well use "-configPath" for this.
Open the PowerShell in administrator mode and move to the directory where the dmsetup.ps1 script file is located.

How to edit the settings.json file¶

The figure below shows a section of the settings.json file

{

"Category" : "Database",

"Setting" : "Appowner",

"Value" : "<APPOWNER_USER>",

"DataType" : "TEXT"

},

The only parameter that can be changed is the “Value” parameter. The Other parameters should not be modified under any circumstance as it will result in crashing of the Demand Plan Server.

The values for “Category”, “Database” ** is a must and values for “Category” ,“Metric”,** used to indicate environment information. Under general configuration both these categories will hold values for their settings.

Below shows a summary on the general categories and their settings.

· “Category”: “Database” and “Setting”: “Connection” [Database Connection, host/sid or TNS name]

· “Category”: “Database” and “Setting”: “AppOwner” [Database Application Owner name]

· “Category”: “Database” and “Setting”: “UserName” [Database Username]

· “Category”: “Database” and “Setting”: “PlainTextPassword” [Database Password. Note: ** Always change this entry when you want to change the database user password. Once entered, during the start of Demand Plan Server the value of this field will be taken out and cleared. Before clearing, the entered password will be encrypted and stored on a different field name EncryptPassword. The value of "EncryptedPassword"** should not be modified manually ]

· “Category”: “Metric” and “Setting”: “customercode” [Customer code to identify the customer]

· “Category”: “Metric” and “Setting”: “environmenttype” [Customer Environment type to identify the environment of the customer, Ex:- prod, dev..]

· “Category”: “Communication” and “Setting”: “OverwriteServer”

[This value is used to set the publicly accessible Host Name URL/IP for the server so that any client which communicates with the Demand Plan Server will communicate using this Server URL. This needs to be used in a situation where the internal Host Name URL/IP is not accessible from client environments, which is the typical scenario when hosting the Demand Plan server on the cloud. Note This entry will not be there in the setting.json by default. But, once the server starts with general configuration, the entry will be automatically added to the settings.json by the Demand Plan Server which can be modified afterwards.]

Example of a settings.json file and the text to change between quotes in "Value" parameter ( ) are shown below. The text entered should be surrounded quotes.

{
"settings":[
{
"Category" : "Metric",
"Setting" : "customercode",
"Value" : "<CUSTOMER_ID_OR_NAME>",
"DataType" : "STR"
},
{
"Category" : "Metric",
"Setting" : "environmenttype",
"Value" : "<CUSTOMER_ENVIRONMENT_TYPE>",
"DataType" : "STR"
},
{
"Category" : "Database",
"Setting" : "Appowner",
"Value" : "<APPLICATION_OWNER_NAME>",
"DataType" : "TEXT"
},
{
"Category" : "Database",
"Setting" : "Connection",
"Value" : "<DATABASE_HOST/SID_OR_TNS_NAME>",
"DataType" : "TEXT"
},
{
"Category" : "Database",
"Setting" : "UserName",
"Value" : "<DATABASE_USER_NAME>",
"DataType" : "TEXT"
},
{
"Category" : "Database",
"Setting" : "PlainTextPassword",
"Value" : "<DATABASE_USER_PASSWORD>",
"DataType" : "TEXT"
}
]
}

You can also change the Settings.json file with the usage of the PowerShell script commands, see below for details.

Script Installation Demand Plan Server¶

Once you have the PowerShell opened in the directory which has the dmsetup.ps1, you can execute one of the following commands to Install the Demand Plan Server.

1. ./dmsetup -action Install [This will install the Demand Plan Server, the SetupForecastServer.exe should be in the parent directory of the directory in which dmsetup.ps1 is located and the settings.json should be located in the same directory as the dmsetup.ps1. Eg: If dmsetup.ps1 & settings.json is in ‘C:\IFS\Demand\tools\DemandSetupScript\’, then SetupForecastServer.exe is in ‘C:\IFS\Demand\tools\’. Standard IFS release package zip contains this structure ]

2. ./dmsetup -action Install -path <folder path to exe> [This will install the Demand Plan Server and the SetupForecastServer.exe should be in the folder provided in the path parameter. settings.json should be located in the same directory as the dmsetup.ps1]

3. ./dmsetup -action Install -path "<folder path to exe>" -configPath [This will install the Demand Plan Server and the SetupForecastServer.exe should be located in the folder path provided to the path parameter and settings.json should be located in the folder path provided to the configPath parameter]

4. ./dmsetup -action Install -customerCode <Customer code to identify the customer> -environmenttype <Customer Environment type to identify the environment of the customer> -Appowner <Database Appowner> -Connection <Database Connection> -UserName <Database Username> -Password <Database Password> [ This will install the Demand Plan Server after updating the Settings.json file in the default location(if not specified with -configPath) with the values given with the command. If no values are given, the Settings.json file will not be changed. It is possible to provide values only for the parameters that need to be updated and the rest of the parameters will remain unchanged.]

Note: - The paths should be provided to the folder level. All paths must have " around them like "C\TEMP" Ex: - ./dmsetup -action Install -path "C:\Projects\demand\ForecastServer" -configPath "C:\Projects\demand\ForecastServer\config"

The command implies that the SetupForecastServer.exe is in the path C:\Projects\demand\ForecastServer and settings.json is in the path C:\Projects\demand\ForecastServer\config

Script Update¶

Once you have the PowerShell opened in the directory which has the dmsetup.ps1, you can execute one of the following commands to Update the Demand Plan Server. NOTE: If you do not use the -force option (see below) remember that the Demand Plan Server service must be stopped before the update.

1. ./dmsetup -action Update [This will update the Demand Plan Server, the SetupForecastServer.exe should be in the parent directory of the directory in which dmsetup.ps1 is located. Eg: If dmsetup.ps1 is in ‘C:\IFS\Demand\tools\DemandSetupScript\’, then SetupForecastServer.exe is in ‘C:\IFS\Demand\tools\’]

2. ./dmsetup -action Update -path <folder path to exe> [This will update the Demand Plan Server and the SetupForecastServer.exe should be in the folder provided to the path parameter.]

3. ./dmsetup -action CopyConfig -customerCode <Customer code to identify the customer> -environmenttype <Customer Environment type to identify the environment of the customer> -Appowner <Database Appowner> -Connection <Database Connection> -UserName <Database Username> -Password <Database Password> [This will update and overwrite the existing setting in the Settings.json file with the new setting, you can provide as many of the settings as you need in the command.]

Note: - The paths should be provided to the folder level.Ex: - ./dmsetup -action Update -path "C:\Projects\demand\ForecastServer"

The command implies that the SetupForecastServer.exe is in the path C:\Projects\demand\ForecastServer -action Update -Force can be used to immediately take down the Demand Planner service and begin the update. If -action Update is used and Demand Planner Service is running, the action will not get executed. Once this command is successfully executed the demand plan server will be updated and the service will be running. -path should be used if the SetupForecastServer.exe in not in the default location.

Script Uninstall Demand Plan Server¶

Once you have the PowerShell opened in the directory which has the dmsetup.ps1, you can execute one of the following commands to UnInstall the Demand Plan Server.

1. ./dmsetup -action UnInstall [This will Uninstall the Demand Plan Server, but the SetupForecastServer.exe should be in the parent directory of the directory in which dmsetup1.ps1 is located. Eg: If dmsetup.ps1 is in ‘C:\IFS\Demand\tools\DemandSetupScript\’, then SetupForecastServer.exe is in ‘C:\IFS\Demand\tools\’]]

2. ./dmsetup -action UnInstall -path "<folder path to exe>" [This will Uninstall the Demand Plan Server and the SetupForecastServer.exe should be in the folder provided to the path parameter.]

Note:- The paths should be provided the folder level.Ex: - ./dmsetup -action UnInstall -path "C:\Projects\demand\ForecastServer"

The command implies that the SetupForecastServer.exe is in the path C:\Projects\demand\ForecastServer

-action Uninstall-Force can be used to immediately take down the Demand Planner service and begin uninstallation. If -action Uninstall is used and Demand Planner Service is running, the action will not get executed. Once this command is successfully executed the demand plan server will be uninstalled.

-path should be used if the SetupForecastServer.exe in not in the default location.

Script Command Summary¶

All Commands which can be executed in the script is listed below:

Command	Description
-action Install	Install the Demand Plan Server, -path parameter can be provided if the SetupForecastServer.exe is in a different path
-action UnInstall	Uninstall the Demand Plan Server, make sure the Demand Plan Service has been stopped before running the command
-action UnInstall-Force	Uninstall the Demand Plan Server, Automatically Stops the Service and uninstalls the Demand Plan Server
-action Update	Update the Demand Plan Server, make sure the Demand Plan Service has been stopped before running the command. -path parameter can be provided if the SetupForecastServer.exe is in a different path
-action Update-Force	Update the Demand Plan Server, Automatically Stops the Service and updates the Demand Plan Server.
-action Start	Start the Demand Plan Service. Make sure the settings.json file has been updated with the database connection information.
-action Stop	Stop the Demand Plan Service.
-action Restart	Restart the Demand Plan Service.
-action Help	View the help guide.
-action CopyConfig	Update/overwrites the existing setting.json file. Can provide any/all of the parameters -customerCode -environmenttype -Appowner -Connection -UserName -Password depending on which parameters in the settings.json file needs to be updated.
-action Manage-User	Unlock or reset password of the Oracle user. Can reset the user with the -ResetPassword flag or can unlock the user with the -UnlockUser flag. Make sure to provide all parameters for -Appowner -Connection -UserName -Password.

· -path Optional parameter to define the path to the SetupForecastServer.exe file

when running -action Install, -action Update, -action UnInstall commands.

· -configPath Optional parameter to define the path to the setting.json file when running -action Install command.

· -ResetPassword Optional parameter to reset the password of the oracle user when running -action Manage-User command.

· -UnlockUser Optional parameter to unlock the Oracle user when running -action Manage-User command.

Historical Data Files¶

The daily aggregated demand will be stored in data files for fast access. They will be stored in AppData\Roaming\ForecastServer\Historical path on Windows OS. Note: In some cases these get stored on windows installation drive Windows\System32\config\systemprofile\AppData\Roaming\ForecastServer\Historical otherwise those should be in Users\XXX\AppData\Roaming..

Demand Plan Server Metrics URL¶

Following URL can be used to check the status of the Demand Plan Server once it is setup. Replace the DP_SERVER accordingly(Host/IP where the Demand Server is installed) to get a valid URL.

http://DP_SERVER:PORT/metrics

demand_server_status 0 indicates an error 1 indicates OK status.

demand_server_status{ifsrole="dm", customercode="rusta", environmenttype="prd", ifsversion="2020.1", buildversion=”6.0.3.23”, demandrole=’demand’} 1

demand_server_job_engine 0 indicates an error, 1 if it is idle, above 1 would be the job id currently under execution by the server.

demand_server_job_engine{ifsrole="dm", customercode="rusta", environmenttype="prd", ifsversion="2020.1", buildversion=”6.0.3.23”} 1

demand_server_writeback_engine o indicate an error, 1 if it is under sleep mode, 2 if it is idle, 3 if its excuting a job.

demand_server_writeback_engine{ifsrole="dm", customercode="rusta", environmenttype="prd", ifsversion="2020.1", buildversion=”6.0.3.23”} 2

In general, after a successful installation the metrics URL should produce a reponse like below,

demand_server_status{ifsrole="dm", customercode="rusta", environmenttype="prd", ifsversion="2020.1", buildversion=”6.0.3.23”, demandrole=’demand’} 1
demand_server_job_engine{ifsrole="dm", customercode="rusta", environmenttype="prd", ifsversion="2020.1", buildversion=”6.0.3.23”} 1
demand_server_writeback_engine{ifsrole="dm", customercode="rusta", environmenttype="prd", ifsversion="2020.1", buildversion=”6.0.3.23”} 2

Demand Release Artifacts and Versioning¶

Following versioning practice will be followed for Demand Plan artifact releases. Version will be increased only when the corresponding artifact has a change during a service update. The version will be changed to denote the latest service update the artifact got changed. Note that demand server Installation package version last digit denotes the last service update where the powershell script got changed.

IFS Cloud Version	21.1E.0.0	21.1E.1.0	21.1.0.0	21.1.1.0	21.1.2.0	21.1.2.0	21.1.2.0	21.2E.0.0
Demand Server Fix Exists			Y		Y	Y	Y
Demand Server Version	21.1E.0.0	21.1E.0.0	21.1.0.0	21.1.0.0	21.1.2.0	21.1.2.1	21.1.2.2	21.2E.0.0
Powershell Installer Fix Exists				Y			Y
Powershell Installer Version	21.1E.0.0	21.1E.0.0	21.1E.0.0	21.1.1.0	21.1.1.0	21.1.1.0	21.1.2.0	21.2E.0.0
Demand Server Installation package version	ifs-demand-server-21.1E.0.0.zip	ifs-demand-server-21.1E.0.0.zip	ifs-demand-server-21.1.0.0.zip	ifs-demand-server-21.1.0.1.zip	ifs-demand-server-21.1.2.1.zip	ifs-demand-server-21.1.2A.1.zip	ifs-demand-server-21.1.2B.2.zip	ifs-demand-server-21.2E.0.0.zip
Demand Client Fix Exists				Y
Demand Client Version	21.1E.0.0	21.1E.0.0	21.1E.0.0	21.1.1.0	21.1.1.0	21.1.1.0	21.1.1.0	21.2E.0.0
Demand Middletier Fix Exists		Y		Y
Demand middle tier version	21.1E.0.0	21.1E.1.0	21.1E.1.0	21.1.1.0	21.1.1.0	21.1.1.0	21.1.1.0	21.2E.0.0

Technical Notes¶

Update the Demand Plan Server Software

Updates of the Demand Plan Server, like installing new versions/service updates. It's important to do this when the Demand Plan Server is idle (not running any jobs like create forecast, refresh IPR data etc. ) to avoid loss of data. The Demand Plan Server writeback buffer should also be empty. Suitable time for doing updates will vary depending on how the Demand Planning is configured, but a general rule will be to avoid the first date of a month and 1 day of the week (Sunday & Mondays), and working hours is normally better than at night, since most Demand Plan Server jobs are scheduled at non working hours.

Demand Plan Server Port Configuration:

Demand Plan Server uses a specific port for the communication with Demand Plan Clients. When it comes to container configurations, both application services container and Odata container needs to have this specific port open for Demand Plan Server to facilitate server communication. This default port number can be found/changed in the settings.json file in the Demand Plan Server installation ("Category" : "Communication","Setting" : "Lisener"...). If changed then above container ports also needs to get changed correspondingly with the new port number.

How to verify Demand Server Installation and IFS Cloud Web Communication¶

**Verify the Demand Server Installation in the Host ** Once the demand plan server is started http://localhost:PORT/metrics should produce a success response in the host. Check for Demand Server Matrix URL section to verify the expected results.

**Verify the Demand Server Communication with Middletier ** Demand Server uses both Odata and Appsvc containers for the communication. CURL command issued against "CURL http://DPSERVER:PORT/metrics" from each(or atleast one) of this container should produce a success response. Check for Demand Server Matrix URL section to verify the expected results. Note that the Demand Server should be up and running on the host for this check.

Verify the Demand Server Host Visibility in Middletier This step is useful if the matrix end point( http://DPSERVER:PORT/metrics ) is not reachable from the containers mentioned in above step. This could be mostly due to a host name resolving failure. If the host name is not resolving from the middiletier container, follow these steps to register the IP address,

Shutdown the Demand Plan Server
Add the IP address of the Demand Plan Server host to, settings.json, OverwriteServer VALUE.
Start the Demand Server
Verify the Demand Server Visibility/Communication with Middletier again using the IP address (http://DPSERVER_IP:PORT/metrics)

Permission Sets¶

Following are the permission sets available for demand planning.

Permission Set	Description
DEMAND_SUPER	This permission set has access to everything, the only user that can execute manual jobs in the Demand Plan Server from the Dashboard. Only user to create new user and edit access rights for the main Demand Plan Client.
DEMAND_GENERAL	The permission set has access to everything apart from the basic data set up. The user will be able to add and delete new forecast parts, publish forecast parts to DEMAND_FORECAST users, look at the finished forecasts. The user cannot create/delete/edit base or combined flows or do anything to the Demand Plan Server Setup but can view the Dashboard without being able to execute any jobs on the Demand Plan Server
DEMAND_FORECAST	This permission set has access only to the Demand Forecast Client. Will only be able to look, and evaluate the forecast published to the user in the Demand Forecast Client.
IPR_SUPER	This is a permission set has access to everything IPR related. Like the IPR Supply Plan, Manage IPR Supply Plan, Analyze Demand Derivation, Refresh Inventory Part Unit Cost Snapshot, IPR Planning Details for Inventory Parts, Planning Hierarchy Basic Data, the IPR Excel Sheet menu on Inventory Part Planning.

Manual Actions¶

This section contains information related to manual actions for IFS Demand Planner that might be needed to be executed during an upgrade or installation.

Action Description	Functional Conditions for Execution	Technical Dependencies	Consequences (of not executing)	Steps	Step execution
To run the Demand Plan Server, the Demand Planner service user should be in Active & Unlocked state. Therefore, use this manual action to set the Demand Planner service user as an Active user or to change the password or to unlock the Demand Planner service user.	Only applicable if Demand Server is used and Demand Planner service user is Locked or Inactive.	No	If Demand Planner service user is locked or inactive then this user cannot be used to run Demand Plan Server.	Use the Demand Powershell Setup Scripts to alter and unlock the Demand Planner service user in the database. Replace the <XXX> with the respective values. "./dmsetup -action Manage-User -ResetPassword -UnlockUser -username -password <New Password> -appowner <Database Appowner> -appownerpwd <Database Appowner Password> -connection <Database Connection>"	Post - Anytime