1. Introduction

This guide provides an overview of Web Experience Management Audit Discover.

This guide describes the steps necessary to activate the Discover Console on top of your current Web Experience Management Audit installation.

This guide provides information about the features and functionality of the new Discover Console.

1.1. Document Revision History

Topic Modification Revision Number

All

Initial Release

1.0

1.2. About WEM Audit Discover

Audit Discover is a new and fresh console where you can analyze the events recorded by Web Experience Management Audit.

This Console can be used on top of your current WEM Audit environment, as an alternative to the current Insights console.

Audit Discover currently supports the following versions of WEM audit: 8.5, 10.5, 16.0, 16.2 or any minor version to these.

This means you can install Discover on top of any of these Audit versions.

1.3. Prerequisites

Audit Discover is built and packaged as a Java jar file and can be run anywhere that Java is available. Currently Audit Discover requires Java 6 or higher and will work on either the OpenJDK or Oracle JDK.

1.3.1. Verify Java is installed

Before you can launch the application you must verify that you have Java installed. Currently Discover requires Java 7 or higher and will work on either the OpenJDK or Oracle JDK. To check that you have a working java runtime, go to a terminal and type:

java -version

You should see output such as:

java version "1.8.0_31"
Java(TM) SE Runtime Environment (build 1.8.0_31-b13)
Java HotSpot(TM) 64-Bit Server VM (build 25.31-b07, mixed mode)

If you did not see the output above and instead saw either an error or your Java version is less than 1.7, then you need to install Java Runtime.

2. Installation

This chapter describes the steps necessary in order to install the WEM Audit Discover Console.

2.1. Installation Process Overview

The WEM Audit Discover installation has the following major steps:

  • Audit Discover packaging and delivering

  • Running Audit Discover

  • Initial Audit Discover configuration tool

Important:

Ensure you have read the section Prerequisites before proceeding.

2.2. Audit Discover packaging and delivering

Audit Discover can be delivered to you in either 2 ways:

  • along with your WEM Audit package, in a folder called discover

  • in a single package

Either way, you will end up with a discover folder with all you need to install Audit Discover on top of your current WEM Audit installation.

You can copy this folder onto the location where you want to run Audit Discover.

Be aware that Audit Discover will always run from the location to where you’ve copied its folder.

2.3. Running Audit Discover

2.3.1. Configuring the Audit Discover Database

Audit Discover works on top of an embedded H2 database where it stores information about users, saved questions, dashboards, and any other data needed to run the application.

When the application is first launched it will attempt to create a new H2 database in the same filesystem location the application is launched from.

In order to set a custom database location, you must use the following environment variables:

export MB_DB_TYPE=h2
export MB_DB_FILE=/the/path/to/my/Discover.db
On the first run, the database will be created in the path you indicated in MB_DB_FILE.

2.3.2. Startup the application

In order to run Audit Discover you simply need to run the discover.jar file.

export MB_DB_TYPE=h2
export MB_DB_FILE=/the/path/to/my/Discover.db
java -jar discover.jar &

Audit Discover will be available at http://localhost:3000 at this point.

2.3.3. Deploy on an application server

Alternatively you might want to run your Audit Discover on an application server. Currently we can ensure the war deploy on Tomcat/TomEE servers.

Application Servers Supported Versions

Tomcat

8.5.3

TomEE

7.0.1

To deploy your application just place the discover.war under the {$CATALINA_HOME}/webapps folder. This must deploy your war to the application server and the Audit Discover will be available at http://{$host-url}/discover

To set any environment variables, mentioned in the previous sections, you can add them in the setenv file at {$CATALINA_HOME}/bin folder. Then you will need to restart your application server.

2.4. Initial Audit Discover configuration tool

Before starting to work with Discover, you need to run an initial configuration tool to link your current WEM Audit installation to Audit Discover.

This tool is available at the Audit Discover folder with the name discover-audit-configurer.jar and it reads the necessary configurations from the config/application.yml file.

2.4.1. General Configurations

Before launching the Audit Discover configuration tool, you’ll need to create/modify the config/application.yml file. You’ll find an example in the configuration folder which you can copy and start from there.

These are the necessary configurations that you’ll need to edit accordingly to your environment:

Under the audit/discover/setup group:

Property Value

prefs/site-name

Your company or your site/product name, as you wish. This will be the name of the Discover instance.

user/email

Initial Administrator email.

user/first-name

Initial Administrator first name.

user/last-name

Initial Administrator last name.

user/password

Initial Administrator password. This password must be 6 characters long and include one number.

Under the audit/discover/database group:

This information is related to your current Audit installation database, where you have your WEM Audit events recorded.

Property Value

engine

Your Audit Database engine (oracle, postgres or sqlserver)

details/host

Your database host.

details/port

Your database host port.

details/service-name

Oracle Service name (just for Oracle).

details/sid

Oracle SID (just for Oracle).

details/dbname

SQL Server or Postgres database name / Oracle schema.

details/user

Database username. If you’re using Oracle, you must use quotation marks in this field, for example: "admin".

details/password

Database user password.

2.4.2. Selecting the event model

Now you need to select the WEM Audit event model accordingly to your Audit version.

Go to the folder eventModel where you can see multiple event model files. The VCMEventModel.xml is the file that will be used by the configuration tool. You may need to replace this file accordingly to these conditions:

  • If your Audit version is 10.5.1.3 (WEM Audit 10.5.1 Patch 3) or above, you’re fine to go, that’s the default selected model.

  • If your Audit version is below 10.5.1.3, you need to rename VCMEventModel_legacy.xml to VCMEventModel.xml, replacing the current VCMEventModel.xml file.

File Versions

VCMEventModel.xml

Any 8.5, 10.5.1.2 or below.

VCMEventModel_legacy.xml

10.5.1.3 or above, any 16.0 or any 16.2.

2.4.3. Run the configuration tool

After setting up all the required configuration properties on config/application.yml, simply run discover-audit-configurer.jar.

java -jar discover-audit-configurer.jar

This will initialize your system and link Audit Discover to your current Audit installation and database.

You can now access Audit Discover at http://localhost:3000 with the administrative user and password that you’ve set up in the config file and start working with Discover.

3. Administration

This section describes further configurations that are optional to your Discover environment. You can also find information about managing Audit Discover at an administrative level.

3.1. Setting up LDAP

This chapter describes how you can connect your LDAP to Audit Discover, so you can login using your company’s credentials.

In order to set up LDAP with Discover, follow these steps:

  1. Login to Discover using administrative credentials.

  2. Access the Admin panel in the access menu in the top right corner.

  3. In the Settings tab, navigate to the Authentication section.

  4. Click Configure in the LDAP card.

  5. Set LDAP Authentication to Enabled.

  6. Configure the required LDAP fields.

  7. Optional: Enable group membership synchronization and edit group mappings.

  8. Save changes.

From now on, you can login to Audit Discover using your LDAP credentials. Be aware that although setting group mappings is an optional step, you need those mappings if you want to categorize your users, giving different level of access for different groups.

3.2. Setting up SMTP server

If you wish that Audit Discover sends emails with important data and reports, you need to configure an SMTP server for Discover to use.

Follow these steps to configure the SMTP server:

  1. Login to Discover using administrative credentials.

  2. Access the Admin panel in the access menu in the top right corner.

  3. In the Settings tab, navigate to the Email section.

  4. Configure the required SMTP fields.

  5. Click Send test email in order to test your settings.

  6. Once you’re done, Save changes.

4. Questions

Questions are the core concept of Audit Discover. Questions are composed by 3 major parts: source of data, filters and, of course, the answer.

4.1. Data Source

With Audit Discover, all your events are organized into views in your Audit Database. These views are available to pick up as data sources in Questions. Each view represents an event, or a set of related events. For example, all events related with content instances are called Content Instance [action] (eg. Content Instance Create, Content Instance Modify, Content Instance Publish…​). So you’ll find a view for each individual event and also a view called Instance, that will include all Content Instance events.

This is the complete event tree available in Audit Discover:

  • Events

    • Content

      • Type

      • Instance

      • Channel

    • Operation **

4.2. Filters

Filtering your data lets you exclude information that you don’t want. You can filter by any attribute of the event you are working with.

Different attributes will have different filter options based on their data type. There are four universal filter options, or “operators,” that can be applied to any field. These operators are:

  • is a value, e.g., “Status is ‘closed’”

  • is not a value, e.g., “Status is not ‘closed’”

  • is null, i.e., the cell in the field is empty

  • is not null, i.e., the cell in the field isn’t empty

Some attributes have a limited number of possible operators. Attributes that are comparable, like numbers or dates, can also be filtered using the following operators:

  • Less than a value you enter

  • Greater than a value you enter

  • Between two values you enter

4.3. Filtering by dates

If filtering by dates, a date picker will appear to allow you to select dates easily. You have two main options for picking your date: relative or specific.

4.3.1. Specific Dates

This is the most basic way to select dates. You just click on the date you want from the calendar. If you click on a second date, the picker will select all the dates in between the two you clicked on, creating a range. Clicking on any date while you have a range selected will clear the range. You can also use the All before and All after buttons to quickly select all dates before or after the one you’ve selected.

4.3.2. Relative Dates

Relative dates are how we more commonly talk about time: “how many events did we have last month?” We talk about time relative to today.

In practice, if you select Past 30 days from the Relative Date calendar picker, this would be the same as selecting those same dates from the Specific Date picker — unless you save your question and look at it again tomorrow.

Now the relative date will be referencing the past 30 days from today, not from the day you saved the question. This is a really useful way of creating and saving questions that stay up-to-date: you can always know what your total events were in the past 7 days, for example.

4.4. Answers

Discover can output the answer to your question in many different ways. This guide will enhance the most common and relevant outputs for analyzing WEM Audit events.

4.4.1. Raw Data

Raw Data is just a table with the answer listed in rows. It’s useful when you want to see the actual data you’re working with, rather than a sum or average, etc., or when you’re exploring a small table with a limited number of records.

4.4.2. Count of Rows

Count of rows is a very useful metric that will allow you to sum the number of events in a single numeric result.

4.4.3. Groupings

You can group your results by any attribute in the view, simplifying you data for analysis.

4.4.4. Visualization options

Discover provides you several visualization types for the results of your questions. These are the most common and relevant to analyze WEM Audit events:

  • Table: a simple table with every attribute available

  • Line: a Line graph with 2 dimensions

  • Pie: a Pie chart with groupings

  • Bar: a Bar chart comparing groups

4.5. WEM Audit Default Questions

Audit Discover installation will automatically create 3 questions for each existent event in WEM Audit:

  • 1 question with Table output.

  • 1 question with Pie chart output, grouped by Username.

  • 1 question with Line graph output, grouped by Username and Event Date.

This means that you can start analyzing your events out of the box without the need to create additional questions.

All WEM Audit Default questions are categorized as [Audit] and included in the Audit default collection. They cannot be modified.

4.6. New Question

If find that the default questions are not sufficient for your analysis or that some information is missing, you can create your own questions using the New question builder.

Select the data source from the dropdown menu, WEM Audit events will be available in the AUDIT data source.

Add the filters that you find necessary to your question using the plus icon in the filters section of the question builder.

Get the answer to your question.

If you wish you can save your question so you can get the answer again later, using the Save option on the top right corner.

4.7. Export Question

Discover also provides you an easy way to export your question as a pdf. You can download the pdf file with the pretended question by clicking in print button on utilities bar of any question.

5. Dashboards

A dashboard is a collection of saved questions that you want to refer back to and view regularly. It displays groups of questions and their corresponding answers.

5.1. WEM Audit Default Dashboards

Questions on a dashboard are meant to be viewed together, so Discover already provides some default dashboards grouping the questions related to the same event. Each WEM event will have a dashboard with its 3 default questions: table, pie and line.

WEM Audit Default Dashboards are categorized as [AUDIT] and cannot be modified.

These default dashboards are a simple and quick way to get an insight of each event. If you need further information about an event, you can open one of the 3 questions available in the dashboard and start playing with filters and groupings. You can’t however save those filters and groupings as you are dealing with Audit default questions.

5.2. New Dashboard

If you think that the default dashboards are not sufficient for your analysis, you can create new custom dashboards at your like.

In the Dashboards you’ll find the option Add new dashboard in the top right corner. Give your dashboard a name and a description and you are ready to add questions to it.

In the top right corner of your new dashboard, you can find the option Add a question. Select the desired question from the list and place it in your dashboard.

You can either add your custom questions or also the Audit default questions to your dashboard. Have in mind that Audit default questions cannot be saved once modified in the dashboard, however, you can always add them, mess around with the filters and groupings and see the results.

5.3. Export Dashboard

You can easily export your dashboard as a pdf. In the exported pdf, there will be all questions at that dashboard, one per page. The pdf download is triggered by clicking in print button on utilities bar of any dashboard.

6. Share

A very important feature in any data analysis tool is the ability to share your data. In Audit Discover, data is shared using Pulses.

The Pulses feature in Discover gives you the ability to automatically send regular updates to your teammates to help everyone keep track of changes to the metrics that matter to you most. You can deliver a pulse via email on the schedule of your choice.

6.1. Create a Pulse

In the Share section of Audit Discover, you can Create a pulse.

Give a Name to your Pulse.

Pick Your Data

Select any of your saved questions to be sent in your Pulse. You can select up to 5 questions in a single Pulse.

When you select a saved question, Discover will show you a preview of how it’ll look in the pulse. Because of the email’s space constraints, Discover will automatically make some adjustments to the appearance of your saved question so that it looks great in the pulse. For example, in order to save space, pie charts will automatically be transformed into bar charts.

Currently, there are a few restrictions on what kinds of saved questions you can put into a pulse:

  • Raw data can’t be put in a pulse.

  • Tables will be cropped to a maximum of three columns and 10 rows.

  • Bar charts (and pie charts which get turned into bar charts) will be cropped to one column for the labels, one column for the values, and 10 total rows.

Choose your schedule

Each Pulse you create can be delivered by mail in a regular period of your choice. Type in the email addresses you want to send the pulse to, separated by commas. Then, choose to either send it daily, weekly, or monthly, and the time you want it to be sent.

Once you’re done, just click Create pulse. You’ll see your new pulse, along with its recipients, and the saved questions that are included in the pulse. If anyone else on your team wants to subscribe to a pulse that’s delivered by email, they can click the button that says Get this email from the Pulses screen.

6.2. Export Raw data

If you think a Pulse is too much for what you want, and you simply want a clean export of raw data, Discover allows you to export your answers in 3 raw formats:

  • CSV

  • XLSX

  • JSON

To do this, simply open a question, get your answer and then on the top right corner of your result you’ll find an arrow as a Download button. Then you can choose the format to export your results.