1. Developing with Oracle WebCenter Sites
  2. Developing WebCenter Sites: Visitor Services
  3. Developing WebCenter Sites: Visitor Services

42 Developing WebCenter Sites: Visitor Services

Oracle WebCenter Sites: Visitor Services fetches and compiles visitor profile information. Marketers use this information to orient their website content, such as product information and marketing campaigns, toward visitor needs.

Topics:

Note:

For information about Visitor Services-specific terms, see the Visitor Services Glossary.

42.1 Visitor Services Overview

Visitor's profile information is typically captured across different systems within customers’ online presence. For example, a visitor may have recently viewed an Eloqua email, downloaded a CRM white paper, or logged into Facebook or Google. Each online activity collects a different set of visitor attributes. Visitor Services collects these visitor attributes and serves this information through an aggregate template.

The Visitor Services component provides discovery, aggregation, and query features that you can use for targeting. Choosing selected attributes from different visitor profiles, you can create as many aggregated templates as the marketers need. Marketers use the visitor information to target content on WebCenter Sites delivered pages.

Visitor Services Tasks for Developers

Visitor Services configuration primarily involves developer tasks organized on the Visitors Admin node of the Admin interface, as shown below. For more information about Visitor Services from a marketer perspective, see Understanding WebCenter Sites: Visitor Services in Using Oracle WebCenter Sites.

Description of svs_nodes.png follows
Description of the illustration svs_nodes.png

Developer tasks include:

  • Configure the Visitor Services URL as described in Configuring the Visitor Services URL.

    To configure Visitor Services with WebCenter Sites, you need to identify the Visitor Services URL configured during installation. See Configuring the Visitor Services URL.

  • Configure an identity provider for the single sign-on system (SSO) to authenticate site visitors to Visitor Services. See Configuring an Identity Provider.

    Visitor Services ships with an Oracle Access Manager identity provider for integration with Oracle Access Manager. You can also create a custom identity provider, as described in Creating a Custom Identity Provider: Example.

  • Configure access providers to authenticate profile information requests. See Configuring Access Providers.

    An access provider qualifies the REST calls made from the application to Visitor Services. Oracle recommends using an access provider to maintain a secure connection between Visitor Services and WebCenter Sites.

  • Create profile providers to compile and enrich visitor profiles.

    A profile provider allows a visitor identity to be associated with a visitor profile. You implement and configure profile providers for specified repositories in Visitor Services, and write enrichment rules to collect visitor information from all profile providers. Visitor Services ships with an Eloqua profile provider for integration with the Eloqua Cloud Marketing Service, an Oracle Access Manager profile provider for integration with Oracle Access Manager, a Facebook profile provider. See Configuring One or More Profile Providers and About the Profile Providers and Enrichment Service.

  • Create aggregate templates that determine which data, based on visitor profiles, is returned to the site visitors. See Creating One or More Aggregation Templates and About the Identity Providers.

    An aggregation template links visitor profiles and lets you combine information from different visitor profiles. Developers write aggregation rules and templates that combine profile information from visitor profiles.

  • Configure how visitor profiles from Visitor Services are requested and used.

    To make use of visitor profiles, WebCenter Sites components must request them via Visitor Services APIs (REST, JAVA, or JavaScript) during runtime. Visitor Services comes integrated with:

    • Engage: Use visitor profiles to determine Engage segments and provide recommendations. For example, a marketer might use visitor profile attributes such as age and income to create segments and deliver recommendations. For anonymous visitors, create segments for them based on attributes such as device used to access the site, time zone, locale, browser, referrer (Facebook, Twitter, Bing), or IP address. See Working with Engage Assets in Using Oracle WebCenter Sites.

    • A/B Testing: Use visitor profiles for determining segments, then use the segments to target visitors for the A/B test. See Working with A/B Testing in Using Oracle WebCenter Sites.

Visitor Services API References

  • Visitor Services Java API: Provides Java API documentation for client developers of Visitor Services to write custom identity provider, access provider, and profile provider interface implementations.

  • Visitor Services Client Java API: Provides Java API documentation for developers of applications such as Oracle WebCenter Sites and Engage that communicate with Visitor Services to get visitor profile information.

42.2 Configuring the Visitor Services URL

Before you can use Visitor Services, you need to configure its instance with your WebCenter Sites. The Property Management tool available in the Admin interface lets you quickly configure your Visitor Services instance.

  1. Log into the Admin interface.
  2. On the tree, expand the Admin node and the System Tools node.
  3. Double-click the Property Management node.

    The Property Management Tool page is displayed.

  4. From the Category drop-down list, choose Visitors and then click Search.

    The Properties section on the Property Management Tool page is populated with the properties for the Visitors category.

  5. Under the Key column, click visitors.rest.url.
  6. In the Value field, enter the Visitor Services instance URL in format: http://<visitorserviceshost>:<visitorservicesport>/visitors-webapp.

    Figure 42-1 Properties section of the Property Management Tool Page

    Description of Figure 42-1 follows
    Description of "Figure 42-1 Properties section of the Property Management Tool Page"
  7. Click Save .

    Your Visitor Services instance has been configured.

    Figure 42-2 visitors.rest.url Property Configured in the Properties Section

    Description of Figure 42-2 follows
    Description of "Figure 42-2 visitors.rest.url Property Configured in the Properties Section"

42.3 Configuring an Identity Provider

An identity provider finds the status of visitor authentication to Visitor Services. You can configure an identity provider using the OSGi bundle or develop your own identity provider as an OSGi bundle.

Note that Visitor Services supports authenticated and unauthenticated visitors as follows:

  • Authenticated visitors: These visitors are authenticated through identity providers. For example, a valid OAM user can be authenticated by an identity provider created to identify those OAM users that reach Visitor Services via a request call.

  • Unauthenticated/Anonymous visitors: This type of visitor never signs in, so Visitor Services has no attributes for this user. While Visitor Services cannot identify anonymous visitors, if a client application (for example, WebCenter Sites) decides to register them explicitly, these visitors become authenticated visitors after their registration. The client applications can save attributes on their behalf post registration. The website can store the Visitor Services-generated visitor ID in a cookie and use it for associating the user sessions.

42.3.1 Configuring Identity Provider Settings

Whether you use the out of the box identity provider or create your own provider, the identity provider’s settings described in this topic must be set in the Admin interface.

To configure an identity provider:

  1. Log into the Admin interface.
  2. On the tree, expand the Visitors Admin node.
  3. Double-click the Identity Providers option.

    The Identity Providers List page is displayed.

  4. Click Add New.

    The Visitors Identity Providers form is displayed.

  5. In the Name field, enter a meaningful name.
  6. In the Implementation box, either drop the implementation OSGi bundle in the Drop File Here region, or click Browse to upload it. For example, to configure OAM identity provider, use the OAMIdentityProvider implementation provided with the Visitor Services application.
  7. In the Configuration box, enter the configuration parameters of the identity provider you are creating. For example, if you are configuring OAM identity provider, the parameters are:

    • Visitor Identity Header name: oam.headers.dn=OAM_REMOTE_USER

    • Identity Storage Header name: oam.headers.identityStorage=OAM_IDENTITY_DOMAIN

    • Anonymous Visitor Identity Header value: oam.guest=Anonymous

    Figure 42-3 Visitors Identity Providers Form

    Description of Figure 42-3 follows
    Description of "Figure 42-3 Visitors Identity Providers Form"

    When the LDAP embedded with OAM is down and requests made through OAM do not reach Visitor Services, the Visitor Services application does not return any response about the LDAP’s unavailability.

  8. Click the Save icon.

    The new identity provider is available on the Identity Providers List page.

    To enable an identity provider for this site, first go to the Identity Providers List by double-clicking the Identity Providers node in the Admin tree on the left. Then, choose the Enable radio button for the provider you want to enable. At a time, only one identity provider can be enabled for a site.

42.3.2 Integrating Oracle Access Manager (OAM) with Visitor Services

Before performing steps described in this section, ensure that you have configured the OAMIdentityProvider provided with Visitor Services. The OAM identity provider enables Visitor Services to communicate with OAM. Steps to configure this provider are described in Implementing and Configuring Identity Providers.

After integrating OAM with Visitor Services as described in this section:

Note:

The OAM-Visitor Services integration must be a standard implementation.

To integrate OAM Mobile & Social with Visitor Services:

  1. Go to the OAM Admin console: http://host:port/oamconsole.

  2. Click the Application Domains tab, then create an application domain.

    Figure 42-4 Applications Domains

    This images shows the Application Domains page.

  3. To create protection policies:

    • Under the Application Domains page, on the Authentication Policies tab, click Create Authentication Policy.

      Figure 42-5 Authentication Policies

      Application Domains — Authentication Policies tab.

    • On the Authentication Policy page, from the Authentication Scheme drop-down list, choose OICSchema and call it oicpolicy.

    • Click Add for Resources, add /index.html, and then click Apply.

      Figure 42-6 Authentication Policy - Authentication Scheme

      This image shows the Authentication Policy page.

    • On the Authentication Policy page, click Protect Resource Policy.

    • From the Authentication Scheme drop-down list, choose LDAPSchema so that OAM uses LDAP as the AuthenticationModule.

    • Click Add for Resources, add /sites/avi/home.html , /**. and then click Apply.

      Protected Resource Page. Shows two resources.

    • From Launch Pad, open Authentication Module. Then, verify identity storage used for the LDAP module (see the administrator’s guide for Oracle Access Manager). This storage is used when configuring the LDAP profile provider.

  4. Under Search, from the Resource Type drop-down list, select HTTP and then click Search. Add the following resources if the search result doesn't return them.

    • Add the following resources (see image below).

      • /index.html

      • /visitor-webapp/rest/*/visitor/**

      • /visitors-webapp/rest/*

      • /visitors-webapp/rest/*/visitor/current/**

      • /sites/avi/*.*

      • /visitors-webapp/**

      • /sites/avi/home.html

      • /**

    • For /visitors-webapp/rest/*/visitor/**, choose the protection level as Excluded.

    • For /visitors-webapp/rest/**, choose the protection level as Unprotected.

    Figure 42-7 HTTP Resource Type

    Application Domains — Resources tab.

  5. Create an SSO agent:

    • On the Launch Pad, click SSO Agent Registration.

    • Select 11g Webgate.

    • Complete the form.

      Figure 42-8 svsSSOAgent

      This image shows the SSO Agent page.

  6. Configure Oracle Http Server (OHS):

    1. Go to Enterprise Manager: http://host:port/em.

    2. In the navigation tree, expand Web Tier, then select the OHS instance.

    3. To create a new virtual host, choose Administration and then choose mod_wl_ohs Configuration from the Oracle Http Server drop-down menu.

      Figure 42-9 mod_wl_ohs Configuration

      Oracle HTTP Server — mod_wl_ohs page.

    4. Edit the mod_wl_ohs.conf file.

    5. In the section containing the WebLogicCluster directive, set DynamicServerList to OFF.

    6. Save the mod_wl_ohs.conf file and restart OHS.

  7. Configure Mobile and Social:

    1. From Launch Pad, open Social Identity.

    2. Create an application profile with the same name that you specified while creating the application domain.

    3. Map application user attributes and Internet identity provider user attributes.

      Figure 42-10 Application User Attribute and Internet Identity Provider User Attributes Mapping

      The Application User Attribute and Internet Identity Provider User Attributes Mapping page.

Configure the profile provider, as described in Implementing and Configuring Profile Providers and Enrichment Rules.

For your reference here is a sample code that lets you use the Java Script client with OAM:

<html>

<head>
    <title>Sample  Page</title>
	//Assuming OAM is at 'http://<host>:<port>',(Actual Visitor Service application may be deployed somewhere else. Its location must be registered with OAM),
	//use OAM server in URLs for Visitor Services to go to the Visitor Services application via OAM so that the identity token set by OAM is available to Visitor Services.
    <script src="<host>:<port>/visitors-webapp/js/client.js"></script>
</head>

<body>

<script type="text/javascript">

    var handleSuccess = function( visitorId )
         {
          // Got visitorId 
           console.log("visitor id received from visitor Services = "+visitorId);
         };
		 
    var handleError = function(error)
	 {
	   conole.log(error.errorCode);
	 };
      


     var client = new com.oracle.sites.visitors.Client("<host>:<port>/visitors-webapp"); //URL having OAM instance as server part
     client.getVisitorId(handleSuccess,handleError);
</script>

</body>

</html>

Verify OAM-Visitor Services integration

  1. Get a visitor Id using the Visitor Services Javascript client. For this, a page in WebCenter Sites, which is protected in OAM through policy 'protected', can be called via OHS so that the user is asked by OAM to log in. The use provides his credentials and lands on the page where the Javascript client code is present. The visitor ID received by the Javascript client is an OAM authenticated visitor ID. Use the OHS virtual host and port instead the host and port of Visitor Services. Do not specify any external ID because OAMIdentityProvider gets it from request. Generate visitor ID for each call.

  2. Log into Visitor Services using an existing user.

  3. Get the visitor ID as described in step 1. User ID should be generated on the first call, and it should be the same for each call.

  4. Try to get the visitor's linked profiles using the Visitor Services REST API for the user generated in step 3.

42.3.3 Creating a Custom Identity Provider: Example

OAM identify provider is provided with Visitor Services out of the box. This section guides you to implement a custom identify provider with the help of an example.

The following points can guide you to implement a sample identity provider:

  • Every identity provider must be an OSGi bundle, and this bundle should consist of the provider implementation and an activator to register the provider to Felix runtime.

  • The implementation class should first implement the identity provider interface and then the profile provider interface. It must implement the identity provider interface with at least one of the following methods fully implemented:

    • Identity getVisitorIdentity(String externalId);

    • Identity getVisitorIdentity(HttpServletRequest request);

  • The method shown in the following example returns the identity (just the Distinguished Name (dn)), which is passed to the profile provider to fetch the profile information. 

    package com.oracle.sites.visitors.api.providers;

import ...
public interface IdentityProvider
{
String getProviderName();
void setProviderConfig(Properties config);
Identity getVisitorIdentity(HTTPServletRequest request);
}

  • The following is a sample code to implement an identity provider. This implementation uses an external Id consisting of a provider name and a user dn: 

    public class SampleIdentityProvider implements IdentityProvider
{
     private static final String PARAMETER_EXTERNAL_ID_NAME = "parameter.external_id";
     private static final String COOKIE_NAME_ATTRIBUTE_NAME = "cookie.external_id";

     @override
     public Identity getVisitorIdentity)HttpServletRequest request)
     {
         String externalId = getExternalIdFromCookie(request);

         if (null ==externalId || externalId.isEmpty())
         {
              externalId = getExternalIdFromParams(request);
         }
                  //Returns an identity object based on external id
         return getVisitorIdentity(externalId);
         }

    The system calls the profile provider with the identity object returned above. Every time a user requests for the visitor Id, the external id (provider and dn) is stored in the cookie for the future use.

  • OSGi bundles require an activator class to activate the code contained in the bundles. Write an activator class that can register the sample identity provider. 

    public class Activator implements BundleActivator {
    /**
     * Implements BundleActivator.start(). Prints
     * a message and adds itself to the bundle context as a service listener.
     * @param context the framework context for the bundle.
    **/
    public void start(BundleContext context)
    {
        context.registerService (ProfileProvider.class.getName(),
                new SampleProfileProvider(context.getBundle().getLocation()), null);
    }
    
    /**
     *Implements BundleActivator.stop().Prints a message
     *and removes itself from the bundle context as a service listener.
     *@param context the framework context for the bundle.
    **/
    public void stop(BundleContext context)
    {
    }
}

  • Configure the identity provider by following the steps described in Configuring an Identity Provider.

42.4 Configuring an Access Provider

An access provider controls applications’ access to visitor profile information. The access provider service works in pair with the REST client. For example, for the container protection authentication you should upload the access provider bundle with basic authentication settings on Visitor Services, and set the same authentication type on the REST client.

See Access Provider Reference.

Visitor Services ships with a basic LDAP access provider for authentication against an LDAP directory.

Follow the steps in this section to enable an access provider to use with Visitor Services:

To configure an access provider:
  1. Log in to the Admin interface.
  2. On the tree, expand the Visitors Admin node.
  3. Double-click the Access Providers option.

    The Access Providers List page is displayed.

  4. Click Add New.

    The Visitors Access Providers form is displayed.

    Figure 42-11 Visitors Access Providers Form

    Description of Figure 42-11 follows
    Description of "Figure 42-11 Visitors Access Providers Form"
  5. In the Name field, enter a meaningful name.
  6. In the Implementation box, either drop the implementation OSGi bundle (For example, ContainerBasicAccessProvider) in the Drop File Here region, or click Browse to upload it.

    The access provider is a OSGi bundle containing the files required by Visitor Services. This OSGi bundle is an actual JAVA-based implementation of the communication required between Visitor Services and the desired storage. The access provider OSGi bundle consists of the following:

    • The Activator class which is the entry point of the OSGi framework.

    • The MANIFEST.mf file with OSGi Headers described in this table:

      Table 42-1 OSGi Headers in MANIFEST.mf File

      Header Name Description

      Bundle-Name

      Name of the access provider.

      Bundle-SymbolicName

      com.sample

      Bundle-Description

      Description of the access provider

      Bundle-ManifestVersion

      1

      Bundle-Version

      1.0.0

      Bundle-Activator

      com.sample.Activator

      Import-Package

      org.osgi.framework;version=4.2.1,org.json, com.oracle.sites.visitors.api.providers, com.oracle.sites.visitors.api.providers.beans

    • The name of the configuration file must be the same: accessProviderConfig.properties. This file must contain key=value pairs of properties required by current implementation of the access provider. The configuration file must always exist in the OSGi bundle, even though blank.

  7. In the Configuration box, enter the configuration of the access provider you are creating. For example, for ContainerBasicAccessProvider, enter role=role Configured In Container for Visitors Services.
    If Sitewrapperapi is used, then you must also set the following properties in the Property Management Tool: wcsites.visitors.auth.password, visitors.rest.authalias, visitors.rest.authtype, visitors.rest.authheader.
  8. Click the Save icon.
    The new access provider is available on the Visitors Access Providers page.
  9. To enable this access provider for this site, go to the Access Providers List by double-clicking the Access Providers node in the Admin tree on the left. Then, choose the Enable radio button for the provider you want to enable. At a time, only one access provider can be enabled for a site.

42.5 Configuring One or More Profile Providers

A profile provider lets you associate a visitor identity with a visitor profile. Visitor Services ships with an Eloqua profile provider that you integrate with Eloqua, an Oracle Access Manager profile provider for Oracle Access Manager, and a sample profile provider.

See Profile Provider Reference.

You can configure a profile provider by:

Note:

Do not change the attribute names of the profile providers once these attributes are set.

42.5.1 Configuring Profile Provider Settings and Enrichment Rules

To configure a profile provider and enrichment rules:

  1. Log in to the Admin interface.
  2. On the tree, expand the Visitors Admin node.
  3. Double-click the Profile Providers option.

    The Profile Providers List page is displayed.

    Figure 42-12 Profile Providers List

    Description of Figure 42-12 follows
    Description of "Figure 42-12 Profile Providers List"
  4. Click Add New.

    The Visitors Profile Providers form is displayed.

  5. In the Name field, enter a meaningful name for the profile provider you are configuring. In case of the OAM identity provider, the name of the profile provider should be the same as that of the embedded LDAP store.
  6. Next to the Implementation field, click Browse to upload the profile provider OSGi bundle. If LDAP is used, then upload the LDAP profile provider provided with Visitor Services, otherwise use your custom implementation.

    The profile provider OSGi bundle consists of the following:

    • The Activator class which is the entry point of the OSGi framework.

    • The MANIFEST.mf file with OSGi Headers.

      Table 42-2 OSGi Headers in MANIFEST.mf File

      Header Name Description

      Bundle-Name

      Name of the profile provider.

      Bundle-SymbolicName

      com.sample

      Bundle-Description

      Description of the profile provider

      Bundle-ManifestVersion

      1

      Bundle-Version

      1.0.0

      Bundle-Activator

      com.sample.Activator

      Import-Package

      org.osgi.framework;version=4.2.1,org.json, com.oracle.sites.visitors.api.providers, com.oracle.sites.visitors.api.providers.beans

    • The name of the configuration file must be the same: profileProviderConfig.properties. This file must contain key=value pairs of properties required by current implementation of the profile provider. The configuration file must always exist in the OSGi bundle even if the file is blank.

  7. In the Configuration box, enter configuration parameters for your profile provider. If you are using the LDAP profile provider, see this table:

    Table 42-3 LDAP Profile Provider Configuration Parameters

    Parameter Value

    LDAP Address

    Format: ldap://<host>:<port>/.

    Base Distinguished Name for users

    BaseUserDN=cn=Users,dc=com

    Distinguished Name of the manager (admin)

    AdminDN=cn=admin,dc=com

    Password

    Password of the manager (admin). AdminPassword=password

    LDAP attribute used as the user login name

    Default is uid. LoginUserAttribute=uid.

    Supported LDAP objectClasses

    ObjectClasses=top;inetOrgPerson

    LDAP profile attributes

    ProfileAttributes=cn,sn,displayName,mail,title,givenName,name

    CaseAwareSearch

    		 Allowed values are true or false. Determines whether the search on LDAP is case sensitive or case insensitive.

    Figure 42-13 Visitors Profile Providers Form

    Description of Figure 42-13 follows
    Description of "Figure 42-13 Visitors Profile Providers Form"
  8. In the Enrichment Rule box, enter enrichment rules you wish to apply on visitor profiles. Enrichment rules includes attributes that define visitors profile. These rules are based on multiple visitor profiles available in different storages, as well as arbitrary attributes that customers wish to add to visitor data that Visitor Services will be collecting and providing to applications.

    To configure enrichment rules for LDAP, CRM, and Eloqua profile providers, dn used in LDAP profile provider must be the same as the name in the CRM profile provider, the CRM profile provider includes the email attribute, and the Eloqua profile provider includes the Id attribute. Thus, to allow enrichment process to run, profile providers should be configured as follows:

    • Add the following enrichment rule to the LDAP profile provider: dn=CRM:name

    • Add the following enrichment rules in CRM profile provider:

      • name=LDAP:dn

      • Id=ELOQUA:Id

    • You can write the enrichment rule for the Eloqua profile provider based on the Id attribute. For example:

      Eloqua enrichment rule for LDAP:

      Id=eloqua:Id

      Eloqua enrichment rule for unknown profile providers:

      dn=eloqua:id

    Consider the following:

    • In case of LDAP profile provider, the LDAP embedded with OAM does not support search for some attributes such as homePhone, employeetype, departmentnumber, homepostaladdress, c, l, employeenumber. Therefore, enrichment rules based on these attributes may not work.

    • Oracle Virtual Directory's search functionality supports only those attributes that use ASCII characters.

  9. Click the Save icon.

    A new row is created in the Providers table. The Visitor Services log is updated confirming that the new provider has been added.

    The new profile provider is available for editing on the Profile Providers List page.

  10. To enable this profile provider, go to the Profile Providers List by double-clicking the Profile Providers node in the Admin tree on the left. Then, select Enable check boxes for the providers you want to enable. You can enable multiple profile providers simultaneously.

Note:

The default value of the Profile Update Period is set to 1. It means that the visitor’s profile will not be updated until 1 day and it will not show the linked enrichment profile immediately. If the value of the Profile Update Period is set to 0, then it will show the linked profile immediately.
42.5.1.1 About Configuring Eloqua Profile Provider

To use the Eloqua profile provider, you must:

  1. Follow the procedure described in Configuring Profile Provider Settings and Enrichment Rules to create a profile provider for Eloqua.

    Ensure that you enter the details of the Eloqua provider instance in the Configuration box.

    For example: 
    ###################################################################################################
#### ELOQUA SETTINGS
###################################################################################################

## Auth Settings
#######################################
#
# Client's Company name 
#
company = OraclePOC 

#
# Client's user name 
#
user =  username

#
# Client's user password 
#
password =  password


## Proxy Settings
#######################################
#
# Use proxy in provider
#
useProxy = true

#
# Proxy server host
#
proxyHost = www-proxy.us.oracle.com

#
# Proxy server port
#
proxyPort = 80

#
# Proxy server type
# This can be "DIRECT", "HTTP", or "SOCKS"
#
proxyType = HTTP

## Search Settings
#######################################
#
# Eloqua REST URL
#
restUrl = https://secure.eloqua.com/API/REST/1.0

#
# Depth or level of visitor detail returned. 
# This can be "minimal", "partial", or "complete". 
# 
searchDepth = partial

  2. To enable the Eloqua Profile Provider profile provider, go to the Profile Providers List by double-clicking the Profile Providers node in the Admin tree on the left. Then, select Enable check boxes for Eloqua Profile Provider .

Note:

Eloqua does not support email-based search. Therefore, enrichment rules based on the email field in Eloqua do not work. Only Id-based search is supported. Ensure that the identity provider is configured in such a way that it identifies the user Id in Eloqua so the profile provider can fetch visitor profile details.

42.5.2 Creating a Custom Profile Provider: Example

Visitor Services comes packaged with LDAP profile provider, Eloqua profile provider, and a sample profile provider. The following points can guide you to implement a custom CSV profile provider:

  • Every provider must be an OSGi bundle, and this bundle should consist of the provider implementation and an activator to register the provider to Felix runtime.

  • The implementation class should first implement the identity provider interface and then the profile provider interface.

  • The profile provider method shown in the following example fetches the profile information.

    public interface ProfileProvider
{
String getProviderName();
RawProfile getProfile(String dn);
List<RawProfile> search(String attribute, String value);
void setProviderConfig(Properties config);

  • Write an activator class that can register the sample profile provider:

    public class Activator implements BundleActivator {
    /**
     * Implements BundleActivator.start(). Prints
     * a message and adds itself to the bundle context as a service listener.
     * @param context the framework context for the bundle.
    **/
    public void start(BundleContext context)
    {
        context.registerService (ProfileProvider.class.getName(),
                new SampleProfileProvider(context.getBundle().getLocation()), null);
    }
    
    /**
     *Implements BundleActivator.stop().Prints a message
     *and removes itself from the bundle context as a service listener.
     *@param context the framework context for the bundle.
    **/
    public void stop(BundleContext context)
    {
    }
}

  • In the following sample implementation, the dn passed for the identity object can be used to get the raw profile information. The profiles are loaded from *.csv file. 

    ID,Name,Email,Address,Country,City
1,Alek,Alek.Z@mycompany.com,Kyiv,Ukraine,Kyiv
2,Avi,avi.n@mycompany.com,Gachibowli,India,Hyderabad
3,Joe,Joe.d@mycompany.com,Miyapur,India,Hyderabad
4,Reva,reva.p@mycompany.com,Kukatpally,India,Hyderabad

@Override
public RawProfile getProfile(String dn) {
    List<CSVProfile> profiles = csvManager.getProfiles();
    CSVProfile selected = null;
    for (CSVProfile p : profiles) {
        if (p.getName().equalsIgnoreCase(dn)) {
            selected = p;
            break;
        }
    }

    if (selected == null)
        return null;
    RawProfile rawProfile = new RawProfile();
    rawProfile.setUserId(selected.getId());
    rawProfile.setProviderId(getProviderName());
    rawProfile.setAttributes (getAttributes (selected));
    return rawProfile;
    }

    private JsonObject getAttributes(CSVProfile csvProfile)
    {
        JsonObject attributes = new JsonObject();

        attributes.addProperty("email", csvProfile.getEmail());
        attributes.addProperty("address", csvProfile.getAddress());
        attributes.addProperty("country", csvProfile.getCountry());
        attributes.addProperty("city", csvProfile.getCity());
        return attributes;
     }

  • Write an activator class that can register the sample profile provider:

    public class Activator implements BundleActivator {
    @Override
    public void start(BundleContext bundleContext) throws Exception {
         bundleContext.registerService(ProfileProvider.class.getName(),
                  new CSVProfileProvider(bundleContext.getBundle().getLocation()), null);
    }

    @Override
    public void stop(BundleContext bundleContext) throws Exception {

    }
}

  • Configure the profile provider by following the steps described in Configuring One or More Profile Providers.

42.6 Creating One or More Aggregation Templates

Based on visitor profiles, an aggregation template helps determine what information should be sent to the site visitors. For example, you can call an aggregation template from Engage to identify the attributes that you want to use for recommendations. You can create aggregation templates using Velocity or JavaScript.

See Aggregation Template Reference.

To configure aggregation templates:
  1. Log in to the Admin interface.
  2. On the tree, expand the Visitors Admin node.
  3. Double-click the Aggregation Templates option.

    The Aggregation Templates List page is displayed.

    Figure 42-14 Aggregation Templates List

    Description of Figure 42-14 follows
    Description of "Figure 42-14 Aggregation Templates List"
  4. Click Add New.

    The Visitors Aggregation Templates form is displayed.

  5. In the Name field, enter a meaningful name for the template you are configuring.
  6. In the Language field, choose either Velocity or JavaScript.
  7. In the Template box, enter aggregation template code. The following example shows a sample aggregation template that compiles visitor information from multiple profile storages. This sample is a Velocity code.

    Sample Velocity Code for Creating an Aggregation Template

    #set( $sn ="Not Provided")
       #if(${profiles.LDAPProfileProvider.get(0).sn} != "null")
       #set( $sn = ${profiles.LDAPProfileProvider.get(0).sn.getAsString()})
       #end

       #set( $displayName ="Not Provided")
       #if(${profiles.LDAPProfileProvider.get(0).displayName} != "null")
              #set( $displayName = ${profiles.LDAPProfileProvider.get(0).displayName.getAsString()})
         #end

       #set( $mail ="Not Provided")
       #if(${profiles.LDAPProfileProvider.get(0).mail} != "null")
              #set( $mail = ${profiles.LDAPProfileProvider.get(0).mail.getAsString()})
         #end

       #set( $homePhone ="Not Provided")
       #if(${profiles.LDAPProfileProvider.get(0).homePhone} != "null")
              #set( $homePhone = ${profiles.LDAPProfileProvider.get(0).homePhone.getAsString()})
          #end

       #set( $name ="Not Provided")
       #if(${profiles.LDAPProfileProvider.get(0).name} != "null")
              #set( $name = ${profiles.LDAPProfileProvider.get(0).name.getAsString()})
         #end

       #set( $description ="Not Provided")
       #if(${profiles.LDAPProfileProvider.get(0).description} != "null")
              #set( $description = ${profiles.LDAPProfileProvider.get(0).description.getAsString()})
       #end

#else
        #set( $otherProvider = "other profile provider used.")
#end

#if (${profiles.has("LDAPProfileProvider")})
{
"Name ": "$name",
"displayName ": "$displayName",
"description ": "$description",
"sn ": "$sn",
"mail ": "$mail",
"homePhone ": "$homePhone"
}
#else
{
"otherProvider ": "$otherProvider"
}
#end

    The following example shows a sample aggregation template that compiles visitor information from multiple profile storages. This sample is a Javascript code that does the same as the Velocity code above:

    Sample JavaScript Code for Creating an Aggregation Template
    function aggregate()
{
    var result={};
    if(profiles.get("LDAPProfileProvider"))
    {
        var NOT_PROVIDED_LABEL = "Not Provided";
        var internalAttrs = JSON.parse(profiles.get("LDAPProfileProvider").get(0).getAttributes());

        result.Name = internalAttrs.name || NOT_PROVIDED_LABEL;
        result.displayName = internalAttrs.displayName || NOT_PROVIDED_LABEL;
        result.description = internalAttrs.description || NOT_PROVIDED_LABEL;
        result.sn = internalAttrs.sn || NOT_PROVIDED_LABEL;
        result.mail =internalAttrs.mail || NOT_PROVIDED_LABEL;
        result.homePhone = internalAttrs.homePhone || NOT_PROVIDED_LABEL;

    }
    else
    {
        result.otherProvider = "other profile provider used.";
    }
    return result;
}

    Figure 42-15 Visitors Aggregation Templates Form

    Description of Figure 42-15 follows
    Description of "Figure 42-15 Visitors Aggregation Templates Form"
  8. Click the Save icon.

    The new aggregation template is available on the Aggregation Templates page.

42.7 Optimizing Experiences Using Visitor Services Data 

To help you optimize visitors’ experience, extended attributes and activities collect visitor information from multiple profiles of a visitor. You can also integrate Visitor Services with Engage. In WebCenter Sites, page authors use this information to design segments and recommendations to display relevant content to the targeted users. Marketers use Visitor Services data for targeting, testing, and analysis.

Requesting visitor information involves two steps:

  • Requesting the visitor ID.

  • Requesting the visitor profile using a specified aggregation template.

    Returns the aggregated template and specified attributes.

“Requesting visitor profile information” process flow diagram.

This section includes the following topics:

42.7.1 How WebCenter Sites Components Request Visitor Services Profile Information

To enable communication between Visitor Services and client applications such as WebCenter Sites, Visitor Services provides client APIs (Java and JavaScript) that are executed in client applications to hit Visitor Services. Out of the box, Visitor Services provides Java client for the server side and JavaScript client for the client side. Java client is used when Visitor Services and applications try to access profile information from server side. JavaScript client APIs are used when visitors, using applications from browsers, try to communicate with Visitor Services. The difference between the Java Client API and the JavaScript Client API is that the Java Client API is expected to be running inside trusted applications such as the server side code in WebCenter Sites. Therefore, these applications have the credentials available to authenticate themselves before processing some sensitive operations on the visitor data (update operation). The JavaScript Client executes inside a browser, and it is less secured. Therefore, it can read the current visitor’s information only. Visitor Services provides information about all the visitors' profiles to trusted applications. To visitors, it provides information only about themselves.

Java and JavaScript client APIs have these functions in common. However, in case of JavaScript the functions are for the current/logged in visitors.

  • GetVisitorId: Gets the visitor's ID from Visitor Services using the external ID stored in the SSO solution. In JavaScript APIs, this function is called GetCurrentVisitorId. It gets the visitor ID for the current user from Visitor Services.

  • GetAggregatedProfile: Gets the aggregated profile from Visitor Services using the existing visitor's ID. In JavaScript APIs, this function is called GetCurrentAggregatedProfile. It gets the aggregated profile for the current user from Visitor Services.

    You can set profile expiration period from 0 day to any positive number (1 = 1 day). The expiration period determines how many days the profile information fetched from external storage should remain in the Visitor Services database, until this information is refreshed. If you do not specify an expiration period, then the profile information is not refreshed at all. The General Configuration page, which is accessed through the General Configuration node under the Visitors Admin node, contains the Profile Update Period configuration. Edit this configuration to set the expiration period.

  • IsExists: Verifies if the visitor ID exists in the database. Whether a guest or a registered user with some profile exists or not, the response will be true if the visitor Id exists in the database. In JavaScript APIs, this function is called IsCurrentExists. It verifies if the visitor ID exists in the database. Whether a guest or a registered user with some profile exists in the database or not, the response will be true if the visitor Id exists in the database.

  • IsGuest: Verifies that visitor has no profiles in the database. Whether the visitor information exists or not, the response will be true in both cases. In JavaScript APIs, this function is called IsCurrentGuest. It verifies that the no visitor profile for this guest visitor exists in the database. Whether the guest visitor is stored in the database or not, the response will be true in both cases.

Java client is run at the server, while JavaScript is executed from the web browser. The URLs for both are differently structured. For example:

  • Java REST function for trusted applications: http://visitorserviceshost:visitorservicesport/visitors-webapp/rest/v1/visitor/id/690b507b-efb6-4c35-9e6e-0c9f2a28b37d/profile/aggregated/arrg

    In this URL notice id/690b507b-efb6-4c35-9e6e-0c9f2a28b37d. This is the specified visitor ID (for the logged-in visitor, current is used in its place, as shown in the next point.)

  • JavaScript REST function for non-trusted visitors: http://visitorserviceshost:visitorservicesport/visitors-webapp/rest/v1/visitor/current/profile/aggregated/arrg

    In the above URL the visitor Id path is replaced with the current context which indicates that untrusted visitor can information only about himself. All REST calls for untrusted customer include the current context.

When all applications are deployed on OAM, Oracle HTTP Protection is set to the excluded security type. If a client application requests for profile information for which the data is already prepared, Visitor Services Java client APIs' Send request (through which already prepared data is provided to these applications) can be protected through Visitor Services' own protection:

  • Container Protection: All the information about users is stored in the container storage, and Visitor Services only checks for users' roles. Oracle recommends using the container protection if client's web server allows basic authentication.

  • Visitor Services Protection: Use Visitor Services protection when a client's web server doesn't support the basic authentication mechanism.

You can also implement your own access provider using Visitor Services API and upload your provider through the Admin interface.

Note:

When a request for an aggregated or linked profile is processed with the updated param set to false, the behavior of Visitor Services for expired profiles is as follows:

  • JMS configured for Visitor Services: The current request returns old profile data while Visitor Services updates the profile in the background to refresh the profile data in sometime.

  • JMS not configured for Visitor Services: Returns the updated profile in the request call since the background processing capability is dependent on JMS.

It is recommended that each application has its own credentials for accessing REST APIs. Visitor Services verifies this access by itself. Visitor Services REST APIs for untrusted applications are secured by SSO, and in OAM the protection level is set to unprotected. Visitor Services has no protected REST resources. Oracle recommends using the Container protection.

See the Java API Reference for Oracle WebCenter Sites: Visitor Services.

42.7.2 Configuring Visitor Services with Engage

You can integrate Visitor Services with Engage to collect and provide visitor information to Engage for use in segments and recommendations. In WebCenter Sites, page authors use this information to design segments and recommendations to display relevant content to the targeted users. To get profile information from Visitor Services, developers or page authors use the Value Source field in the Visitor Attributes form which is designed to collect and store visitor information as attributes.

  1. In the Properties Management tool, ensure that Visitor Services properties are set, as described in Oracle WebCenter Sites: Visitor Services Properties in Property Files Reference for Oracle WebCenter Sites.
  2. On the Visitor Services node in the Admin interface, configure the aggregation template to be used in the recommendation or segmenting. See Creating One or More Aggregation Templates.
  3. In the Contributor interface, configure the Value Source field in the Visitor Attributes form, using Expression Language (EL) to reference the data in the aggregated template to populate the value of the visitor attribute. The visitor attribute is then used for segmenting and evaluating recommendations. For example, an EL expression in the Value Source field might look like this, where Agg_Temp is an aggregated template that collects the visitors’ addresses, street numbers/name, and house address, AnotherTemplate identifies a second aggregated template, My City is the city in which a visitor lives, and Zip Code is the city’s zip code: ${Agg_Temp.Address.PostalCode},${AnotherAggregatedTemplate["My City"].ZipCode}.  For more information about EL, see https://docs.oracle.com/javaee/6/tutorial/doc/gjddd.html.
  4. In the Recommendation Reader API, create an implementation object that includes the same attributes set up in the aggregation template. During execution, the Recommendation Reader API interacts with Visitor Services to obtain the aggregated template using the following methods:

    • readSegments: Determines the Engage segments to which the user belongs, after evaluating the visitor attributes provided or computed for the user. This method returns a list of map items where the key/value pairs in the map items describe the segments.

    • retainSegments: Determines the user’s membership in the specified Segments, after evaluating the visitor attributes provided or computed for the user. This method returns a list of map items where the key/value pairs in the map items describe the segments. This method is similar to the readSegments method, but it only considers the supplied list of segments, not all available segments.

    • readRecommendations: Evaluates the named Engage Recommendation based on the visitor attributes provided or computed for the user. This method returns a list of map items where the key/value pairs in the map describe the assets produced by the recommendation.

  5. The readSegments, retainSegments, and readRecommendations APIs set the svsvisitorid cookie if metadata used to address the call comes from Visitor Services. No cookie is set if the segments or recommendations can be computed without the use of Visitor Services. If the user has not logged in to Visitor Services, then svsvisitorid is set to a guest Id. This guest Id is used for subsequent segment or recommendation computation calls. If the user logs in, the developer needs to set the correct svsvisitorid cookie for that user. Similarly, when the user logs out, thesvsvisitorid cookie may need to be reset.

42.7.3 Linking Visitor Profiles and Managing Cookies

You can use the oracle.fatwire.integrations.svs.VisitorServiceHelper class to get the current visitor's profile information and to manage visitor cookie lifecycles.

Suppose your website contains a Home page and a My Account page. If a visitor has not logged into the Home page using the Visitor Services identity provider service, the Helper API code (helper.getProfile(ics,aggregationTemplateName,..) ) inside the page sets a guest ID in the browser as a cookie. (Note that a guest ID has no profile information.) If a link to the My Account page is protected through an authentication mechanism and the visitor logs in using the identity provider service before coming to the My Account page, then the visitor becomes an authenticated visitor. However, because the Helper API already set the guest ID in the browser cookie in the Home page, the cookie in the browser needs to be updated, by passing the updateNow param as true (helper.getProfile(ics,aggregationTemplateName,true)) inside the My Account page code. If the cookie is not updated, the My Account page won't receive the authenticated visitor ID and the related profile information, and it will keep using the guest visitor ID from the cookie.

In this example, the My Account page uses the following code:

VisitorServiceHelper helper = VisitorServiceHelper.getInstance();  
Helper. getProfile(ics,<someAggregationTemplateName>,true);
In the above code, the behavior of the true value for the Boolean param is as follows:  

  • If the visitor ID from the browser cookie is null, it indicates that the visitor landed directly on an authenticated page. Otherwise, it indicates that it is a guest ID: that the ID does not exist in Visitor Services and was cached in the local browser only. In this case, generate the new visitor ID and replace the value in the cookie.

  • If the visitor ID from the cookie exists in Visitor Services, keep using this ID, as the cookie links the two IDs. This is what happens when the guest ID in the cookie is registered explicitly before it is used in the My Account page. The code in the Home page either calls this API passing the Boolean param as false or calls another method that takes only two parameters: Helper. getProfile(ics,<someAggregationTemplateName>), where this parameter is assumed to be false by default.

42.7.4 Storing Additional Information with Extended Attributes and Activities

This section describes extended attributes and activities, and it explains how they work in Visitor Services. This section includes the following:

42.7.4.1 About Extended Attributes and Activities

Extended attributes are based on visitors' characteristics such as, language, locale, gender, and so on. Extended attributes relate to a visitor by the visitor Id and include name and value. These attributes are specific to the applications. With an application's approval, these attributes are stored in Visitor Services and used by other applications. For instance, extended attributes from Engage, if approved, can be used by any other application.

Extended activities are based on a visitor's actions on a website. For example, opening a page, performing searches, bids etc. Activities relate to a visitor by the visitor Id and include type, data, timestamp, and rating. These activities are specific to the applications. With an application's approval, these activities are stored in Visitor Services and used by other applications.

Extended activities and attributes are collected from all the profiles of the visitors. That is, if a visitor has more than one linked profile, then the get rated(latest) function returns the same result for all profiles.

Adding Activities in REST using a Java Client: Example

VisitorsClient client = new VisitorsClient(..);
Map<String,String> acts = new HashMap<>();
acts.put("product", " dell v560"); // type,data
acts.put("catalog", " laptops");
acts.put("web_page", "http://online.store.com/dell/v560");
client.addActivity("c11e123e-7fd0-4e55-9f6f-ef581e30d86a", acts);

Getting Activities in REST using a Java Client: Example

can get activities using two types:
getRated: fetches most rated activities
getLatest: fetches latest activities

getRated Method:
VisitorsClient client = new VisitorsClient(..);
List<Activity> res = client.getRated("c11e123e-7fd0-4e55-9f6f-ef581e30d86a", "product", 5);

getLatest Method:
VisitorsClient client = new VisitorsClient(..);
List <Activity>res = client.getLatest("c11e123e-7fd0-4e55-9f6f-ef581e30d86a", "product", 5);

5 - count. How many activities are needed

Adding Extended Attributes in REST using a Java Client: Example 

VisitorsClient client = new VisitorsClient(..);
Map<String,String> attrs = new HashMap<>();
attrs.put("language", "en"); // name,value
attrs.put("gender", "male");
client. saveExtendedAttributes ("c11e123e-7fd0-4e55-9f6f-ef581e30d86a", attrs);
42.7.4.2 How to Use Extended Attributes and Activities in Visitor Services

The extended attributes are available for aggregation and enrichment in Visitor Services:

  • Aggregation: Linked profiles have an additional profile named extended that contains all the extended attributes for the visitor.

  • Enrichment: You can add enrichment rules for extended attributes as Extended Attribute Configuration’s value. Visitor Services will use these enrichment rules to enrich visitors profiles. An example of extended attribute is a phone number that a visitor leaves for callback on a website. This number can be used as the visitor's extended attribute in Visitor Services to find the visitor's profiles from other profile stores. So the enrichment rules for this example would be callback_phone=LDAP:Personal_Phone.

The following process flow involves a sample online store, a visitor, and the Visitor Services activities functionality:

  1. A visitor opens a browser and navigates to http://online.store.com/dell/v560 and then selects the Dell v560 laptop.

  2. The browser sends a request to the web server for the page with URL: http://online.store.com/dell/v560

  3. The web server calculates the required data and performs the following operations:

    • (Optional) Fetches data from the database.

    • (Optional) Requests Visitor Services for the visitor's interests so they can include advertisements about the most relevant/interested (rated) goods.

      Sample code: List<Activity> res = client.getRated("c11e123e-7fd0-4e55-9f6f-ef581e30d86a", "product", 5);

      Visitor Services returns that this visitor is interested in Lenovo laptops (this information is based on previous activities).

    • Includes advertisements related to Lenovo laptops.

    • (Optional) Saves the recent activities of the visitor and requests Visitor Services to add activities:

      First: visited page = 'http://online.store.com/dell/v560'

      Second: product = 'dell v560'

      Sample Code:

      Map<String,String> acts = new HashMap<>();
acts.put("product", " dell v560'");
acts.put("web_page", "http://online.store.com/dell/v560");
client.addActivity("c11e123e-7fd0-4e55-9f6f-ef581e30d86a", acts);

42.8 Visitor Services Reference

Here is information about Visitor Services architecture, data model, aggregation templates, and providers such as Identity, Profile, Access.

42.8.1 About the Visitor Services Architecture

Visitor Services fetches visitor's profiles from different profile storages and lets developers store visitor profile information (such as city, education, interests, job profile, and so on) in a repository as different profile attributes. Visitor Services allows developers to query, enrich, store, and link visitor profiles for tracking usage and effective content targeting.

Visitor Services communicates with profile storages through profile providers that collect user data requested by applications. To access user information, Visitor Services relies on customers' single sign-on (SSO) solutions. Visitor Services uses identity providers to communicate with SSO solutions.

The following figure shows the Visitor Services architecture. Visitor Services includes the following integration layers:

  • Profile Providers: Enable communication between Visitor Services and profile storages.

  • Identity Provider: Enables communication between Visitor Services and its SSO solution.

  • REST Services: Enable communication between Visitor Services and its client APIs.

Figure 42-16 Visitor Services Architecture

The Visitor Services architecture diagram.

These integration layers are designed to support custom identity and profile providers in Visitor Services.

42.8.2 Identity Provider Reference

This reference includes the following topics:

42.8.2.1 About the Identity Providers

The Identity Provider Service enables integration between Visitor Services and the customer's SSO system to provide a communication mechanism between Visitor Services and the SSO system. When a browser requests the REST service for a visitor's profile, the REST service asks for an identify object from the identity provider. The identity provider passes on the identity object (consisting of DN and Provider) to the profile provider. If the user exists in the storage, the profile provider returns a unique Id. Otherwise, the user is considered a guest user, and therefore, a new unique Id is returned. Then, the REST service returns the visitor Id to the browser.

Using some identifiers such as a browser cookie ticket, identity provider provides the following information (called identity in Visitor Services) about the requested visitor:

  • Visitor's login name (unique name in the storage).

  • The name of the storage in which the visitor information is stored.

The identity provider functionality is an integral part of the Visitor Services application and cannot be accessed directly. Therefore, all requests about getting visitors' IDs are sent to the identity provider through REST services. Some SSO solutions work with external IDs such as cookie tickets, while others take HTTP request as an input parameter. Keep in mind that the identity provider implementation should support both situations.

42.8.2.2 How Visitor Services Identifies Visitors to Your Website

Visitor Services helps identify website visitors by providing each with a unique visitor ID. It identifies visitors as one of the following types:

  • Authenticated: Visitor Services identifies visitors who are registered with the website and can authenticate themselves through an SSO solution such as Oracle Access Manager (OAM) or SiteMinder.

  • Unauthenticated/Anonymous: This type of visitor never signs in, so Visitor Services has no attributes for this user. While Visitor Services cannot identify anonymous visitors, if a client application (for example, WebCenter Sites) decides to register them explicitly, these visitors become authenticated visitors after their registration. The client applications can save attributes on their behalf post registration. The website can store the Visitor Services-generated visitor ID in a cookie and use it for associating the user sessions.

To handle authenticated visitor profiles, Visitor Services integrates with Oracle Access Manager (OAM) out of the box, including OAM Mobile and Social. For other SSO solutions, developers can create extensions and configure custom identity providers.

See Configuring an Identity Provider.

42.8.3 Access Provider Reference

This service is used to protect the connection between Visitor Services and applications. You can configure either basic, LDAP-based authentication, or any other, to verify the authenticity of the clients that interact with Visitor Services. If authentication is not configured through the access provider service, all resources are considered public and can be accessed by anyone. It is strongly recommended that you set up the access provider in production systems.

Note:

The JavaScript API used to connect applications with Visitor Services on the client side is considered a public API, and it is not supported by the access provider service.

This reference includes the following topics:
42.8.3.1 About Container Protection and Visitor Services Protection

The access provider service provides the following types of protection:

  • Container Protection: All the information about users is stored in the container storage, and Visitor Services only checks for users' roles. Oracle recommends using the container protection if client's web server allows to configure basic authentication. The basic authentication requires the following:

    • Web Server: user = "username", password="pass", role="svsclient"

    • Access Provider: Upload the access-provider-container-basic.jar bundle. Config: role= svsclient

    • REST Client: Initialize the client with new HttpAuthentication("username "," pass ")

  • Visitor Services Protection: Information about users can be stored in LDAP, database, etc. If client's web server doesn't support the basic authentication mechanism, use the Visitor Services protection.

    The basic LDAP protection from Visitor Services requires the following:

    • Access Provider: Upload the access-provider-ldap-basic.jar bundle.

      Config:

      • LDAP connection settings are the same as LDAP profile provider.

      • auth type settings: HeaderName=Visitors-Authorization and AuthAlias=Visitors-Basic

    • LDAP with user's username along with password.

    • REST Client: Initialize the client with new VisitorsHttpAuthentication("username","pass")

42.8.3.2 How Container Protection Works

  1. Client sends a profile information request to Visitor Services. This request contains the required authentication, that is, auth token in the Authentication header.

  2. Web server halts this request and checks the Authentication header.

  3. If the user cannot be authenticated, the web server returns the 401 error.

  4. If the user is authenticated successfully, the web server adds user roles to the request.

  5. The request comes to the access provider.

  6. The function boolean check(HttpServletRequest request) checks the request for the required role.

  7. If the role check is successful, Visitor Services processes the request.

42.8.3.3 How Visitor Services Protection Works

  1. Client sends a profile information request to Visitor Services. This request contains the required authentication information.

  2. When the request comes to the access provider service, the function boolean check(HttpServletRequest request) checks the request for the authentication information.

  3. The access provider checks its storage to verify the authentication information that came with the request.

  4. Visitor Services processes the request.

42.8.4 Profile Provider Reference

This reference includes the following topics:

42.8.4.1 About the Profile Providers and Enrichment Service

Profile providers let Visitor Services fetch visitor profile information from respective repositories. The Enrichment service let Visitor Services fetch a visitor's profile information from all the repositories for which profile providers exist.

42.8.4.1.1 Profile Providers

The main task of Visitor Services is to retrieve visitor information from external storages. These storages could be text files containing some structured data, an LDAP, or external web services built on some database. To fetch visitor data from profile storages, developers can implement custom profile providers and plug them in to Visitor Services. For each profile storage, there can be one profile provider.

For customers who use LDAP and Eloqua, profile providers are available out of the box. These profile providers are available as OSGi bundles that are installed using the Admin interface. These OSGi bundles are actual JAVA-based implementation of the communication required with the desired storage.

Note:

To use Eloqua profile provider and get the visitor Id, the -DUseSunHttpHandler=true parameter must be set in the Visitor Services managed server if the application server being used is the WebLogic server.

42.8.4.1.2 Enrichment Service

The Enrichment service enables Visitor Services to search for visitor information in different profile storages using profile providers. Each profile provider is configured with a single set of rules that enable Visitor Services to search for information that all profile providers search for. Therefore, enrichment rules collect visitor information from all profile providers. These rules have the following structure: AttributeNameInCurrentProfileProvider=DifferentProfileProviderName:AttributeNameInThatProfileProvider.

When Visitor Services receives a request to get a visitor's profile from LDAP, in the background, Visitor Services also searches for this visitor's profile in CRM by enrichment rules specified for the corresponding profile. If it finds the visitor profile in CRM, it searches Eloqua using email address as the search criterion. Enrichment process is time consuming. Therefore, when a visitor's profile is retrieved from a storage using profile provider for the first time, the process runs as a separate flow in the background.

When Visitor Services has collected visitor information from multiple storages, it compiles them (based on aggregation templates) for applications such as Engage.

42.8.4.1.3 How Profile Provider and Enrichment Services Work

The figure below shows how Visitor Services communicates with profile providers to get raw profiles from profile storages and apply enrichment rules to the profiles.

Figure 42-17 Process Flow between Visitor Services and Profile Providers

Depicts communication flow between Visitor Services and Profile Providers.

Procedure based on the Process Flow Depicted in the figure above:

  1. A visitor tries to log into Facebook.

  2. The login request is passed via the SSO solution to the Facebook login page.

  3. Visitor's credentials are passed to the SSO solution.

  4. The session starts.

  5. The website requests Visitor Services for visitor ID.

  6. The SSO solution passes visitor's identity to Visitor Services.

  7. Visitor Services requests the Facebook profile provider for visitor's Facebook profile.

  8. The Facebook profile provider gets the visitor's Facebook profile from the Facebook profile storage.

  9. The Facebook profile provider returns the raw Facebook profile to Visitor Services.

  10. The raw Facebook profile is saved to Visitor Services database.

  11. Visitor Services gets enrichment rules for Facebook profile provider.

  12. Visitor Services requests Google profile provider for Google profile.

  13. The Google profile provider gets the visitor's Google profile from the Google profile storage.

  14. The Google profile provider returns the raw Google profile to Visitor Services.

  15. Google profile and Facebook profile are linked and saved in Visitor Services database.

  16. Visitor Services gets enrichment rules for Google profile provider.

  17. Visitor Services sends the visitor ID to the website.

42.8.4.2 How Visitor Services Gathers and Enriches Visitor Attributes from Multiple Channels

Using profile providers, Visitor Services searches for and fetches visitor data from multiple profile stores such as LDAP, Facebook, Eloqua, and CRM. Profile providers for LDAP and Eloqua are provided. For other profile stores, developers can create and configure custom profile providers.

For each visitor a profile provider finds, Visitor Services creates a raw visitor profile, with the visitor ID and attributes found. For example, a visitor's name and email may come from an LDAP profile provider, and his or her shipping address may come from a CRM provider.

To help build a comprehensive visitor view, Visitor Services can search for and gather visitor attributes from profile providers through profile enrichment, and link visitor profiles. For example, for a visitor who logged in through OAM, Visitor Services might find an email address in an LDAP provider profile and search for a matching email address in an Eloqua profile.

See Configuring One or More Profile Providers.

42.8.5 Aggregation Template Reference

This reference includes the following topics:

42.8.5.1 About Aggregation Templates

An aggregation template is used to aggregate profile attributes from one or more profile providers defined in Visitor Services. For example, different profile storages use different names for the same attributes. A visitor's name and email Id may be different in Google+ and Facebook. The Visitor Services aggregation service provides aggregation templates that contain the following parameters to identify the attributes of the same types irrespective of how they are named across different profiles:

  • Metadata of the profile (List of attributes)

  • Set of rules to combine information from different profiles

The requests made to the aggregation service go through the Visitor Services API to which clients send visitor IDs and the aggregation templates. Each client has its own profile structure irrespective of the visitor profile currently available in Visitor Services. The aggregation service builds a profile using the application's template. An aggregation template is a set of required attributes and rules using which attributes are collected and compiled from different raw profiles. The structure of the aggregated profile is always the same regardless of the list of available profiles in Visitor Services for that visitor and regardless of the structure of raw profiles from different profile providers.

42.8.5.1.1 How the Aggregation Service Works

The figure below shows how the aggregation service gets all linked profiles and the required template when requested.

Figure 42-18 Process Flow: How the Aggregation Service Works

Depicts how the aggregation service works.

Procedure based on the Process Flow Depicted in Figure 42-18:

  1. To get an aggregated profile of a visitor with the specific attributes, website provides the visitor ID and the aggregation template name to the REST service.

  2. The REST service sends the visitor ID and aggregation template name to the aggregation service.

  3. The aggregation service gets all the linked profiles available for the visitor ID from the Visitor Services database.

  4. The aggregation service gets the aggregation template for the aggregation template name provided by the REST service.

  5. The aggregation service sends the aggregated profile based on the aggregated template to the REST service.

  6. The REST service sends the aggregated profile to the website.

42.8.5.2 How Visitor Services Merges Raw Visitor Profiles into a Single Aggregated Profile

Profile aggregation uses aggregation templates to consolidate visitor attributes from multiple visitor profiles into an aggregated profile. (Raw visitor profiles remain separate.) You can create different aggregation templates depending on business need. For example, the marketing department might request one template that provides name, email address from LDAP, and phone number from CRM, and another template that provides name from LDAP and mailing address data from CRM profiles.

In addition to combining visitor profiles from different sources, you can also use an aggregation template to use stored profile information, compute a value found (for example, total orders placed during the past year), and add the computed value as a profile attribute.

See Creating One or More Aggregation Templates.

42.8.5.3 How Visitor Services Makes Aggregated Visitor Profiles Available for Targeting, Testing, and Analysis

Visitor Services collects, links, and stores attributes into aggregated visitor profiles. To make use of the profiles, WebCenter Sites components must request them via Visitor Services APIs (Java Client and JavaScript) during the runtime.

Marketers can use visitor profiles from Visitor Services to determine and create Engage segments. For example, a marketer might use visitor profile attributes from Visitor Services such as age and income to create segments and deliver recommendations.

For unauthenticated and unknown visitors, marketers can create segments for them based on their attributes such as device used to access the site, time zone, locale, browser, referrer (Facebook, Twitter, Bing), or IP address.

42.8.6 Diagnostics

Cache Tool Resources

If you would like to see what's inside Visitor Services, you should use the debug tool.

Cache Tool Resources:

GET

http://<host>:<port>/<context>/rest/v1/cachetool/{region}/list

The resource endpoint can be used to fetch the list of all the providers currently installed in Visitor Services.

REQUEST:

Path Parameters: Name Description Format

Region: Accepts the values common and shared_cache. Common returns the list of all the installed providers, and Shared_cache returns the list of all the installed providers with the date of install/update String.

RESPONSE:

Supported Media Types: application/json

200 Response: The list of installed providers.

Example 42-1 Example 1: Fetch the list of currently installed providers

curl -i -H "Accept: application/json" -X GET
http://<host>:<port>/<context>/rest/v1/cachetool/common/list
Response:
Content-Length:1111
Content-Type:application/json

{
  "type": "cacheToolResponse",
  "status": "success",
  "entry": {
    "entry": [
{
        "key": "profileProviderConfig.pr1",
        "value": "profileProviderConfig.pr1"
      },
      {
        "key": "profileProviderConfig.pr2",
        "value": "profileProviderConfig.pr2"
      },
      {
        "key": "profileProvider.pr1",
        "value": "profileProvider.pr1"
      },
      {
        "key": "profileProvider.pr2",
        "value": "profileProvider.pr2"
      },
      {
        "key": "identityProviderConfig.identityProvider1",
        "value": "identityProviderConfig.identityProvider1"
      },
      {
        "key": "identityProvider.identityProvider1",
        "value": "identityProvider.identityProvider1"
      }
    ]
  }
}

Example 42-2 Example 2: Fetch the installed/updated time of currently installed providers

curl -i -H "Accept: application/json" -X GET
http://<host>:<port>/<context>/<rest>v1/cachetool/shared_cache/tool
Response:
 
Content-Type:application/json
 {
  "type": "cacheToolResponse",
  "status": "success",
  "entry": {
    "entry": [
      {
        "key": "profileProviderConfig.pr1",
        "value": "Fri Sep 04 12:03:41 IST 2015"
      },
      {
        "key": "profileProviderConfig.pr2",
        "value": "Fri Sep 04 12:03:41 IST 2015"
      },
      {
        "key": "profileProvider.pr1",
        "value": "Fri Sep 04 12:03:41 IST 2015"
      },
      {
        "key": "profileProvider.pr2",
        "value": "Fri Sep 04 12:03:41 IST 2015"
      },
      {
        "key": "identityProviderConfig.identityProvider1",
        "value": "Fri Sep 04 12:03:41 IST 2015"
      },
      {
        "key": "identityProvider.identityProvider1",
        "value": "Fri Sep 04 12:03:41 IST 2015"
      }
    ]
  }
}

42.8.7 About the Visitor Services Data Model

The configurations of identity, profile, and access providers are stored in the WebCenter Sites database and retrieved by Visitor Services through the Sites REST API. Visitors' raw profiles, attributes, and activities are stored in the local Visitor Services database.

WebCenter Sites database includes the tables described in the table below. These tables are created during WebCenter Sites installation.

Table 42-4 Tables in WebCenter Sites Database

Table Name Description

WCS_ProfileProviders

Contains profile providers' implementation, configuration, and enrichment rules.

WCS_IdentityProviders

Contains identity providers' implementation and configuration.

WCS_AccessPrividers

Contains access Providers' implementation and configuration.

WCS_AggregatedTemplates

Contains aggregation templates.

WCS_VisitorsConfig

Contains Visitor Services general configuration.

The local Visitor Services database includes the tables described in the table below.

Table 42-5 Tables in the Local Visitor Services Database

Table Name Description

WCS_VIS_Profiles

Contains raw profiles from profile storages, provided by profile providers.

WCS_VIS_Attributes

Contains activities registered by applications.

WCS_VIS_Activity

Contains extended attributes saved by applications.

The figure below shows the Visitor Services data model and the tables each of the databases includes.

Figure 42-19 Visitor Services Data Model

Description of Figure 42-19 follows
Description of "Figure 42-19 Visitor Services Data Model"

42.8.8 Glossary

Aggregation

The process of retrieving an aggregated profile from the raw profiles based on the aggregation rules defined in Visitor Services.

Aggregated Profile

Unique profile attributes compiled by Visitor Services from different linked profiles of a visitor.

Aggregation Template

Configurations to retrieve profile attributes from raw profiles to create an aggregated profile.

Enrichment

The process of capturing raw profiles of a visitor from all the profile storages based on enrichment rules defined in Visitor Services.

External Id

An external user identifier provided by a SSO solution.

Identity

A pair of values: visitor's profile provider name and distinguished name (DN). This pair comes from the identity provider.

Identity Provider

An entity implemented by developers which accepts an externalID to provide the profile provider name and user DN pair from the corresponding identity store to Visitor Services.

Identity Store

A storage that contains visitors' information. It could be an LDAP or a database.

Linked Profile

Data provided by Visitor Services that contains all linked raw profiles in the form of a few lines in the Visitor Services database.

Profile Provider

An entity implemented by developers to receive visitors' profiles from specific profile stores. In general, one provider is implemented per profile store.

Profile Storages

External storages that contain information about visitors' profiles.

Raw Profile

Visitor data provided by the profile provider from its profile store.

Stored Profile

An internal Visitor Services entity that contains processed profile data in the form of RawProfile, Identity, LinkId, and VisitorId.

SSO Solution

An authentication system which provides the single sign-on functionality between Visitor Services and applications. Visitor Services comes packaged with the OAM SSO system.

Visitor Services Database

The local database used by Visitor Services to store visitors' profile data and settings such as aggregation rules and mapping rules.