Install the Sales Portal application

You'll use an Apache HTTP server to deploy Sales Portal.

Deploying the Sales Portal 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 Sales Portal. 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.
Restart Apache Web Service.

Setting up HTTPS for Sales Portal

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 Sales Portal.

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 Sales Portal 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 Sales Portal URL can direct to a blank page if the paths in index.html are not set correctly.

Symptoms

The Sales Portal 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 Incentives 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 Sales Portal 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 Sales Portal</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 Sales Portal 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 Sales Portal

To deploy SSO on Sales Portal, 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",
"enable_msal_mobile":false,
"msal_id":null,
"is_sso_enabled": "true/false",
"allow_native_login": true/false,
"ignore_signature": true/false
}

Name	Description
entity_id_new	The unique entity ID for Sales Portal. 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 Sales Portal, followed by the endpoint `'/services/saml/acs/payeeweb'`. The frontend URL should match the `hostname` column that was configured in the Sales Portal 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 Sales Portal, 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 Sales Portal

Type the URL for Sales Portal 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 Sales Portal home page. You should see reports if you've set up web tabs in Portal Access.

Integration with Salesforce.com

The Varicent Incentives Sales Portal can be configured to integrate with, and be accessible through, Salesforce.com.

Configuring the Sales Portal for Salesforce.com

After you install the Varicent Incentives Sales Portal, the web.xml web configuration file must be modified so that the Sales Portal is accessible through Salesforce.com. The Incentives Sales Portal must be deployed first.

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

Accessing the Sales Portal from Salesforce.com

You can make the Incentives Sales Portal 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 Sales Portal 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 Incentives 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 Incentives Sales Portal.
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 Incentives 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 Incentives 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 Incentives Sales Portal.
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_540}&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 Incentives 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 Incentives 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 Incentives Sales Portal is now accessible from the newly created tab. When you click the tab, you are logged into the Sales Portal 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 Sales Portal is configured in the Portal Access module in the Incentives client.

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

Install the Sales Portal application

Deploying the Sales Portal application on Apache HTTP server

Tip

Tip

Setting up HTTPS for Sales Portal

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 Sales Portal

Creating key.pem and cert.pem

Uploading the SAML 2.0 certificate

Note

Important

Logging in to Sales Portal

Tip

Tip

Integration with Salesforce.com

Configuring the Sales Portal for Salesforce.com

Accessing the Sales Portal from Salesforce.com

Web client appearance

Search results