11 Configuring Visitor Services

After you set up the Oracle WebCenter Sites: Visitor Services Managed Servers, you can configure Visitor Services with the browser-based Visitor Services Configurator. Visitor Services runtime consists of visitors-webapp applications (WAR files), a config directory, a database instance, sample bundle code, providers, and a visitors client.

The following topics describe configuring Visitor Services:

11.1 Completing Prerequisites for Configuring Visitor Services

Before configuring Visitor Services, make sure the prerequisite tasks are done.

To complete the prerequisites for configuring Visitor Services:
  1. Create a WebCenter Sites – Visitor Services database schema with the Repository Creation Utility, as Creating the Database Schemas describes.
  2. Create a WebCenter Sites – Visitor Services database schema with the Repository Creation Utility, as Creating the Database Schemas describes.
  3. Create Managed Servers for Visitor Services using the WebLogic Configuration Wizard and the Oracle WebCenter Sites Visitor Services — 12.2.1.0.0 template, asConfiguring the WebCenter Sites Domain describes.

    Note:

    For IBM DB2 Visitor Services does not support the default data source created by the Fusion Middleware Configuration Wizard. To create new data source with a driver that DB2 supports:
    1. Add the IBM DB2 Driver JAR files to the class path for the WebLogic domain.

      1. Stop the WebLogic Server Administration Server.

      2. Copy the db2jcc.jar and db2jcc_license_cu.jar files from DB2 to a location that you can add to the domain class path.

      3. Edit DOMAIN_HOME/bin/setDomainEnv.sh and add the following line after # ADD EXTENSIONS TO CLASSPATHS:

        PRE_CLASSPATH="path_to_db2jcc.jar:path_to_db2jcc_license_cu.jar:${PRE_CLASSPATH}"

      4. Start the Administration Server.

    2. Create a new data source using the preceding DB2 driver. For more information, see Specifying JDBC Component Schema Information.

  4. Run security configuration if this was not already run for other components (for example, WebCenter Sites ). If Visitor Services is configured in the same WebLogic domain as WebCenter Sites, ignore this step.

    Grant read, write, and delete permissions for accessing the Oracle Platform Security Services credential store to ORACLE_HOME/wcsites/wcsites_common/lib/sites-security.jar by executing the following script.

    • On UNIX operating systems:

      DOMAIN_HOME/wcsites/bin/grant-opss-permission.sh

    • On Windows operating systems:

      DOMAIN_HOME\wcsites\bin\grant-opss-permission.bat

    Use the WebLogic Server Administrator user name and password, when prompted by the script.

11.2 Configuring Visitor Services with the Configurator

The Visitor Services Configurator supports silent mode and interactive mode.

To configure Visitor Services in silent mode:

  1. Edit the DOMAIN_HOME/wcsites/visitorservices/config/wcs_svs_properties_bootstrap.properties file and update it with Oracle WebCenter Sites: Visitor Services details.

    If Java Messaging Service (JMS) needs to be configured, update the JMS details; otherwise, keep visitors.jms_service_in_use=false.

  2. Start the Visitor Services Managed Server.

    Complete the bootstrap process of Visitor Services using this URL: http://visitorservices-server:visitorservices-port/visitorservices-webcontext/bss

  3. Restart the Visitor Services Managed Server.

To configure Visitor Services in interactive mode:
  1. Start the Visitor Services Managed Server.
  2. In a web browser, access the Visitor Services Configurator at the following URL: http://visitorservices-host:visitorservices-port/visitors-webapp/bootstrapconfig
  3. On the Visitor Services Configurator screen that appears, click Begin.
  4. On the screen that appears, complete the Sites Web Application Parameters section as the following table shows.
    Host name or IP address Host name or IP address of the target WebCenter Sites instance.
    Port number Port number of the target WebCenter Sites instance.
    Application context root Context root of the target WebCenter Sites instance.
    Secure connection? If your environment is set up for SSL connectivity, select Yes; otherwise, select No.
    Site name Name of the target WebCenter Sites site.
    Username Name of the Administrator user account for the target WebCenter Sites instance.
    Password Password of the Administrator user account for the target WebCenter Sites instance.
    Re-enter the Password Confirm the password entered in the previous field.
  5. Complete the Visitor Services Parameters section as follows:
    Data Source JNDI Name Full name of the Visitor Services data source. If you have used the Repository Creation Utility to create the Visitor Services data repository, this is automatically pre-populated.
    Have you configured JMS resources? If you want to integrate Visitor Services with Java Messaging Service, select Yes; otherwise, select No.
    JMS connection factory JNDI name Full name of the Java Messaging Service connection factory.
    JMS enrichment queue JNDI name Full name of the Java Messaging Service enrichment queue.
    JMS profile update queue JNDI name Full name of the Java Messaging Service profile update queue.
    JMS Transaction support Select Yes to enable Java Messaging Service transaction support; otherwise, select No.
    JMS Persistence support Select Yes to enable Java Messaging Service persistence support; otherwise, select No.
  6. Click Test to test connectivity with the WebCenter Sites instance.
  7. When the connectivity test succeeds, click OK to initiate the configuration process and wait for the confirmation screen to appear.
  8. In the confirmation screen, you must click Close to commit your configuration; if you do not click Close, your configuration will be lost.
  9. Restart the Visitor Services Managed Server.
  10. Log in to the WebCenter Sites Admin interface.
  11. Configure a Visitor Services Administrator user name and password in the WebCenter Sites Property Management Tool:
    1. Select the Admin interface icon.

    2. In the Admin tree, expand System Tools, and then double-click Property Management.

    3. Edit the wcsites.visitors.admin.user and wcsites.visitors.admin.password properties to set the user name and password.

  12. Restart the WebCenter Sites Managed Server.
  13. Create and enable an identity provider to use with Visitor Services. An identity provider authenticates site visitors to Visitor Services. Visitor Services ships with an Oracle Access Manager identity provider for integration with Oracle Access Manager.
  14. (Optional) Create and enable an access provider to use with Visitor Services. An access provider authenticates REST calls made between Visitor Services and WebCenter Sites. Oracle recommends using an access provider to maintain a secure connection between Visitor Services and WebCenter Sites. Visitor Services ships with a basic LDAP access provider for authentication against an LDAP directory.
    You also need to set the following properties:
    • wcsites.visitors.auth.password

    • visitors.rest.authalias

    • visitors.rest.authtype

    • visitors.rest.authheader

    • wcsites.visitors.auth.user

  15. Create and enable one or more profile providers. A profile provider allows the association of a visitor identity with a visitor profile. Visitor Services ships with an Eloqua profile provider for integration with the Eloqua Cloud Marketing Service, and an Oracle Access Manager profile provider for integration with Oracle Access Manager.
  16. Create an aggregation template. An aggregation template determines what data, based on visitor profiles, is returned to the site visitors.
    For more information, see Developing WebCenter Sites: Visitor Services in Developing with Oracle WebCenter Sites.
  17. Restart the WebCenter Sites and Visitor Services Managed Servers.

11.3 Getting the Visitor ID

The Oracle WebCenter Sites: Visitor Services OAMIdentityProvider is supported for Oracle Access Manager 11.1.2.2.0 and 11.1.2.3.0.

For information about installing Oracle Access Manager, see the Oracle Identity and Access Management Installation Guide.

To get the visitorId value using OAMIdentityProvider:

  1. Log in to WebCenter Sites at http://site-host:site-port/sites/.

  2. Select AdminSite, Select the Admin interface icon, and click Hide Left Hand Navigation, Admin, and then Identity Providers List.

  3. Upload the identity-provider-oam.jar file located under ORACLE_HOME/wcsites/visitorservices/providers/identity-providers/, with appropriate configuration data in the configuration field.

  4. Copy the configuration located under ORACLE_HOME/wcsites/visitorservices/providersConfig/identity-provider-oam/identity-provider-oam.properties.

  5. Click Profile Provider List.

  6. Make sure that the User Identity Store is configured for User profiles in Oracle Access Manager. (For User Identity Store configuration, see the Oracle Identity and Access Management Installation Guide.

  7. Upload the profile-provider-ldap.jar file with the name UserIdentityStore1 located under ORACLE_HOME/wcsites/visitorservices/providers/profile-providers/ with appropriate configuration data in the configuration field.

  8. Copy the configuration located under ORACLE_HOME/wcsites/visitorservices/providersConfig/profile-provider-ldap/profile-provider-ldap.properties.

  9. The get visitorId for user ex test belongs to the Oracle Access Manager embedded LDAP using the following URL in a REST client:

    http://OHS-host:OHS-port/visitor-services-context/rest/v1/visitor/getId
    

    Add the headers content-type andapplication/x-www-form-urlencoded, and provide the request body:

    request={
    "parameters":"{}",
    "headers":"{}",
    "cookies":"[{}]"
    "header":"{\"oam_identity_domain\":\"UserIdentityStore1\",\"oam_remote_user\":\"test\"}"
    }
    

To get the visitorId value using SampleIdentityProvider:

  1. Log in to WebCenter Sites at http://sites-host:sites-port/sites/

  2. Select AdminSite, Select the Admin interface icon, and click Hide Left Hand Navigation, Admin, and then Identity Providers List.

  3. Upload the identity-provider-oam.jar file located under ORACLE_HOME/wcsites/visitorservices/providers/identity-providers/, with appropriate configuration data in the configuration field.

  4. Copy the configuration located under ORACLE_HOME/wcsites/visitorservices/providersConfig/identity-provider-sample/identity-provider-sample.properties.

  5. Click Profile Provider List. (Make sure that Oracle Internet Directory or another LDAP authentication provider is installed and configured.

  6. Upload the profile-provider-ldap.jar file located under ORACLE_HOME/wcsites/visitorservices/providersConfig/profile-provider-ldap/profile-provider-ldap.properties.

  7. Copy the configuration located under ORACLE_HOME/wcsites/visitorservices/providersConfig/profile-provider-ldap/profile-provider-ldap.properties.

  8. The get visitorId for user test belongs to the Oracle Internet Directory LDAP using the following URL in a REST client:

    http://visitorservices-host:visitorservices-port/visitorservices-context/rest/v1/visitor/getId
    

    Add the headers content-type andapplication/x-www-form-urlencoded, and provide the request body:

    request={
    "parameters":"{\"external_id\":[\"ssoid1\"]}",
    "headers":"{}",
    "cookies":"[{}]"
    "header":"{}"
    }
    

11.4 Completing the Visitor Services Cluster Configuration

Visitor Services is a completely stateless web application, so there is no need for session replication or session management at the cluster level. Cluster configuration of Visitor Services mainly involves taking care of configuration data.

After the first node (primary cluster node) has been created, all other nodes should use the configuration files from the primary cluster node. Of particular importance is the visitors.properties file. The main configuration file for Visitor Services is visitors.properties. This file contains details about the data source in the Visitor Services database, JMS objects, and a URL to a WebCenter Sites instance (either one node or if there is a WebCenter Sites cluster, the load-balancer URL). The secondary nodes can use the visitors.properties file from the primary cluster node in either of two ways:

  • All nodes in the Visitor Services cluster can have a replica of the same Visitor Services file in their class path.

  • All nodes can point to single visitors.properties file with file path being in a shared folder.

There is a single database for the entire Visitor Services cluster. The data source property in the visitors.properties file for each node should point to this single database.

Other Visitor Services configuration files are not meant for modification. Copy them as is from the primary node to the secondary nodes.

Although JMS is optional, Oracle recommended that JMS be used. Each node should point to same JMS objects. A nodes should not configure a different JMS queue because having that node down would result in losing out on messages present in that queue.

The visitors-cache.xml file provides distributed caching configuration for managing a cache of visitors objects (identity provider, access provider, profile provider, aggregation templates, and visitor configuration). Because this is a distributed cache, all the nodes should have same values for the following properties inside this file:

  • multicastGroupPort

  • multicastGroupAddress

Oracle recommends that you set the values for these properties in the visitors-cache.xml file on the primary cluster node and then copy the file to each secondary node. You could also do this manually, by making the change in the file locally, on each secondary node.

The visitors-logging.xml file provides log-level setting for different loggers. To have a consistent logging experience across nodes, Oracle recommends that all nodes use same file or propagate changes made on one node manually to local copies of this file on all nodes.

Note:

Because changes you make to a WAR file are not retained during redeployment, WAR file changes need to be copied over after each redeployment of the web applications. It is generally recommended to deploy the static artifacts such as images and stylesheet files onto the web server.