Install the Payee Web Classic application

You'll use Apache Tomcat to install and configure the Payee Web Classic application. If you want to use the newest version of Sales Portal, skip this section and proceed to Install the Sales Portal application.

After you have deployed the WAR file, you can skip these instructions:

Setting the tenant service location for Apache Tomcat
Configuring access to your model for the Sales Portal

Then you can proceed with SSO configuration or Salesforce integration, if you want to use these features.

Deployment of the Sales Portal with Apache Tomcat

You can use Apache Tomcat version 7 or 8 to deploy the Incentives Sales Portal.

Deploying the Sales Portal on Apache Tomcat

You can use Apache Tomcat Manager to deploy the Sales Portal.

Make sure you have Java and Apache Tomcat installed.

Open Apache Tomcat Manager by going to http://localhost:8080.
Tip
By default, Apache Tomcat runs on port 8080, but if you specified a different port number during the installation of Tomcat, use that port number instead.
Click the Tomcat Manager link and log in with the user name and password that you specified during the Tomcat installation.
In the Deploy section, click Browse.
Find the WAR file and click Deploy.
By default, WAR files can only be a maximum of 50MB. Since Sales Portal Classic is 100MB, you will need to edit the server.xml config file of your Tomcat App manager to allow for the larger WAR file upload.
Important
The payeeweb.war file must be deployed with the name payeeweb.
When you are performing an upgrade, you must uninstall the current WAR file before deploying the new one since a unique name is required for the file.
Click the link to the Incentives Sales Portal to verify deployment.

Setting the tenant service location for Apache Tomcat

After the Sales Portal is deployed in Tomcat, the security.properties file must be edited.

Navigate to the following location:
C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\Incentives\WEB-INF
Open the security.properties file with a text editor like WordPad.
Important
Do not use Notepad because it cannot read .properties files.
In the JWT Configuration section, set the information for the location of the tenant services.

Set the following secret keys to match the values configured in the tenant services configuration file.

Note

These keys must be at least 43 characters to satisfy the length requirement.

Key name	Description
`secretkey`	This must match the `VARICENT_WEB_KEY` that you set in the tenant services configuration file.
`tenantSecretKey`	This must match the `TENANT_KEY` that you set in the tenant services configuration file.

Save the updated security.properties file.
Tip
Save a copy of the file in another location to use for reference when the application is redeployed, such as when you upgrade to a newer version.
Reboot your system to commit the edited keys.
Open Tomcat Manager and click the Reload link to propagate the changes.

Configuring access to your model for the Sales Portal

To access your Incentives on premise model from the Sales Portal, you must configure some parameters.

After the Sales Portal is deployed in Tomcat, the jdbc.properties file must be edited.

Navigate to the following location:
C:\Program Files\Apache Software Foundation\Tomcat 7.0\webapps\Incentives\WEB-INF
Open the jdbc.properties file with a text editor such as WordPad.
Enable these fields by removing the pound (#) signs:
```
jdbc.tenant=single 
jdbc.model=
```
Update these fields in the jdbc.properties file:
Important
In the jdbc.properties file, the build will contain jdbc.onprem=false. To set up Sales Portal, update this line to jdbc.onprem=true.
1. Update the jdbc.model field to include the name of your SQL model.
2. Update jdbc.ProductName= to either sqlserver or sqlserverunicode.
  Tip
  You can check which of the two values you need in the PostgreSQL models table or by checking the databaseType in the defaults.json file for the server where your model is located.
3. Update the jdbc.url= field to include your SQL server.
  If you have one SQL instance, use this format: jdbc:jtds:sqlserver://<your SQL Server name or IP address>:1433/<Database name>
  If you have more than one SQL instance, use this format: jdbc.url=jdbc:jtds:sqlserver://<your SQL Server name or IP address>:1433/<Database name>;instance=<SQL instance name>
4. Update the jdbc.username= field to include the SQL user who has access to the SQL model.
  Tip
  If you are using default settings, the username is usually sa.
5. Update the jdbc.password= to include the password of the SQL user who has access to the SQL model.
Save the updated jdbc.properties file.
Tip
Save a copy of the file in another location to use for reference when the application is redeployed, such as when you upgrade to a newer version.
Open Tomcat Manager and click the Reload link to propagate the changes.
Click the link to the Incentives Sales Portal.

You can now continue with SSO configuration or Integration with Salesforce.com.

SSO configuration

Incentives natively supports authentication by using any SAML 2 compliant identity provider.

These steps use the OpenAM sign-on solution as an example. The steps should be similar with other SAML2-compliant identity providers.

Browse to the Incentives Sales Portal.
The client is evaluated.
Incentives redirects the browser to SSO URL.
The web browser redirects to the SSO URL.
SAML response is generated by the client network SSO provider.
Client returns encoded SAML response to browser.
Browser returns encoded SAML response to Incentives.
SAML response is verified by Incentives.
User is logged in to the Sales Portal.

Service provider configuration

To deploy the Sales Portal as a SAML service provider, you must configure Apache Tomcat and the Incentives.

Before the Sales Portal can be deployed as a SAML service provider (SP), these three things must be obtained from the identity provider (IDP):

IDP SAML meta data file (usually idp.xml)
SSL keystore file (usually keystore.jks)
Signing key credentials in keystore (alias and password)

Begin by deploying the Incentives.war file in the web application server.

Endorsed libraries

The Incentives Sales Portal's SAML implementation requires the use of more advanced XML components than what is available in the standard library.

To use these components, the Virtual Machine needs to be configured. The platform allows users to override standard libraries through the Endorsed Standards Override Mechanism, where the required libraries are copied into a special, endorsed folder.

Apache Tomcat configuration

During setup of SSO authentication with the Incentives Sales Portal, the deployed endorsed folder must be copied to a new folder named common in the main Apache Tomcat folder.

In the main Apache Tomcat folder, create a new folder called common.
Copy the deployed <Tomcat Path>/webapps/Incentives/WEB-INF/ endorsed folder to the main Apache Tomcat folder, so that the endorsed files are in <Tomcat Path>/common/endorsed.
Restart the Apache Tomcat service.

Configuring SSO

For SSO to work, you must configure some settings first.

The keytool is bundled with a JRE and OpenSSL comes from the OpenSSL tool. You must extract the certificate and key file from keystore.jks.

keytool -importkeystore -srckeystore keystore.jks -destkeystore keystore.p12
-deststoretype PKCS12 -srcalias <jkskeyalias> -deststorepass <password>
-destkeypass <password>

openssl pkcs12 -in keystore.p12  -nokeys -out cert.pem

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

Generating a SAML 2.0 integration certificate using OpenSSL

For the Incentives admin web application to communicate with the SSO IdP, you must generate an SSO certificate. The certificate lets the SSO IdP know that the admin web application is certified.

Install OPENSSL.
Make a new directory on your computer, such as C:/Users/Administrator/Desktop/SSOCerKey
Open the Command Prompt, and run the following command:
Note
Type this as a single command, no new lines. You may need to change your directory to where the OpenSSL executable is found, change the command to write to the directory of your choice, and change the command based on your operating system. The following command is for Windows.
```
openssl.exe req -x509 -newkey rsa:2048 -keyout
C:/Users/Administrator/Desktop/SSOCerKey/key.pem -out 
C:/Users/Administrator/Desktop/SSOCerKey/cert.pem -days 365
```
In the same command line window, change the current directory to where your key.pem and cert.pem files were generated.
Decrypt the key.pem file by running the following command:
openssl rsa -in C:/Users/Administrator/Desktop/SSOCerKey/key.pem –out C:/Users/Administrator/Desktop/SSOCerKey/keyDecrypted.pem
Copy your cert.pem file, paste it and rename it as cert.cer.
This allows you to open the file in a browser to review the expiry date of the certificate. Note this date, it will be required later.
Open the decrypted key file, keyDecrypted.pem, using a text editor.

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

Making a REST API call to create an SSO configuration entry

Make a REST API call to create an SSO configuration entry:

Important

The Tenant Services path must include the port. Ensure the Tenant Services instance and the call use the same number.

Path: <TenantServices Path>/services/sso/configs/<model_id>
 Method: POST
Content-Type: application/json
Body: {    
  idp_options: {        
     sso_login_url: <sso_login_url>,  
     sso_logout_url: <sso_logout_url>,        
     certificates: [<certificates>],        
     force_authn: true/false,      
     sign_get_request: true/false,        
     allow_unencrypted_assertion: true/false    
  },    
  sp_options: {        
    entity_id: "https://<server name>/Incentives",            
    assert_endpoint: "https://<server name>/Incentives/acs.html",        
    nameid_format: <nameid_format> 
},
    sp_cert_key_id: "value",
    nameid_column: <column_name>,
   "nameid_format": <nameid_format>,
   "is_sso_enabled": true/false,
   "allow_native_login": true/false,
   "ignore_signature": true/false 
  }
}

sso_login_url,, sso_logout_url, certificates

These parameters are from the idp.xml file.

key.pem, cert.pem

These parameters are created in step 1.

nameid_format

This parameter must be in one of the following formats:

"urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
"urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName",
"urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName",
"urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos",
"urn:oasis:names:tc:SAML:2.0:nameid-format:entity",
"urn:oasis:names:tc:SAML:2.0:nameid-format:persistent",
"urn:oasis:names:tc:SAML:2.0:nameid-format:transient"

POST http://www.abc.com:9101/services/sso/configs/0
{
   "idp_options":{  
      "sso_login_url":"http://zeusv.canlab.ibm.com:8088/OpenAM/SSORedirect
       /metaAlias/idp",
      "sso_logout_url":"http://zeusv.canlab.ibm.com:8088/OpenAM/IDPSloRedirect
       /metaAlias/idp",
      "certificates":[  
         "MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBg
          NVBAgTCkNh\nbGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEw
          NTdW4xEDAOBgNVBAsTB09w\nZW5TU08xDTALBgNVBAMTBHRlc3QwHhcNMDgwMTE1MT
          kxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw\nCQYDVQQGEwJVUzETMBEGA1UECBMKQ2
          FsaWZvcm5pYTEUMBIGA1UEBxMLU2FudGEgQ2xhcmExDDAK\nBgNVBAoTA1N1bjEQMA
          4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B\nAQEFAA
          OBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U
          5Of+\nRkDsaN/igkAvV1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIh
          URebGEmxKW9qJNY\nJs0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATANBg
          kqhkiG9w0BAQQFAAOBgQB3Pw/U\nQzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcN
          SZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAdiDA\ncGy/F2Zuj8XJJpuQRSE6PtQqBuDE
          HjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC\n/FfwWigmrW0Y0Q=="
      ],
      "force_authn":false,
      "sign_get_request":true,
      "allow_unencrypted_assertion":true
   },
   "sp_options":{  
      "entity_id":"http://openam.example.com:8080/payeeweber",
      "assert_endpoint":"http://openam.example.com:8080/payeeweber/acs.html",
      "nameid_format":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
   },
   "sp_cert_key_id":"1",
   "nameid_column":"Email_",
   "nameid_format":"urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress",
   "is_sso_enabled":"true",
   "allow_native_login":false,
   "ignore_signature":true
}

Make a REST API call to download sp metadata from tenant services:

Path:<TenantServices Path>/services/sso/configs/<model_id>/metadata 
Method: GET
Content-Type: application/xml

Registering Varicent Incentives as the service provider

You must set Incentives as the service provider.

From the Common Tasks tab, under the Create SAMLv2 Providers heading, click Register Remote Service Provider.
Select File option → Upload to upload the sp metadata file.
Make sure it is added to the existing circle of trust, such as Incentives, that was created when the IDP was configured (this option is typically selected by default).
Add the same attribute mapped in the IDP configuration (this is usually the mail attribute).

Verifying the Varicent Incentives login

You can make sure that the Incentives Sales Portal is configured properly by navigating to Sales Portal login page.

Navigate to http://<server name>/Incentives.
The browser should automatically be redirected to the SSO login screen.
Log in.
Once a user has been successfully authenticated by SSO, the browser redirects to the Incentives Sales Portal home page.
Important
The signed-in user can log out of the Incentives Sales Portal, but will not be logged out of single sign-on (SSO) until they log out of the IDP. This means that logging out of the Sales Portal and immediately returning to any view will automatically log the user back in.

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 Payee Web Classic application

Deployment of the Sales Portal with Apache Tomcat

Deploying the Sales Portal on Apache Tomcat

Tip

Important

Setting the tenant service location for Apache Tomcat

Important

Note

Tip

Configuring access to your model for the Sales Portal

Important

Tip

Tip

Tip

SSO configuration

Service provider configuration

Endorsed libraries

Apache Tomcat configuration

Configuring SSO

Generating a SAML 2.0 integration certificate using OpenSSL

Note

Uploading the SAML 2.0 certificate

Making a REST API call to create an SSO configuration entry

Important

Registering Varicent Incentives as the service provider

Verifying the Varicent Incentives login

Important

Integration with Salesforce.com

Configuring the Sales Portal for Salesforce.com

Accessing the Sales Portal from Salesforce.com

Web client appearance

Search results