Installation of the Payee Web (V2) application

Varicent Sales Performance Management Documentation

Installation of the Payee Web (V2) application

You'll use an Apache HTTP server to deploy Payee Web.

Deploying the Payee Web application on Apache HTTP server

In Postman, make a call to update the hostname column in the payeeweb table:

Request POST /admin/models/:modelID/payeeweb
Sample Call Path: http://localhost:9101/services/admin/models/:modelID/payeeweb
Method POST
Body:{   
    "hostname": "PAYEEWEB_HOSTNAME"
}

Tip

If you get an error here, read Could not add payeeweb hostname to this model for troubleshooting tips.

In Postman, make a call to update new_payeeweb in the models table:

Request PATCH /admin/tenants/:tenantID/models/:modelID/newPayeewebStatus
Sample Call Path: http://localhost:9101/services/admin/tenants/:tenantID/models/:modelID/newPayeewebStatus
Method Patch 
Body:{   
    "new_payeeweb": true
}

Go to the location of the Apache htdocs folder and create a new folder for Payee Web. In examples, we'll call the folder payeewebv2 .
Tip
By default, htdocs is located here: C:\Program Files\Apache Software Foundation\Apache2.2.34\htdocs.

Open the httpd.conf file and find the directory section that starts with <Directory “c:/Program Files/Apache2.2.34/Apache2/htdocs"> and edit the section so it looks like this:

#Alias "/payeewebv2" PATH_TO_PAYEEWEBV2_FOLDER 
Alias "/payeewebv2" "c:/Program Files/Apache2.2.34/Apache2/htdocs/payeewebv2"
    <Directory "c:/Program Files/Apache2.2.34/Apache2/htdocs/payeewebv2">
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        Allow from all#
        Require all granted
        DirectoryIndex index.html
        FallbackResource /payeewebv2/index.html
    </Directory>

Save the httpd.conf file.
If you are not using the ConfigSetter tool, follow these steps to configure the Payee Web application:
1. Open the index.html in the Payee Web folder you created in step 3. For example, ours is located here: C:\Program Files\Apache Software Foundation\Apache2.2.34\htdocs\payeewebv2.
2. Change the API_URL value to the location of the REST API. Change localhost to the IP or hostname of the machine.
  It will look something like this when you're done:
```
API_URL: http://hostname:8080
```
3. Change the AUTH_URL value to the location of tenant services. Change localhost to the IP or hostname of the machine.
  It will look something like this when you're done:
```
AUTH_URL: http://hostname:9100
```
4. Save the file.
Restart Apache Web Service.

Setting up HTTPS for Payee Web

Make sure that you have already set up HTTPS for the REST API.
Navigate to the following location:
C:\Program Files\Apache Software Foundation\Apache2.2.16\conf
Open the httpd.conf file.

In the VirtualHost *:443 section, add the following lines within the tags:

#Alias "/payeewebv2" PATH_TO_PAYEEWEBV2_FOLDER
Alias "/payeewebv2" "c:/Program Files/Apache2.2.34/Apache2/htdocs/payeewebv2"
<Directory "c:/Program Files/Apache2.2.34/Apache2/htdocs/payeewebv2">
Options Indexes FollowSymLinks MultiViews
AllowOverride None
Order allow,deny
Allow from all#
Require all granted
DirectoryIndex index.html
FallbackResource /payeewebv2/index.html
</Directory>

Restart the Apache Web Service.

Troubleshooting installation

Troubleshoot installation problems with Version 2 of the web client.

Could not add payeeweb hostname to this model

Symptoms

This error occurs after making a Postman call to update the payeeweb_hostname column in the models table:

{
Message: “Could not add payeeweb hostname to this model”
}

Causes

This error can occur if the Payee Web application has the same hostname setup for a different model.

Diagnosing the problem

Check the models table in PostgreSQL for the payeeweb_hostnamecitext column. Remove the hostname for the unintended model or give it a new name.

URL directs to a blank page

The Payee Web Version 2 URL can direct to a blank page if the paths in index.html are not set correctly.

Symptoms

The Payee Web Version 2 URL directs to a blank page.

Causes

The path was not set correctly in the index.html file.

Diagnosing the problem

Go to http://{{payeeweb_v1_host}}/payeewebv2.
Open the developer tools for your web browser and go to the Network tab.
Check the path for each of the network calls.

All static files should come from the path you set in index.html. The default is http://{{payeeweb_v1_host}}/payeewebv2/dist/.

Resolving the problem

Review the index.html file and ensure that all paths are set correctly. Review the steps in Configuring access to your model if needed:

Configuring access to your model

To access your Varicent SPM on-premise model, you must configure some parameters.

You must edit the index.html file to point to your Apache configuration.

Extract and deploy the web client file onprem.tar.gz

Open the index.html in a text editor. This example shows the default configuration:

<html>
	<head>
		<meta http-equiv="X-UA-Compatible" content="IE=edge" />
		<meta charset="utf-8" />
		<title>ICM Payee Web</title>
		<meta name="description" content="" />
		<meta name="viewport" content="width=device-width, initial-scale=1" />
		<link
			rel="icon"
			type="image/png"
			href="/dist/favicon2.png"
		/>
		<script>
			window.PAYEE_WEB_CONFIG = {
				API_URL:
					'https://localhost',
				AUTH_URL:
					'https://localhost',
				CDN_SERVER: '/dist/',
				BASE_ROUTE: '/payeewebv2',
				JAVAWEB_ROOT: '/payeeweb',
				ENABLE_LOCALE_MESSAGE_FALLBACK:
					'true' ===
					'true',
				LOCAL_TENANT: '',
				LOCAL_DATABASE: '',
				ENABLE_LOGGING: 'false' === 'true'
			};
		</script>

		
		<link rel="stylesheet" href="/dist/app.482ed7aaac0b45896526.bundle.css" />
		
	</head>

	<body style="overflow: hidden" class="cap--type-body">
		<div id="root"></div>
	</body>

	
	<script
		type="text/javascript"
		src="/dist/vendor.cd62c9bac9e65b2b42ce.js"
	></script>
	
	<script
		type="text/javascript"
		src="/dist/runtime.482ed7aaac0b45896526.bundle.js"
	></script>
	
	<script
		type="text/javascript"
		src="/dist/app.482ed7aaac0b45896526.bundle.js"
	></script>
	
</html>

Replace all paths to point to your deployed web client in the Apache HTTP server configuration.
For example, paths that include the directory dist are the location of static files in the installation package.

Deployment of SSO for Payee Web

To deploy SSO on Payee Web, you must generate an SSO certificate.

Creating key.pem and cert.pem

The keytool is bundled with a JRE. OpenSSL comes from the OpenSSL tool.

Go to C:\Program Files\Java\jdk1.8.0_221\bin and enter this command to generate a keystore file:
```
Keytool.exe -genkeypair -alias test -keyalg RSA -keystore keystore.jks
```

Run this command to extract a p12 file from the keystore:

Keytool.exe -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12 -deststoretype PKCS12 -srcalias test -deststorepass changeit -destkeypass changeit

Change the directory to C:\Program Files\OpenSSL\bin and enter this command to get a certificate:
```
openssl pkcs12 -in keystore.p12 -nokeys -out cert.pem
```
When prompted to enter a password, enter your -deststorepass password. If you entered the command exactly as in step 2, it's changeit.

Run this command to get a key:

openssl pkcs12 -in keystore.p12 -nodes -nocerts -out key.pem

When prompted to enter a password, enter your -deststorepass password. If you entered the command exactly as in step 2, it's changeit.

Uploading the SAML 2.0 certificate

After creating a certificate, you'll upload it to PostgreSQL using the REST API.

Create and run this REST API call in Postman:

yourServer/services/sso/certs/sp/new
Sample Path: http://localhost:9101/services/sso/certs/sp/new
Method: POST
Body: 
{
"cert_name": "aUniqueCertificateName",
"certificate": "yourCertificateValueNoHeaders",
"private_key": "yourDecryptedPrivateKeyWithHeaders",
"certificate_expiry": "YYYY-MM-DD"
}

Name	Description
cert_name	This can be any value as long as it is unique within the database and model.
certificate	Open the `cert.pem` file and copy the lines between the `BEGIN CERTIFICATE` and `END CERTIFICATE` header and footer. Paste these lines and add `\n` at the end of every line.
private_key	Open the `key.pem` file and copy all of the content, including the `BEGIN/END RSA PRIVATE KEY` header and footers. Paste these lines and add `\n` at the end of every line except after the `END RSA PRIVATE KEY` footer. Then remove all new line characters so that you have 1 string on 1 line.
certificate_expiry	This is the expiry date from `cert.pem`. To find yours, copy the `cert.pem` file. Paste it and rename it `cert.cer`. Now you can open the certificate. You can find the expiry date in the General tab under the Valid From section.

If you need information from certificates that are already in the sso_certificate_key, you can use this call:

GET http://server name:9101/services/sso/certs/sp/all

Use this call to create an SSO configuration entry for the model on tenant services:

Path: <TenantServices Path>/services/sso/configs/<model_id>

Body:
{
"idp_options": {
"sso_login_url": "sso_login_url",
"sso_logout_url": "sso_logout_url",
"certificates": ["yourIDPCert"],
"force_authn": true/false,
"sign_get_request": true/false,
"allow_unencrypted_assertion": true/false
},

"sp_options": {
"entity_id_new": "https://<server name>/payeewebv2",
"entity_id": "https://<server name>/payeeweb", 
"assert_endpoint_new": "https://<server name>/services/saml/acs/payeeweb",
"assert_endpoint": "https://<server name>/payeeweb/acs.html", 
"nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
},
"sp_cert_key_id": "",
"nameid_column": "Email_",
"nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",

"is_sso_enabled": "true/false",
"allow_native_login": true/false,
"ignore_signature": true/false
}

Name	Description
entity_id_new	The unique entity ID for Payee Web. It must also match the same value in IdP setup.
entity_id	The unique entity ID for Payee Web Classic. It must also match the same value in IdP setup.
assert_endpoint_new	The <server name> is the frontend URL to Payee Web, followed by the endpoint `'/services/saml/acs/payeeweb'`. The frontend URL should match the `hostname` column that was configured in the Payee Web table in the `postgres` database. Don't include any alias following the <server name>. Don't include HTTPS if the `hostname` is configured with HTTP only.
assert_endpoint_new	The <server name> is the frontend URL to Payee Web Classic, followed by the endpoint `'/payeeweb/acs.html'`. Don't include HTTPS if the `hostname` is configured with HTTP only.

Note

If you're not using either Payee Web Classic or Payee Web, fill in the attributes with dummy values. This is needed for the API call syntax.

If you use HTTPS in your frontend URL, there is some further configuration needed for the Tenant services default.json file so that the '/sso_redirect' call can succeed. In default.json, change the payeeweb.port and payeeweb.protocol as follows:

"Payeeweb": {
"port": "443",
"protocol": "https",
"path": {
"sso_redirect": "/payeewebv2/sso_redirect"
}

Important

This step is required to prevent an SSO-enabled login loop for Payee Web.

Use this call to download sp metadata from tenant services:

Path: <TenantServices Path>/services/sso/configs/<model_id>/metadata?isNew=true
Method: GET
Content-Type: application/xml
Sample Path: http://localhost:9101/services/sso/configs/1/metadata?isNew=true

Logging in to Payee Web

Type the URL for Payee Web into your web browser. The format for the URL is the hostname or IP of the application server followed by the port for Apache HTTPD and ending with /payeewebv2.
```
http://hostname:80/payeewebv2
```
Tip
If you get a blank page here, read URL directs to a blank page for troubleshooting tips.
Log in using credentials for a payee who is web-enabled.
Tip
You can enable a payee in Portal Access by going to the Groups tab, selecting a group and then clicking the Manage Web Access button. Select the Web Enabled checkbox. You can also reset their password from this window.

If successful, you should see the Payee Web home page. You should see reports if you've set up web tabs in Portal Access.

Integration with Salesforce.com

The Varicent Sales Performance Management (SPM) web client can be configured to integrate with, and be accessible through, Salesforce.com.

Configuring the web client for Salesforce.com

After you install the Varicent Sales Performance Management (SPM) web client, the web.xml web configuration file must be modified so that the web client is accessible through Salesforce.com. The Varicent SPM web client must be deployed first.

Navigate to the web.xml file found, by default, in the following location: ...\webapps\Varicent SPM\WEB-INF.
In the Parameters section, change security.xml to security-salesforce-composite.xml.
After you save the file, restart the Varicent SPM web client for the changes to take effect.

Accessing the web client from Salesforce.com

You can make the Varicent SPM web client accessible from a tab within Salesforce.

You must have a model created. In your model, you must create a payee that has the same email address as the user logging into Salesforce.com. That payee must be added to a workflow group and enabled for web access. The web client must also be deployed.

Log in to Salesforce.com with a user ID that has administrative rights.
Click your user-name to access the drop-down menu, and select Setup.
From the App Setup section, click Create → Tabs.
Click New in the Web Tabs section.
This allows you to create a custom tab that displays Varicent SPM content inside the Salesforce.com window.
You can select one of the following options:
Option
Description
Full page width
Uses the full page width to display the Varicent SPM web client.
2 columns with Salesforce sidebar
This option displays the Salesforce.com sidebar.
Click Next after you have made your selection.
Define the content and display properties for the Varicent SPM tab by completing the following steps:
1. In the Tab Content Definition section, select URL from the Tab Type menu.
2. In the Tab Label field, enter the text that you want displayed on the label.
3. In the Tab Name field, give the tab a unique name. This can be the same as the tab label.
4. Choose the color of your tab by selecting a Tab Style from the styles screen.
5. The Content Frame Height field allows you to indicate how tall (in pixels) the Varicent SPM content frame will be.
  Specify a frame height of at least 800 pixels.

Option	Description
Full page width	Uses the full page width to display the Varicent SPM web client.
2 columns with Salesforce sidebar	This option displays the Salesforce.com sidebar.

In the URL field, paste this string, replacing the parameters as needed:

http://localhost:8080/payeeweb/sforce_composite_login?SessionId={!API.Session_ID}&ServerURL={!API.Partner_Server_URL_100}&Tenant=TENANTNAME&Model=MODELNAME

Parameter	Description
`http://localhost:8080/payeeweb`	This is the URL of your web application. For example, `https://tenant-model-trunk.spm.ibmcloud.com/payeeweb`
`TENANTNAME`	This is the name of your tenant. If you are using Varicent SPM on Cloud, contact IBM support for the name of your tenant.
`MODELNAME`	This is the name of your model.

Parameter

Description

http://localhost:8080/payeeweb

This is the URL of your web application.

For example, https://tenant-model-trunk.spm.ibmcloud.com/payeeweb

TENANTNAME

This is the name of your tenant.

If you are using Varicent SPM on Cloud, contact IBM support for the name of your tenant.

MODELNAME

This is the name of your model.

Set the encoding to Unicode (UTF-8).
Click Save.

The Varicent SPM web client is now accessible from the newly created tab. When you click the tab, you are logged into the web client as the user with the same email address as the Salesforce.com user using SSO.

Web client appearance

The way web tabs are displayed to different web users in the web client is configured in the Portal Access module in the Varicent SPM client.

For more information, read the Portal Access section of the User Guide.

In this section:

Was this helpful?

Would you like to provide feedback? Just click here to suggest edits.

Varicent Sales Performance Management Documentation

Installation of the Payee Web (V2) application

Deploying the Payee Web application on Apache HTTP server

Tip

Tip

Setting up HTTPS for Payee Web

Troubleshooting installation

Could not add payeeweb hostname to this model

Symptoms

Causes

Diagnosing the problem

URL directs to a blank page

Configuring access to your model

Deployment of SSO for Payee Web

Creating key.pem and cert.pem

Uploading the SAML 2.0 certificate

Note

Important

Logging in to Payee Web

Tip

Tip

Integration with Salesforce.com

Configuring the web client for Salesforce.com

Accessing the web client from Salesforce.com

Web client appearance

Search results