Skip to main content

Optional and Advanced Settings

In this section, you can find information about installing and configuring optional features and advanced settings.

Command-line interface

Incentives CLI is a command-line interface that can be used to complete various actions in the model.

Installing the command-line interface

Before you can use the Incentives command-line interface (CLI), you must install the CLI application.

  1. If you are not using the new installer (available in Version 10.1.1.102.0 and higher), you must install the application before you can set the timeout value:

    1. Double-click the Incentives-cli.exe installation file in your release folder.

    2. Complete the steps in the installation wizard.

  2. Open the IBM Cognos Incentives CLI.exe.config file and set the timeout value to a large value.

    For example, set the timeout value to 90000000.

  3. Save the file.

SAML 2.0 integration for Varicent Incentives on Premise

The on Premise (Incentives) admin web application supports SAML 2.0 integration.

Requirements for SAML 2.0 integration

Before integrating Incentives and SAML 2.0, you must have this set-up in place:

  • Tenant services and the admin web application must run on the same domain and port. This means they're running on the same server and same hosting port.

  • It is recommended that tenant services, the REST API, and the admin web application are all hosted on the same server as well.

  • You've already completed a successful installation of the web application, meaning you can successfully log in to Incentives.

SAML 2.0 configuration

There are three files in Incentives that you must configure correctly for SAML 2.0 integration.

Tenant services

Configure the default.json file as per the instruction outlined in the Tenant services section.

REST API

In the RESTAPI.appSettings.config file, make sure that the TenantService value is set to 9101. For example, configure the following key:

<add key="TenantServices" value="http://yourServer:9101/services" />

Configure the other fields as per the instructions in the REST API section.

Admin web application

In the index.html file, configure the API_URL and AUTH_URL as follows:

API_URL: 'http://yourServer:8080', 
AUTH_URL: 'http://yourServer:9100'

All other fields remain the same. For more information on configuring the admin web application, see Admin Web Installation.

All other components

Follow the previous instructions in this guide. No changes required.

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.

  1. Install OPENSSL.

  2. Make a new directory on your computer, such as C:/Users/Administrator/Desktop/SSOCerKey

  3. 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

  4. In the same command line window, change the current directory to where your key.pem and cert.pem files were generated.

  5. 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

  6. 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.

  7. Open the decrypted key file, keyDecrypted.pem, using a text editor.

Upload the SAML 2.0 certificate

After creating the SAML 2.0 certificate, you must upload it to Postgres using the REST API.

To upload the SAML 2.0 certificates, in an application such as Postman, perform the following REST API call:

POST yourServer/services/sso/certs/sp/new

Body:

 
{ 
"cert_name": "aUniqueCertificateName", 
"certificate": "yourCertificateValueNoHeaders", 
"private_key": "yourDecryptedPrivateKeyWithHeaders", 
"certificate_expiry": "YYYY-MM-DD" 
}

Notes

  • cert_name: 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. Do not include the BEGIN CERTIFICATE and END CERTIFICATE lines. Paste these lines and add a \n (see example below) at the end of every line, then remove all new line characters, so that you have one long string on one line.

  • private_key: open the keyDecrypted.pem file and copy all of the content, including the BEGIN/END RSA PRIVATE KEY header and footers. Paste these lines and add a \n (see example below) at the end of every line except after the END RSA PRIVATE KEY footer, then remove all new line characters, so that you have one long string on one line.

Sample body

{"cert_name": "myNewCert",
  "certificate": "\nMIICsDCCAZgCCQCmhR6tkSBYeTANBgkqhkiG9w0BAQsFADAaMQswCQ\nYDVQQGEwJjYTELMAkGA1UECAwCb24
wHhcNMTgwODEzMTUzMzI4WhcN\nMTkwODEzMTUzMzI4WjAaMQswCQYDVQQGEwJjYTELMAkGA1UECAwCb24wggEiMA0GC\nSqGSIb3DQEB
AQUAA4IBDwAwggEKAoIBAQCdKfslziLODmyreA/W7EgN0cIzy4oM1tcVd46+SjA\nyGy1TfYYRLWfgaogUPkB+RNPPyrTg7xhA1HQ4F
hi6OH8UUZiS/Kaj0+q0/dH\nfEc2MS/PyhN41E/XaZvLnzn5onTIlUs2DxLTINSDV57i7MrRNcoKD+t8p\n2eFttc0tn8bkjA57R5TU8g
f4fW+Wi2uaQhkIZAieZUnYybWIfnjQn\nTM1qNoKCzQ3ZQl3luaaVYn0IkzdwG1QNjmEIdcjKZytDPfnL\nSpkJSe0WurZV2IMBqCJaLd
jlzE6anQDLi53qlnLUHf1i26cI/SLOHezgVR54zu\ntK2MpftxUMdfMILuMUyLbAgMBAAEwDQYJKoZIhvcNAQELBQADggEBAHp2Hw3N
1sNFcGK\nAjulxdHTE7xC2MP7kDBE8vaA98UkYWhj3ifRAOEc9E2+tZooow7nMSGxzPS7V9\n4KoF9s9RBhZCjOiynPfIOOhMEEWQzhdv
dp8nAU/yXOVLAaOxPu66TSX\n14yP5ui1SwBNUa2L/96/U4nqGdOT5367d4qF4TchWPwEURH5+m22kwja\njxpozvkx4lH4FaKW+GEsSRC
rPHpTLroATuKt28Plt\ncOcK8MFYQI7heEXCqQwkj6pYiAowhr4rAQDMhFDfhbBDS+XKoewxesG1QqHRt3QSeE6vqatt2hK7txtMx2XB
Obq8vlDaI6QNW9+Ca6e0seWrTvv4eE
",
  "private_key": "-----BEGIN RSA PRIVATE KEY-----
\nMIIEowIBAAKCAQEAnSn7Jc4izg5sq3gP1uxIDdHCM8uKDNbXFXeOvkowMhstU32G\nES1n4GqIFD5AfkTTz8q04O8YQNR0OBYYujh
/FFGYkvymo9PqtP3R3xHNjEvz8oTe\nNRP12mby585+aJ0yJVLNg8S0yDUg1ee4uzK0TXKCg/rfKdnhbbXNLZ/G5IwOe0eU\n1PIH+H1
vlotrmkIZCGQInmVJ2Mm1iH540J0zNajaCgs0N2UJd5bmmlWJ9CJM3cBt\nUDY5hCHXIymcrQz35y0qZCUntFrq2VdiDAagiWi3Y5cxO
mp0Ay4ud6pZy1B39Ytu\nnCP0izh3s4FUeeM7rStjKX7cVDHXzCC7jFMi2wIDAQABAoIBAFSFWECbnFIupbiN\naA9QoOt1rDhItSR0gd
VUp9qkcUjxHq4w6mHghmXFRQuF8w81Gqg8PoxdaTCsURg8\noe28JnOZ8jDSWRfwBuBxRGXv4BgcXMRHOm1XH7fl96o8ffTq3SX/YvEDX
6nwEImZ\nBdr+yMKB27j4uP175GUpCYAI1mDgLb4848QTTudjnzctCdhwN915UqgM4ILJdInF\nk4O5DENvqcEJijrg4bWS6yKTWJ5DLP
J0koozwDzkF18aTm800iW0zEeEAmj4VTvZ\n6TWkfNA0N2IlMF6Mxxktx1ggIoxJW9Zz2ET8XRx9t6ghjSABYb/KENHip3I4TLWx\n8XMX
4jkCgYEAzBHxcQJvSGBZaXJr98s3bcUgkJtDMOww26qg8caj9txRqjbKUIrn\nA6yRPVYcd+PyEJSiFU7hnSACAvuIQb+HmLsPihl+XV5P
z5QNmKSRez3WgobOtkN0\nKKbmQ3FANgoyt4Sxe05LCu5vxRKvpHzgtYW1uTLI2Lg9LG5iShWJO1UCgYEAxShc\nQ1L4r2CSUn0VagV867
TMCtcKTFoQjNnKKxic0rS6z5CjaKKkabSlalqvbUt+9ISq\n71rsRo/GdRqfsfn3+qKcpjk7UFMw0vgRzLgxZXDeYZaMewZSvR7tcrbPol
TPzLA4\nTfXYm1XbkwpkRsBki8R9Q6pvJG0lC1/Yd5KCxW8CgYAe9roDw7LO8I+giFQJjTQj\n271NM8HGMpBXRFSXWuSWGGfrw9R+1BSp
Yg3HmMFJD7Uy/tp5ETb6eFjVywSptT4F\n1pxNAAFEeYLypCxL9Ox+Hqvlsj67ORDu+iQGJ7Dugi2f2upzIzYPuo4LAQLVmn0e\nDeO87g
+7knj1vOn9A7eG4QKBgHqJ7FZX0oNGVYt5fP7JbGwfkhZGs3rjG5g/oP0K\nLiZz+AwcTMQzGlcs1Qb2WERpAP4/GvLroyD0KZgNNSZsQ+
l+ejiCJ9Bz9EubrYx9\nCw6OiVlENgoc0v4Co/iBkSnG5uTEvioOXFOnmHKaqdqjp5qLRIPzAWM1hym7p5Ih\n+K93AoGBAL3QcOfxno0c
TcmfcYWGzk+kC+CSDrgOxK3AiXDaFl3PkL/KHpyAp9Wb\ny7088irT9LkqjKYOP/YlDa6ArkHU6W+JUz+ekP+h087bChA58q2YseI+EtXx
yil4\nSyqlVwwvyxeDOTceMAaQ04w+HEc20ptuZeAoiAs/XXm4JfFhCMOD-----END RSA PRIVATE KEY-----
",
  "certificate_expiry": "2021-08-20"
}

Create the SAML 2.0 integration configuration for the admin web application

After uploading the SAML 2.0 certificate to Postgres, create the SAML 2.0 integration configuration for the admin web application.

To create the SAML 2.0 integration configuration for the admin web application, perform the following REST API call:

POST yourServer/services/ssoAdminweb/configs/1

Body:

 
{
  "tenant_id": "1”,
  “tenant_name”: “single”,
  “sso_login_url”: “ssoIdpLoginUrl”,
  “sso_logout_url”: “ssoIdpLogoutUrl”,
  “sp_url”: “yourICM10serverdomain:adminWebUIport",
  "force_authn": false,
  "sign_get_request": "false",
  "ignore_signature": false,
  "allow_unencrypted_assertion": true,
  "certificate": [
    "spCertAsInStep2"
  ],
  "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "is_sso_enabled": "true",
  "sp_options": {
    "entity_id": " yourICM10serverdomain ",
    "assert_endpoint": "serverdomain:adminWebUIport/services/saml/acs",
    "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  },
  "idp_options": {
    "sso_login_url": "ssoidploginurl",
    "sso_logout_url": "ssoidplogouturl",
    "certificates": [
      " yourIDPCert"
    ],
    "force_authn": false,
    "sign_get_request": true,
    "allow_unencrypted_assertion": true
  },
  "sp_cert_key_id": "1"
}

Notes

  • sp_cert_key_id: in the example above this is set to 1, as one certificate has been added. As more certificates are added, the ID will be incremented. The sso_certificate_key table in Postgres has all certificates listed.

  • certificates: use the same format and instructions as in Upload the SAML 2.0 certificate.

  • idp_options.certificates: this certificate is different than the certificate, spCertAsInStep2, listed on line 12. idp_options.certificates should originate from your identity provider (IdP). It is NOT the OpenAM generated certificate from Generating a SAML 2.0 integration certificate using OpenSSL.

Sample body

{
  "tenant_id": "1",
  "ignore_signature": false,
  "sp_cert_key_id": "1",
  "certificate": [
"MIICsDCCAZgCCQCmhR6tkSBYeTANBgkqhkiG9w0BAQsFADAaMQswCQYDVQQGEwJj\nYTELMAkGA1UECAwCb24wHhcNMTgwODEzMTUz
MzI4WhcNMTkwODEzMTUzMzI4WjAa\nMQswCQYDVQQGEwJjYTELMAkGA1UECAwCb24wggEiMA0GCSqGSIb3DQEBAQUAA4IB\nDwAwggE
KAoIBAQCdKfslziLODmyreA/W7EgN0cIzy4oM1tcVd46+SjAyGy1TfYYR\nLWfgaogUPkB+RNPPyrTg7xhA1HQ4Fhi6OH8UUZiS/Kaj
0+q0/dHfEc2MS/PyhN41\nE/XaZvLnzn5onTIlUs2DxLTINSDV57i7MrRNcoKD+t8p2eFttc0tn8bkjA57R5TU\n8gf4fW+Wi2uaQhk
IZAieZUnYybWIfnjQnTM1qNoKCzQ3ZQl3luaaVYn0IkzdwG1Q\nNjmEIdcjKZytDPfnLSpkJSe0WurZV2IMBqCJaLdjlzE6anQDLi53
qlnLUHf1i26c\nI/SLOHezgVR54zutK2MpftxUMdfMILuMUyLbAgMBAAEwDQYJKoZIhvcNAQELBQAD\nggEBAHp2Hw3N1sNFcGKAjul
xdHTE7xC2MP7kDBE8vaA98UkYWhj3ifRAOEc9E2+t\nZooow7nMSGxzPS7V94KoF9s9RBhZCjOiynPfIOOhMEEWQzhdvdp8nAU/yXOV
LAaO\nxPu66TSX14yP5ui1SwBNUa2L/96/U4nqGdOT5367d4qF4TchWPwEURH5+m22kwja\njxpozvkx4lH4FaKW+GEsSRCrPHpTLro
ATuKt28PltcOcK8MFYQI7heEXCqQwkj6p\nYiAowhr4rAQDMhFDfhbBDS+XKoewxesG1QqHRt3QSeE6vqatt2hK7txtMx2XBObq\n8v
lDaI6QNW9+Ca6e0seWrTvv4eE=
"
  ],
  "tenant_name": "single",
  "sso_login_url": "http://myServer:8085/myIDP/SSORedirect/metaAlias/idp",
  "sso_logout_url": "http://myServer:8085/myIDP/IDPSloRedirect/metaAlias/idp",
  "sp_url": "http://myServer",
  "force_authn": false,
  "sign_get_request": "false",
  "allow_unencrypted_assertion": true,
  "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "is_sso_enabled": "true",
  "sp_options": {
    "entity_id": "http://myServer",
    "assert_endpoint": "http://myServer:90/services/saml/acs",
    "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  },
  "idp_options": {
    "sso_login_url": "http://myServer:8085/myIDP/SSORedirect/metaAlias/idp",
    "sso_logout_url": "http://myServer:8085/myIDP/IDPSloRedirect/metaAlias/idp",
    "certificates": [  "MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh\nb
Glmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w\nZW5TU08xDTALBgNVBAMTBHRlc3
QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw\nCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUMBIGA1U
EBxMLU2FudGEgQ2xhcmExDDAK\nBgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkqhkiG9w0B
\nAQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+\nRkDsaN/igkAvV1cuXEgTL6R
lafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY\nJs0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6ZyL8CAwEAATAN
BgkqhkiG9w0BAQQFAAOBgQB3Pw/U\nQzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT4OFcfu2/PeYoAd
iDA\ncGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC\n/FfwWigmrW0Y0Q=="
    ],
    "force_authn": false,
    "sign_get_request": true,
    "allow_unencrypted_assertion": true
  }
}

Optional

If you would like to bypass the use of a private key, and if you would like your GET requests to not be signed, you can set the sign_get_request value on line 29 to false, "sign_get_request": false. Line 13’s GET request value (“false”) can be ignored.

Configuration note

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

"UI": {
"port": "443",
"protocol": "https",
"path": {
"sso_redirect": "/sso_redirect"
},
"logindelay": {
"delay_min_ms": 50,
"delay_rand_ms": 100

Important

This step is required to prevent an SSO-enabled login loop for the admin web application.

Associate users to the SAML 2.0 configuration

After you create the SAML 2.0 integration configuration for the Incentives admin web application, use the REST API to associate users to the SAML 2.0 configuration.

To associate users to the SAML 2.0 configuration, use this REST API call:

PATCH yourServer/services/admin/1/users/{userid}/sso_nameid

Replace {userid} and sso_nameid with the userID that you want to associate to the SAML 2.0 configuration.

Important

The sso_nameid must match the ID used to identify users in the model.

Body:

 
{"sso_nameid":"sso_nameid"}

Get metadata to upload into SAML 2.0 IdP

After associating users to the SAML 2.0 configuration, use the REST API to get the sp.xml file (Service Provider metadata) from Incentives to upload into the SAML 2.0 IdP.

  1. To get metadata to upload into the SAML 2.0 IdP, perform the following REST API call:

    GET yourServer/services/ssoAdminweb/configs/1/metadata

  2. Save the returned values of this command as sp.xml. Save as an XML file by copying and pasting it into a text editor.

  3. Upload the sp.xml file to your IdP.

Configuring Apache server for virtual hosting

The last step to integrate SAML 2.0 is to configure the Apache server for virtual hosting.

  1. Navigate to your Apache HTTP Server installation directory and open the conf folder.

    For example, C:\Program Files (x86)\Apache Software Foundation\Apache2.2\conf

  2. Open the httpd.conf file using a text editor.

  3. Un-comment the following lines by removing the number symbol (#) at the start of the line.

    The lines should like this when you're done:

    LoadModule proxy_module modules/mod_proxy.so 
LoadModule proxy_connect_module modules/mod_proxy_connect.so 
LoadModule proxy_http_module modules/mod_proxy_http.so

  4. Add the following lines to the httpd.config file and change the lines according to your setup:

    <VirtualHost *:443>
     ServerAdmin “serveradmin“
     DocumentRoot "{ApacheInstallDirectory}\Apache2.4\htdocs"
     ServerName   “severname“
     ErrorLog "{ApacheInstallDirectory}\Apache2.4\error.log"
     CustomLog "{ApacheInstallDirectory}\Apache2.4\access_log.log" hgvhostAccesslog
	 ProxyPass /services /{{your tenant service domain}}:{{Ts domain port}}/services
	 ProxyPassReverse /services /{{your tenant service domain}}:{{Ts domain port}}/services
</VirtualHost>

    Note

    • ServerAdmin: listed in the httpd.conf file (~line 187)

    • ServerName: the fully qualified server name, such as yourServer.ca.varicent.com

    • Ensure that you followed the Install the Payee Web Classic application section, specifically step 5: "Between the <Directory "C:/Program Files/Apache Software Foundation/Apache2.2.16/htdocs"> and </Directory> tags, add the following lines:

      DirectoryIndex index.html
FallbackResource /index.html

    • If you are using SSL or a proxy to re-direct traffic via a VirtualHost, in your httpd – SSL.conf, in your <Directory "${SRVROOT}/htdocs"> section (within a VirtualHost entry), ensure the following entries exist within the Directory tag:

      <Directory "${SRVROOT}/htdocs">
    Options Indexes Includes FollowSymLinks MultiViews
    AllowOverride AuthConfig Limit FileInfo
    Require all granted
    DirectoryIndex index.html
    FallbackResource /index.html
 </Directory>

  5. Restart the Apache server, the Tenant services (node.js), and the REST API.

  6. Access the admin web application.

  7. Enter your userID and click Submit.

    You are redirected to the IdP login page.

  8. Login using IdP. You will be redirected back to the admin web application once authentication is complete.

SAML 2.0 integration with multiple servers

The admin web application supports SAML 2.0 integration when your installation has multiple servers.

Requirements for SAML 2.0 integration with multiple servers

Before integrating Incentives with multiple servers and SAML 2.0, you must have this set-up in place:

  • Tenant services and the admin web application should be installed on the same server (Server 1.

  • The REST API can be installed on a different server (Server 2).

  • You've already completed a successful installation of the web application, meaning you can successfully log in to Incentives.

SAML 2.0 configuration with multiple servers

There are three files in Incentives that you must configure correctly for SAML 2.0 integration with multiple servers.

Tenant services

Follow the Incentives 10 installation and configuration guide.

Configure the default.json file in the following ways:

  • change the UI.hosts.default value to point to server 2

  • change the UI.port value to where the admin web application UI is hosted (the Apache HTTP Server port)

  • change the UI.protocol as needed

    For example,

    "UI" : {
			"hosts": {
				"default":"yourServer2.yourDomain.com"
		},
			"port": 80,
			"protocol": "http",
		"path": {
				"sso_redirect": "/sso_redirect"
		},
			"logindelay": {
				"delay_min_ms": 50,
				"delay_rand_ms": 100
		}
	},

REST API

Configure as per the instructions in the REST API section.

Admin web application

Configure the admin web application as in Admin Web Installation.

Open Apache’s httpd.conf file and add the following lines below the Listen x line, such as Listen 80:

Listen 80

<VirtualHost *:80>
	ServerAdmin  admin@yourServer
	DocumentRoot "C:\Program Files (x86)\Apache Software Foundation\Apache2.2\htdocs"
	ServerName  Server2.ibm.com:80
	ErrorLog  "C:\Program Files (x86)\Apache Software Foundation\Apache2.2\logs\hgvhosterror.log"
	CustomLog  "C:\Program Files (x86)\Apache Software Foundation\Apache2.2\logs\hgvhousterror-access.log" hgvhostAccesslog
	ProxyPass /services http://Server1.youDomain.com:9100/services
	ProxyPassReverse /services http:// Server1. youDomain.com:9100/services
	ProxyPass  /api http://Server1.youDomain.com:8080/api
	ProxyPassReverse /api http:// Server1.youDomain.com:8080/api
</VirtualHost>

Note

DocumentRoot/ErrorLog/CustomLog – update the path to your Apache install location. Ensure that this location exists.

ProxyPass/ProxyPassReverese – this entry points to your server1, where the REST API and Tenant services are hosted.

In the htdocs folder in the Apache HTTP server installation directory, in the index.html file, edit the API_URL value to point to server 2 (the server where the admin web UI is installed). Include the port where the Apache HTTP server is running.

In the index.html file, edit the AUTH_URL to point to server 2 (the server where the admin web UI is installed). Include the port where Apache HTTP server is running.

For example,

<script>
		window.ICM_CONFIG = {
			API_URL: 'http://saltv.canlab.ibm.com:90',
			AUTH_URL: 'http://saltv.canlab.ibm.com:90',

After you save the index.html file, restart the Apache HTTP server.

Create the SAML 2.0 integration configuration for the admin web application with multiple servers

After uploading the SAML 2.0 certificate to Postgres, create the SAML 2.0 integration configuration for the admin web application with multiple servers.

Before completing the following steps, ensure that a certificate already exists and has been uploaded via the POST yourServer/services/sso/certs/sp/new call.

Create the SAML 2.0 integration configuration for the admin web application using the following REST API call:

POST yourServer/services/ssoAdminweb/configs/1

Body

{
  "tenant_id": "1”,
  “tenant_name”: “single”,
  “sso_login_url”: “ssoIdpLoginUrl”,
  “sso_logout_url”: “ssoIdpLogoutUrl”,
  “sp_url”: “yourICM10server2domain:adminWebUIport",
  "force_authn": false,
  "sign_get_request": "false",
  "ignore_signature": false,
  "allow_unencrypted_assertion": true,
  "certificate": [
    "spCertAsInStep2"
  ],
  "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "is_sso_enabled": "true",
  "sp_options": {
    "entity_id": " yourICM10serverdomain ",
    "assert_endpoint": "server2domain:adminWebUIport/services/saml/acs",
    "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  },
  "idp_options": {
    "sso_login_url": "ssoidploginurl",
    "sso_logout_url": "ssoidplogouturl",
    "certificates": [
      " yourIDPCert"
    ],
    "force_authn": false,
    "sign_get_request": true,
    "allow_unencrypted_assertion": true
  },
  "sp_cert_key_id": "1"
}

Name

Description

sp_url

This should be updated to refer to your server2. If you're using a non-standard port (not port 80), ensure that the port is specified: yourICM10server2domain:adminWebUIport.

assert_endpoint

This should be updated to refer to your server2. If you're using a non-standard port (not port 80), ensure that the port is specified: server2domain:adminWebUIport/services/saml/acs.

sp_cert_key_id

In the example above, this is set to 1, as one certificate has been added. As more certificates are added, the ID will be incremented. The sso_certificate_key table in Postgres has all certificates listed.

certificates

Use the same format/instructions as in Generating a SAML 2.0 integration certificate using OpenSSL.

idp_options.certificates

This certificate is different than the certificate (spCertAsInStep2) listed on line 12. idp_options.certificates should originate from your identity provider (IdP). It is NOT the OpenAM generated certificate from the Generating a SAML 2.0 integration certificate using OpenSSL section.

Sample body

{
	  "tenant_id": "1",
  "ignore_signature": false,
  "sp_cert_key_id": "1",
  "certificate": [
"MIICsDCCAZgCCQCmhR6tkSBYeTANBgkqhkiG9w0BAQsFADAaMQswCQYDVQQGEwJj\nYTELMAkGA1UECAwCb24wHhcNMTgwODEz
MTUzMzI4WhcNMTkwODEzMTUzMzI4WjAa\nMQswCQYDVQQGEwJjYTELMAkGA1UECAwCb24wggEiMA0GCSqGSIb3DQEBAQUAA4IB\
nDwAwggEKAoIBAQCdKfslziLODmyreA/W7EgN0cIzy4oM1tcVd46+SjAyGy1TfYYR\nLWfgaogUPkB+RNPPyrTg7xhA1HQ4Fhi6
OH8UUZiS/Kaj0+q0/dHfEc2MS/PyhN41\nE/XaZvLnzn5onTIlUs2DxLTINSDV57i7MrRNcoKD+t8p2eFttc0tn8bkjA57R5TU\
n8gf4fW+Wi2uaQhkIZAieZUnYybWIfnjQnTM1qNoKCzQ3ZQl3luaaVYn0IkzdwG1Q\nNjmEIdcjKZytDPfnLSpkJSe0WurZV2IM
BqCJaLdjlzE6anQDLi53qlnLUHf1i26c\nI/SLOHezgVR54zutK2MpftxUMdfMILuMUyLbAgMBAAEwDQYJKoZIhvcNAQELBQAD\
nggEBAHp2Hw3N1sNFcGKAjulxdHTE7xC2MP7kDBE8vaA98UkYWhj3ifRAOEc9E2+t\nZooow7nMSGxzPS7V94KoF9s9RBhZCjOi
ynPfIOOhMEEWQzhdvdp8nAU/yXOVLAaO\nxPu66TSX14yP5ui1SwBNUa2L/96/U4nqGdOT5367d4qF4TchWPwEURH5+m22kwja\
njxpozvkx4lH4FaKW+GEsSRCrPHpTLroATuKt28PltcOcK8MFYQI7heEXCqQwkj6p\nYiAowhr4rAQDMhFDfhbBDS+XKoewxesG
1QqHRt3QSeE6vqatt2hK7txtMx2XBObq\n8vlDaI6QNW9+Ca6e0seWrTvv4eE=
"
  ],
  "tenant_name": "single",
  "sso_login_url": "http://myServer:8085/myIDP/SSORedirect/metaAlias/idp",
  "sso_logout_url": "http://myServer:8085/myIDP/IDPSloRedirect/metaAlias/idp",
  "sp_url": "http://myServer:90",
  "force_authn": false,
  "sign_get_request": "false",
  "allow_unencrypted_assertion": true,
  "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified",
  "is_sso_enabled": "true",
  "sp_options": {
    "entity_id": "http://myServer",
    "assert_endpoint": "http://myServer:90/services/saml/acs",
    "nameid_format": "urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified"
  },
  "idp_options": {
    "sso_login_url": "http://myServer:8085/myIDP/SSORedirect/metaAlias/idp",
    "sso_logout_url": "http://myServer:8085/myIDP/IDPSloRedirect/metaAlias/idp",
    "certificates": [  "MIICQDCCAakCBEeNB0swDQYJKoZIhvcNAQEEBQAwZzELMAkGA1UEBhMCVVMxEzARBgNVBAgTCkNh\
nbGlmb3JuaWExFDASBgNVBAcTC1NhbnRhIENsYXJhMQwwCgYDVQQKEwNTdW4xEDAOBgNVBAsTB09w\nZW5TU08xDTALBgNVBAMTBH
Rlc3QwHhcNMDgwMTE1MTkxOTM5WhcNMTgwMTEyMTkxOTM5WjBnMQsw\nCQYDVQQGEwJVUzETMBEGA1UECBMKQ2FsaWZvcm5pYTEUM
BIGA1UEBxMLU2FudGEgQ2xhcmExDDAK\nBgNVBAoTA1N1bjEQMA4GA1UECxMHT3BlblNTTzENMAsGA1UEAxMEdGVzdDCBnzANBgkq
hkiG9w0B\nAQEFAAOBjQAwgYkCgYEArSQc/U75GB2AtKhbGS5piiLkmJzqEsp64rDxbMJ+xDrye0EN/q1U5Of+\nRkDsaN/igkAvV
1cuXEgTL6RlafFPcUX7QxDhZBhsYF9pbwtMzi4A4su9hnxIhURebGEmxKW9qJNY\nJs0Vo5+IgjxuEWnjnnVgHTs1+mq5QYTA7E6Z
yL8CAwEAATANBgkqhkiG9w0BAQQFAAOBgQB3Pw/U\nQzPKTPTYi9upbFXlrAKMwtFf2OW4yvGWWvlcwcNSZJmTJ8ARvVYOMEVNbsT
4OFcfu2/PeYoAdiDA\ncGy/F2Zuj8XJJpuQRSE6PtQqBuDEHjjmOQJ0rV/r8mO1ZCtHRhpZ5zYRjhRC9eCbjx9VrFax0JDC\n/Ffw
WigmrW0Y0Q=="
    ],
    "force_authn": false,
    "sign_get_request": true,
    "allow_unencrypted_assertion": true
  }
}

Optional

If you would like to bypass the use of a private key, and if you would like your GET requests to not be signed, you can set the sign_get_request value on line 29 to false, "sign_get_request": false. Line 13’s GET request value (“false”) can be ignored.

Associate users to the SAML 2.0 configuration

After you create the SAML 2.0 integration configuration for the Incentives admin web application, use the REST API to associate users to the SAML 2.0 configuration.

To associate users to the SAML 2.0 configuration, use this REST API call:

PATCH yourServer/services/admin/1/users/{userid}/sso_nameid

Replace {userid} and sso_nameid with the userID that you want to associate to the SAML 2.0 configuration.

Important

The sso_nameid must match the ID used to identify users in the model.

Body:

 
{"sso_nameid":"sso_nameid"}

Get metadata to upload into SAML 2.0 IdP

After associating users to the SAML 2.0 configuration, use the REST API to get the sp.xml file (Service Provider metadata) from Incentives to upload into the SAML 2.0 IdP.

  1. To get metadata to upload into the SAML 2.0 IdP, perform the following REST API call:

    GET yourServer/services/ssoAdminweb/configs/1/metadata

  2. Save the returned values of this command as sp.xml. Save as an XML file by copying and pasting it into a text editor.

  3. Upload the sp.xml file to your IdP.

Configuring Apache server for virtual hosting

The last step to integrate SAML 2.0 is to configure the Apache server for virtual hosting.

  1. Navigate to your Apache HTTP Server installation directory and open the conf folder.

    For example, C:\Program Files (x86)\Apache Software Foundation\Apache2.2\conf

  2. Open the httpd.conf file using a text editor.

  3. Un-comment the following lines by removing the number symbol (#) at the start of the line.

    The lines should like this when you're done:

    LoadModule proxy_module modules/mod_proxy.so 
LoadModule proxy_connect_module modules/mod_proxy_connect.so 
LoadModule proxy_http_module modules/mod_proxy_http.so

  4. Add the following lines to the httpd.config file and change the lines according to your setup:

    <VirtualHost *:443>
     ServerAdmin “serveradmin“
     DocumentRoot "{ApacheInstallDirectory}\Apache2.4\htdocs"
     ServerName   “severname“
     ErrorLog "{ApacheInstallDirectory}\Apache2.4\error.log"
     CustomLog "{ApacheInstallDirectory}\Apache2.4\access_log.log" hgvhostAccesslog
	 ProxyPass /services /{{your tenant service domain}}:{{Ts domain port}}/services
	 ProxyPassReverse /services /{{your tenant service domain}}:{{Ts domain port}}/services
</VirtualHost>

    Note

    • ServerAdmin: listed in the httpd.conf file (~line 187)

    • ServerName: the fully qualified server name, such as yourServer.ca.varicent.com

    • Ensure that you followed the Install the Payee Web Classic application section, specifically step 5: "Between the <Directory "C:/Program Files/Apache Software Foundation/Apache2.2.16/htdocs"> and </Directory> tags, add the following lines:

      DirectoryIndex index.html
FallbackResource /index.html

    • If you are using SSL or a proxy to re-direct traffic via a VirtualHost, in your httpd – SSL.conf, in your <Directory "${SRVROOT}/htdocs"> section (within a VirtualHost entry), ensure the following entries exist within the Directory tag:

      <Directory "${SRVROOT}/htdocs">
    Options Indexes Includes FollowSymLinks MultiViews
    AllowOverride AuthConfig Limit FileInfo
    Require all granted
    DirectoryIndex index.html
    FallbackResource /index.html
 </Directory>

  5. Restart the Apache server, the Tenant services (node.js), and the REST API.

  6. Access the admin web application.

  7. Enter your userID and click Submit.

    You are redirected to the IdP login page.

  8. Login using IdP. You will be redirected back to the admin web application once authentication is complete.

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.

  1. Log in to Salesforce.com with a user ID that has administrative rights.

  2. Click your user-name to access the drop-down menu, and select Setup.

  3. From the App Setup section, click Create → Tabs.

  4. Click New in the Web Tabs section.

    This allows you to create a custom tab that displays Incentives content inside the Salesforce.com window.

  5. 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.

  6. Click Next after you have made your selection.

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

  8. 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.

  9. Set the encoding to Unicode (UTF-8).

  10. 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.

Using web forms on the Sales Portal (Payee Web V2)

If you want to use web forms with Sales Portal, you must first host them on Payee Web Classic, which then allows you to render them on Sales Portal in an iFrame.

  1. If you have not already completed installation and deployment of Payee Web Classic, you must complete these steps: Install the Payee Web Classic application.

  2. Add the following line to the newpayeeweb.properties file:

    Tip

    By default, the directory for this file is Tomcat/Webapps/Payeeweb/Web-INF/newnewpayeeweb.properties.

    newpayeeweb.basePath=/payeewebv2

  3. To create a proxy between Payee Web Classic and Sales Portal:

    1. In the Apache.HTTPD.CONF, remove the hash symbol from these lines to un-comment them:

      LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_connect_module modules/mod_proxy_connect.so
LoadModule proxy_http_module modules/mod_proxy_http.so

    2. Add proxy remapping before the alias payeewebv2 configuration. As an example, it should look something like this:

      ProxyPass /payeewebv2/webforms http://localhost:8085/payeeweb/webforms
ProxyPassReverse /payeewebv2/webforms http://localhost:8085/payeeweb/webforms

ProxyPass /payeeweb http://localhost:8085/payeeweb
ProxyPassReverse /payeeweb http://localhost:8085/payeeweb

      http://localhost:8085 is the Tomcat port where Payee Web Classic is hosted.

      payeeweb is the Incentives .war file name and cannot be changed. It’s also the name of the Tomcat Web-APP deployed for Payee Web Classic.

      You may change localhost to a server name or IP for consistency with the configuration files and to match the Payee Web Classic deployment in Tomcat.

      If https is required, you must deploy the Tomcat port to HTTPS protocol. The URL will be https://localhost:8085/payeeweb instead.

Load balancer configuration

If Sales Portal is hosted behind a load balancer and accessed via https://loadbalancerURL/Payeewebv2, then the Payee Web Classic URL must also be accessible behind a load balancer.

Ensure the URL https://loadbalancerURL/payeeweb is accessible on the load balancer. If it is not, the API calls to that URL will fail to redirect at the load balancer.

It is recommended to set up a new irole to route traffic from https://LoadBalancerURL/payeeweb to http://Servername:8085/payeeweb.

Setting up a Varicent Tab on Salesforce Mobile

To access Varicent tabs on the Salesforce mobile app, you must create a Visualforce page and configure it with a link to Sales Portal. Then, you can create a Visualforce tab so users can find it in the Salesforce mobile app.

By default, the view is the same as Sales Portal on desktop, but you can choose to disable the navigation bar and link to a specific report instead.

What's different in Salesforce Mobile?

There are some cases where Incentives web tabs on Salesforce mobile behave differently or are limited in some way when compared to the desktop experience. You should keep this in mind when setting up this integration.

  • You cannot download files. This includes trying to download files from the Message Center or trying to export reports to PDF or Microsoft Excel.

  • Some fonts may not display correctly on some mobile devices. This depends on the operating system. For example, iOS does not support Tahoma.

    For a list of iOS-supported fonts, see: https://developer.apple.com/fonts/system-fonts/.

    If a particular font is not available on the user's device, Inter will be used instead. This is same font used in the admin application.

  • The user is authenticated every time the web tab is accessed. This can make it seem like reports take longer to load when compared to the desktop application.

  • On iOS devices, the Freeze header option on data grids does not work.

  • Some report content can appear cut-off if there is limited padding on the report.

  • Performance can vary depending on the mobile device and OS. Generally, a newer device will load Incentives reports faster than an older one. The difference in loading times is more noticeable in reports with a large amount of data.

Creating a Visualforce page

  1. Log in to Salesforce.

  2. Click your username and then click Setup.

  3. From the sidebar, under the Develop section, click Visualforce Pages.

  4. Click New.

  5. Enter a label and page name.

  6. Select the Available for Lightning Experience, Lightning Communities, and the mobile app checkbox.

  7. In the Visualforce Markup section, replace the default code with this code:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeeweb/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}&Tenant=rti&Model=rtiprod" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>                                       

    • Update apex:iframe src , replacing https://rti.spm.varicent.com/payeeweb/ with the URL of your company's Sales Portal instance.

    • Update serverURL, replacing {!$Api.Partner_Server_URL_210} with the URL of the Visualforce page you set up.

    • Update Tenant , replacing rti with your Incentives tenant name.

    • Update Model , replacing rtiprod with your Incentives model name.

  8. Click Save.

If you want users to be able to see the same reports that they would have access to on desktop, proceed to Creating a VisualForce tab.

If you want users to be able to see specific reports only, follow the directions in Creating a direct link to a Varicent web tab.

Creating a direct link to a Varicent web tab

By creating a link to a specific web tab, instead of users arriving at the home page that they would see on desktop, a direct link disables the navigation bar so they can only access the report you specify.

With this set up, users are also unable to make inquiries on reports.

To create a direct link, you'll add an extra piece of code on Step 7 of Creating a Visualforce page after the Model name.

The code varies slightly depending on whether you use Payee Web Classic or the newer version of Sales Portal and what type of web tab you're linking to.

You can find the ID or number of the tab you want to link to by going to that report in Sales Portal and checking the part of the URL that follows payeeweb or payeewebv2. If you're setting up a Direct Link web tab, you can get the ID directly from Portal Access.

ID_in_URL.png

  1. For web form tabs in Payee Web Classic, add this code: &nextPath=webforms/index.html?tabId=#, replacing # with the tabID for the web form you want to link to.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}&Tenant=rti&Model=rtiprod&nextPath=webforms/index.html?tabId=1" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>

  2. For Presenter report tabs in Payee Web Classic, on Step 7 of Creating a Visualforce page, add this code after the Model name: &nextPath=reporting/index.html?tabId=1.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL=https%4B%3H%3Hd.na15.visual.force.com%3Hservices%3HSoap%3Hv%3H21.1%3H00EB000000018FJ&Tenant=rti&Model=rtiprod&nextPath=reporting/index.html?tabId=1" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999' />    
    </apex:pageblock>
</apex:page>

  3. For web form tabs in Sales Portal, on Step 7 of Creating a Visualforce page, add this code after the Model name: nextPathname=WebForm/###, replacing ### with the number of the tab you want to link to.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}&Tenant=rti&Model=rtiprod&nextPathname=WebForm/492" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>

  4. For Presenter report tabs in Sales Portal, add this code: nextPathname=PresenterReport/###, replacing ### with the number of the tab you want to link to.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}https%4B%3H%3Hd.na15.visual.force.com%3Hservices%3HSoap%3Hv%3H21.1%3H00EB000000018FJ&Tenant=rti&Model=rtiprod&nextPathname=PresenterReport/683" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>

  5. For Data Discovery Dashboards and Data Discovery Infographics web tabs in Sales Portal, add this code: nextPathname=DDE/###, replacing ### with the number of the tab you want to link to.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}&Tenant=rti&Model=rtiprod&nextPathname=DDE/456" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>

  6. For Rapid Reports web tabs in Sales Portal, add this code: nextPathname=RapidReport/###, replacing ### with the number of the tab you want to link to.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}&Tenant=rti&Model=rtiprod&nextPathname=RapidReport/123" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>

  7. For Direct Link web tabs in Sales Portal, which can be Presenter Reports, Rapid Reports, or Data Discovery Dashboards, add this code: nextPathname=DirectLink/### with the number of the tab you want to link to.

    Tip

    For more information about generating a direct link, read: Creating a direct link web tab for Salesforce Mobile.

    As an example, the code looks like this:

    <apex:page showHeader="false" standardStylesheets="false" sidebar="false" applyHtmlTag="false" applyBodyTag="false" docType="html-5.0" >    
    <apex:pageblock >        
        <apex:iframe src="https://rti.spm.varicent.com/payeewebv2/sforce_composite_login?SessionId={!$Api.Session_ID}&ServerURL={!$Api.Partner_Server_URL_210}&Tenant=rti&Model=rtiprod&nextPathname=DirectLink/416" scrolling="true" id="theIframe" style='position:absolute; top:0px; left:0px; width:100%; height:100%; z-index:999'/>    
    </apex:pageblock>
</apex:page>

Creating a direct link web tab for Salesforce Mobile

If you design a web tab meant for viewing on a mobile device, you can share that report using a Direct Link web tab. This means it won't be visible by default on the desktop web application. Users either need to have the URL or access it through a Salesforce Mobile tab.

  1. In Portal Access, on the Web Tabs tab, click the Add Web Tab icon.

  2. In the Name field, type a name for the web tab. You can use special characters, such as hyphens and apostrophes.

  3. From the Type menu, select Direct Link.

  4. From the Direct Link Type menu, select either Infographic, Presenter Report, or Rapid Report.

  5. From the Object drop-down list, select the object that you want to assign to the web tab.

  6. Click Add Web Tab.

  7. Hover over the web tab row you created and click the Copy URL button.

  8. Paste the URL into a text editor and copy the ID number.

    For example, if the URL is http://rti.spm.varicent.com/payeewebv2/DirectLink/4096, you need to copy 4096 and add it to the code in Salesforce.

Creating a VisualForce tab

  1. Click your username and then click Setup.

  2. From the sidebar, go to Create → Tabs.

  3. In the Visualforce Tabs section, click New.

  4. Enter a label and tab name.

  5. Select the VisualForce page you created.

  6. Select a preferred tab style.

  7. Add the tab visibility based on the profiles you want to grant access to.

  8. Click Save.

  9. Use Search to find "Salesforce Navigation" and select it from the Salesforce Administration menu.

  10. Find the tab you created and move it from Available to Saved.

  11. Click Save.

Viewing Varicent in Salesforce Mobile

To confirm you successfully set up the VisualForce page and tab, look for your Incentives reports in the Salesforce Mobile app.

  1. On your mobile device, download the Salesforce app from the iOS app store or the Google Play store.

  2. Log in to the Salesforce app.

    Important

    The account must be a Salesforce ID with an email address that matches a SSO-enabled Sales Portal user. That user must be enabled for the model you specified when you created the VisualForce page.

  3. From the menu, find the name of the VisualForce tab you added.

When you click the name of the tab, you will access Incentives. You will see Sales Portal as it appears on desktop. But you can modify this to hide the navigation and only let users access specific web tabs. Read: Creating a direct link to a Varicent web tab

Setting up SSL for secure HTTPS connections on Sales Portal (Classic)

You can set up SSL on Payee Web Classic for secure HTTPS connections. This set up requires you to set up tenant services with HTTPS. You will also have to work with keystores and certificates and create multiple virtual hosts using an Apache httpd server.

Configuring REST API and tenant services

Before you begin, ensure that you have matching host values in all fields in the the defaults.json and REST API.exe.config files.

In defaults.json, the fields that need matching host values are:

  • server > cookieDomainUrl

  • server > globalDomains

  • RESTAPI > host

  • RESTAPI host > hosts > default

In REST API.exe.config, the fields that need matching host values are:

  • SchedulerService

  • TenantServices

  • Host

  • ServiceAddress

  1. In defaults.json, edit the Payeeweb section so that the port and protocol is set to the correct Apache Tomcat server HTTPS and SSL settings.

    It should look something like this:

    "Payeeweb" : 
    {            
        "port": 8443,
        "protocol": "https",
    }

  2. Go to the location where you installed Apache 2.4 htdocs and open index.html. Edit the API_URL and AUTH_URL to match the host values in defaults.json and REST API.exe.config.

    They should look something like this:

    API_URL: 'http://yourServer.varicent.com:8080',
AUTH_URL: 'http://yourServer.varicent.com:9100',

Configuring the Apache HTTP server

  1. If you haven't already installed Apache web server, follow the directions from Installing Apache Web Server:

    1. Navigate to C:\Program Files\Apache Software Foundation\Apache2.2.16\conf.

    2. Open the httpd.conf file and comment out the <Directory /> section by using the number (#) symbol.

    3. Between the <Directory "C:/Program Files/Apache Software Foundation/Apache2.2.16/htdocs"> and </Directory> tags, add these lines:

      DirectoryIndex index.html
FallbackResource /index.html

  2. While still in the httpd.conf file, remove the number symbol (#) from these lines:

    Tip

    These lines are not consecutive. Make sure you find all three and remove # from each.

    LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so
LoadModule ssl_module modules/mod_ssl.so

  3. Add these sections to httpd.conf:

    Listen 433
<VirtualHost *:433>       
    ServerName yourServer       
    SSLEngine on       
    SSLCertificateKeyFile C:/Users/user/Desktop/device.key       
    SSLCertificateFile C:/Users/user/Desktop/device.crt       
    SSLProtocol -all +TLSv1.2       
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:!DSS       
    ProxyPass /services/ http://yourServer:9100/services       
    ProxyPassReverse /services/ http://yourServer:9100/services
    ProxyPass /api/ http://localhost:8080/api/
    ProxyPassReverse /api/ http://localhost:8080/api/
</VirtualHost> 
    Listen 9001
<VirtualHost *:9001>       
    ServerName yourServer       
    SSLEngine on       
    SSLCertificateKeyFile C:/Users/user/Desktop/device.key       
    SSLCertificateFile C:/Users/user/Desktop/device.crt       
    SSLProtocol -all +TLSv1.2       
    SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:!DSS       
    ProxyPass /services/ http://yourServer:9101/services       
    ProxyPassReverse /services/ http://yourServer:9101/services
    ProxyPass /api/ http://localhost:8080/api/
    ProxyPassReverse /api/ http://localhost:8080/api/
</VirtualHost>

    1. Update SSLCertificateKeyFile and SSLCertificateFile with the location of your files.

    2. Update ProxyPass and ProxyPassReverse with your server's hostname and IP.

  4. Replace the default Apache certificate .crt and .key files with your own trusted certificates.

    By default, you can find those files at C:\Program Files\Apache24\conf\ssl\server.crt and C:\Program Files\Apache24\conf\ssl\server.key.

Configuring the Apache Tomcat server and Sales Portal .WAR files

  1. Update these fields in the Tomcat /payeeweb/WEB-INF/security.properties file. They must match the Apache http server virtual host values. The protocol must also be changed to https instead of http.

    C:\Program Files\Apache Software Foundation\Tomcat\7.0\webapps\payeeweb\WEB-INF\security.properties 

# JWT Configuration
security.jwt.home=/home.html
security.jwt.tenant-services-url=https://yourServer:433/services/varicent_web_login
security.jwt.secretkey=varicent-ca-varicent-varicentweb-secret-key
security.jwt.tenantServicesPrivateUrl=https://yourServer:9001/services
security.jwt.tenantSecretKey=varicent-tenant-varicent-spm-production

    Tip

    All ports must match in both the security.properties and the httpd.conf files.

  2. Set up SSL on Tomcat by following the Apache Tomcat guide.

    When you get to the server.xml file, it should look something like this when you're done, where the connector on port 8443 is configured to use a keystoreFile:

    <Connector port="8085" protocol="HTTP/1.1"
    connectionTimeout="20000"
    redirectPort="8443" />                                

<Connector port="8443" 
protocol="org.apache.coyote.http11.Http11Protocol" SSLEnabled="true"
maxThreads="150" scheme="https" secure="true"
clientAuth="false" sslProtocol="TLS" keyAlias="ICMSSL"     keystoreFile="C:/keystore_Tomcat_SSL.jks" keystorePass="test" />

Importing Java cacerts keystore

  1. Add all of the Apache HTTP and Apache Tomcat certificates that you use a Java trusted keystore cacerts.

    For more information about this, read IBM SDK, Java Technology Edition 7.1 cacerts Certificates File.

  2. From the command line, navigate to the location where you installed Java's bin folder.

  3. Using the keytool, import all certficates used by Apache HTTP and Apache Tomcat web servers into the Java keystore (cacerts) to make all certificates trusted.

    Tip

    By default, the Java cacert keystore password is changeit.

    If you are using only one certificate, you need to import the main cert and the root cert. If Tomcat SSL uses a different cert, you must import that, too. These examples show import of the main cert, root cert, and a Tomcat SSL cert:

    C:\Program Files\Java\jre1.8.0_144\bin>keytool.exe -import -keystore "C:\Program Files\Java\jre1.8.0_144\lib\security\cacerts" -alias yourServer.varicent.com.device -file C:\Users\ user \Desktop\currentCerts\device.crt
Enter keystore password: changeit
Certificate was added to keystore
    C:\Program Files\Java\jre1.8.0_144\bin>keytool.exe -import -keystore "C:\Program Files\Java\jre1.8.0_144\lib\security\cacerts" -alias yourServer.varicent.com.rootCa -file C:\Users\ user \Desktop\currentCerts\rootCA.pem
Enter keystore password: changeit 
Certificate was added to keystore
    C:\Program Files\Java\jre1.8.0_144\bin>keytool.exe -import -keystore "C:\Program Files\Java\jre1.8.0_144\lib\security\cacerts" -alias yourServer.varicent.com.TomcatSSL -file C:\Users\user\Desktop\currentCerts\yourTomcatSSLcertificate.cer
Enter keystore password: changeit
Certificate was added to keystore

  4. Restart Apache HTTP server and Apache Tomcat services.

(Optional) Generating a self-signed certificate using OpenSSL

You can use OpenSSL to generate self-signed certificates. More information: https://www.openssl.org/

  1. Using a text editor, create a file and name it v3.ext.

  2. Add this content to the file, replacing the server and alt names with your server information:

    authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment,                 dataEncipherment
subjectAltName = @alt_names

[alt_names]
DNS.1 = localhost
DNS.2 = yourServer
DNS.3 = *.yourDomain
IP.1 = 127.0.0.1
IP.2 = 1.2.3.4

  3. From the command line, navigate to the location where you installed OpenSSL's bin folder.

    By default, it's installed here: C:\OpenSSL-Win32\bin.

  4. Run these commands to generate output files:

    openssl genrsa -out rootCA.key 2048
    openssl req -x509 -new -nodes -key rootCA.key -sha256 -days 1024 -out rootCA.pem
    openssl req -new -newkey rsa:2048 -sha256 -nodes -keyout device.key -subj "/C=CA/ST=None/L=NB/O=None/CN=yourServer.varicent.com" -out device.csr
    openssl x509 -req -in device.csr -CA rootCA.pem -CAkey rootCA.key -CAcreateserial -out device.crt -days 999 -sha256 -extfile v3.ext

    If successful, you should have these output files: rootCA.key, rootCA.pem, device.key, device.csr, device.crt.

  5. Using Microsoft MMC, install these certificates as trusted root certificates.

    Note

    device.crt is the only certificate that needs to be imported.

    For more information on how to do this, read the Microsoft documentation.

(Optional) Importing the certificate and private key into Keystore for Tomcat SSL

You can create a new keystore that can be used by Tomcat in the <Connector keystoreFile=”” > tag. You don't need to do this if you already have a keystore you want to use.

  1. From the command line, navigate to the location where you installed OpenSSL's bin folder.

    By default, it is installed at C:\OpenSSL-Win32\bin.

  2. Run this command to convert an existing certificate and the corresponding private key to a PKCS 12 file:

    openssl.exe pkcs12 -export -in device.crt -inkey device.key -out keystore.p12 -name yourOrganization -chain

  3. Navigate to the location where you installed Java's bin folder.

  4. Run this command to create a keystore based on the PKCS file:

    "C:\Program Files\Java\jre1.8.0_144\bin\keytool.exe" -importkeystore -deststorepass changeit -destkeypass changeit -destkeystore keystoreConverted.jks -srckeystore keystore.p12 -srcstoretype PKCS12 -srcstorepass changeit -alias varicentCloud

Multiple SQL server databases configuration

You must follow some additional steps to configure Incentives on Premise when using multiple SQL server databases.

REST API configuration for multiple databases

There are some additional steps that you must follow to configure the REST API when using multiple databases.

  1. Go to the location where you installed the REST API and open the RESTAPI.dbServers.config.

  2. Navigate to the <databaseServers> section and find the <databaseServer Name="default"> entry.

  3. Select, copy, and paste the full <databaseServer> entry on a new line below the existing entry. You should now have two <databaseServer> entries.

    multipleDBs.jpg

  4. Configure your second database entry by updating values as required. Your Name value must match your corresponding defaults.json server entry’s Name value. This will be configured in the next section. Make a note of the Name value. Also, ensure that your DiskPath and LogPath values are valid locations on your SQL database server.

Tenant services configuration for multiple databases

There are some additional steps that you must follow to configure the Tenant services when using multiple databases with Incentives.

  1. Go to the location where you installed tenant services and open the defaults.json file.

  2. In the modelServer section, find the servers section and qdd a comma (“,”) after the “}” ending bracket of the existing entry.

  3. Select, copy, and paste the full servers entry on a new line below the existing entry.

    You should now have two servers entries.

    serversSection.jpg

  4. Configure your second database entry by updating values as required. Ensure that your second database entry has a unique id value that is different from your first entry’s id value. Ensure that your name value matches the corresponding RESTAPI.dbServers.config file database’s name value.

REST API calls for tenant services with multiple databases

Make sure that all required components are installed and configured: REST API, Tenant Services, Redis, PostgreSQL, Node.js, SQL Server, Scheduler, Apache Web Server, and Apache HTTP server.

  1. Follow the instructions in REST API calls for tenant services to generate a JSON Web Token (JWT) and use these values:

    Header: Keep as default

    Payload:

    { "admin_user": {}, 
"server":"2" 
}

    Verify Signature: Replace your-256-bit-secret with management-portal

    invalidsignatureerror.jpg

  2. Continue following the instructions in REST API calls for tenant services to add the Authorization and Content-Type key values.

  3. Proceed with the REST API calls to continue with the creation and configuration of your model.

    Depending on the JWT token used, the REST API calls will be called on different SQL database servers. To change the SQL database server that REST API calls are directed to in Postman, change the JWT key by changing the Payload's server value and regenerating the token. Then, update the bearer in the Postman Header value.

Migrating between multiple tenants

If you have a set-up where a single tenant service is used by all of your environments, then you can perform migrations as if you were on Cloud. This is because all of your environments already share a connection to the same REST API and tenant services. Follow the instructions for migrations in the User Guide: Migration.

If you have a set-up where each environment is on a different tenant service, there are some additional steps you must take before you can migrate between environments.

In this example, we will migrate from our DEV environment (the source model) to our TEST environment (the target model).

  1. In the defaults.json file for the target model, add the source model server details to the servers section.

    Tip

    Make sure the model servers you add have unique IDs and names from any previous ones you've added.

    It should look something like this when you're done:

    "modelServer": {
    "servers": {
        {
            "id": 1,
            "name": "TEST",
            "datacenter": "default",
            "instanceName": "SQL2016",
            "address": "nameOfsqlServerInstance",
            "hostname": "localhost",
            "user": "sa",
            "password": "aStrongPassword",
            "databaseType": "SQLServer2014Unicode",
            "enableCreation": true,
            "timeoutSeconds": "9000",
            "logPath": "F:\\",
            "diskPath": "F:\\",
            "accessVersions": [1],
            "logins": {
                "1": {
                    "user": "sa",
                    "password": "aStrongPassword",
                    }
                }
        },
        {
            "id": 2,
            "name": "DEV",
            "datacenter": "default",
            "instanceName": "SQL2016",
            "address": "uniqueNameOfSqlServerInstance",
    }

    Tip

    Make sure you don't forget the comma separating the different servers! If you forget it, tenant services won't restart properly and you won't be able to log in to the admin application.

  2. If your target model is located on a different SQL server instance than the source model, edit the RESTAPI.dbservers.config file to have a new database server entry.

    It should look something like this when you're done:

    <databaseServers>
    <databaseServer Name="TEST">
    </databaseServer>
        <databaseServer Name="DEV">
        </databaseServer>
</databaseServers>

  3. Using Postman, make an API call to associate the source model to the target model in postgres:

    Request  /tenants/1/models/externalRestore
Method: Post
Sample Call Path: http://localhost:9100/services/tenants/1/models/externalRestore
Body: { 
    "model_name":“DEV",
    "server":“2",
    "isOverwrite":false,
    "isUnicode": true
}

  4. Make an API call to create an admin user with access to all models and permission to perform migrations:

    Sample Call Path: http://localhost:9100/services/admin/tenants/1/users
Method: POST
Body: {      
    "tenant_id": "1",       
    "email": "migrationuser@test.com ",       
    "password": “aStrongPassword",      
    "first_name": “Migration",      
    "last_name": “User"
}

  5. Make an API call to associate the admin user who will perform the migration to all of your environments:

    Sample Call Path: http://localhost:9100/services/admin/tenants/1/users/migrationuser@test.com
Method: PATCH
Body: {                  
    “tenant_id”: “1”,                  
    “email”: “migrationuser@test.com”,                  
    “model”: “DEV”
}

    Tip

    If you created an admin user in step 4, you must make this call a second time for the target model.

    In this example, we would change the model to "TEST" and make the call again.

If successful, when you go to the source model (TEST) admin application and perform a migration, the target environment (DEV) appears as an option in the migration wizard.

Setting the Audit Log time zone

You can configure the Audit Log so that the display time syncs with the admin web user's local time. Configuring this setting also prevents any issues related to Daylight Savings.

For this to work, the application servers and the database server must both be configured to UTC (Coordinated Universal Time). If the REST API and tenant services are on separate servers, then you must change the time zone to UTC on the servers that have the REST API, tenant services and SQL server. If you do not change this setting, the Audit log will always display times in UTC time for all users.

Note

This configuration will not affect the tenant services console. That will always show in UTC.

  1. On the server where you installed REST API and tenant services, go to the Date and Time settings.

    You may be able to find this by clicking the date and time in the menu bar and then clicking Change date and time settings.

    setting up the audit log time 3

  2. Click Change time zone and then change the time to UTC (Coordinated Universal Time).

    setting up the audit log time 2

  3. Click OK or close the window.

  4. To confirm that the time zone has been correctly updated, in the command line, type this command:

    tzutil /g

  5. If the time zone has not been updated after performing the previous steps, in the command line, type this command:

    tzutil /l

    You should see a list of time zones that looks something like this. Make a note of the time zone you want to use.

    setting up the audit log time

  6. In the command line, type this command, replacing <timeZone> with the time zone you want to use:

    tzutil /s "<timeZone> /l"

  7. Restart tenant services and the REST API.