Introduction

Dovetail Agent Reporting is a full-featured web-based reporting module for Dovetail Agent.

A set of sample reports and dashboards are included with this package. Because every business is different, it is expected that each customer will create their own reports and dashboards that are specific to their business needs.

The core reporting application is Exago eWebReports. Exago is a Dovetail partner, and the eWebReports reporting application has been integrated with Dovetail Agent.

Exago is an enterprise BI solution that allows non-technical end users to create and edit reports and dashboards without IT support.

Features include:

There are two main Exago UIs:

Access to the Main Reporting app is controlled via Privilege Classes within Dovetail/Clarify. Access to the Reporting Admin app is controlled via a separate username and password.

What's New

Version 1.1

Upgraded to Exago eWebReports version 2016.2.5

dovetail.xml configuration file has been split into two files:

Version 1.0

Initial release of the product

Requirements

Client

The only client requirement is a web browser. The following web browsers have been verified:

Server

Operating System

Dovetail Products

Web Server

Clarify Version

Other Tools

Install Guide

Review the Requirements

Unzip the reports.zip file

Install Exago

Note: The default Exago install directory is C:\Program Files\Exago\. Due to default security permissions on the C:\Program Files directory, installing in a different directory (such as C:\exago) will make life easier.

Install Exago components using $reports\exago\ExagoSetup_v2016.2.5.112.exe

Setup Dovetail Agent - Exago integration

If you installed Exago into a location different than C:\exago edit $reports\dovetail\setup.bat. Set the path to the exago directory:

SET EXAGO_DIR=your_exago_install_path

From a command line (started as an administrator), run:

$reports\dovetail\setup.bat database_type

where database_type is either mssql or oracle

This will copy the dovetail files into the Exago directory.

Configure Exago

Edit the $exago\exagoWeb\config\dovetail.xml file

Set the path to the reports directory

<reportpath>C:\exago\Reports</reportpath>

Set the path to the temp directory

<temppath>C:\exago\Temp</temppath>

Set the username and password to access the Reports Admin app

<userid>admin</userid>
<password>adminPassword</password>

Disallow direct access to reports. This forces users to access reports through Dovetail Agent.

<allowhomedirect>False</allowhomedirect>

During initial setup/development, it may be useful to leave this set to True.

Set the URL to Dovetail Agent.

  <parameter>
    <id>agentURL</id>
    <data_type>string</data_type>
    <value>http://dovetailAgent.company.com</value>
    <hidden>False</hidden>
    <prompt_text />
  </parameter>

Set the database type and connection string.

The user must be able to directly connect to the database, such as via sqlPlus or sqlCmd. A Clarify user with a Clarify-encrypted password will not work. The account only needs read access, so a read-only account can be used.

Microsoft SQL Server example:

  <datasource>
    <id>0</id>
    <name>dovetail</name>
    <dbtype>mssql</dbtype>
    <dataconnstr>Server=localhost;Database=dovetail;User Id=myLoginName; Password=myPassword;</dataconnstr>
  </datasource>

Oracle example:

  <datasource>
    <id>0</id>
    <name>dovetail</name>
    <dbtype>oracle</dbtype>
    <dataconnstr>Data Source=myOracleDatabase;User Id=myLoginName;Password=myPassword;</dataconnstr>
    <schema>SA</schema>
  </datasource>

Set the Oracle schema owner

If using an Oracle database, and the schema owner is not SA, then change the first Restrictions option to be the schema owner. Normally, this does not need to be changed.

    <oracleprovidertableschema>Collection:"Tables", Restrictions:["SA", null], NameColumn:"TABLE_NAME", SchemaColumn:"OWNER"</oracleprovidertableschema>
    <oracleproviderviewschema>Collection:"Views", Restrictions:["SA", null], NameColumn:"VIEW_NAME", SchemaColumn:"OWNER"</oracleproviderviewschema>
    <oracleproviderprocedurechema>Collection:"Procedures", Restrictions:["SA", null], NameColumn:"OBJECT_NAME", SchemaColumn:"OWNER"</oracleproviderprocedurechema>

Configure Exago web.config

Edit the $exago\exagoWeb\web.config file

Within the appSettings element, add an AgentURL key and set its value to your Dovetail Agent URL. Example:

  <appSettings>
    <add key="AgentURL" value="http://dovetailAgent.company.com/" />
    <add key="vs:EnableBrowserLink" value="false" />
  </appSettings>

Within the system.webServer element, add the following:

<security>
  <requestFiltering>
    <hiddenSegments>
      <add segment="dovetail.xml" />
      <add segment="webreports.xml" />
    </hiddenSegments>
  </requestFiltering>
</security>

Configure Exago API

Edit the ExagoWebAPI\Config\WebReportsApi.xml file.

Set the <apppath> element to point at the virtual directory of the Exago Web Application

<apppath>/exago</apppath>

Disable public access to ExagoWebAPI

Using IIS Manager UI

  1. Enable IP security feature in Windows How to Enable IP security

  2. Deny access to ExagoWebApi web application for everyone

    • IIS Manager
    • Click on ExagoWebApi web application
    • Double-click the IP Address and Domain Restrictions feature
    • Click Edit Feature Settings... in the Actions pane.
    • Select Deny for Access for unspecified clients
    • Click OK

  3. Enable local access to ExagoWebApi web application

    • In the IP Address and Domain Restrictions feature, click Add Allow Entry... in the Actions pane.
    • Enter specific IP address of 127.0.0.1
    • Click OK

    If your web site has a binding for a specific IP address (Web Site - Actions panel in right sidebar - Bindings)

    • Click Add Allow Entry... in the Actions pane.
    • Enter the specific IP address
    • Click OK

Using web.config

Alternatively, this task can also be accomplished by editing the ExagoWebAPI web.config.

<system.webServer>
  <security>
    <ipSecurity allowUnlisted="false"> 
    <add ipAddress="127.0.0.1" allowed="true"/>    
    </ipSecurity>
  </security>
</system.webServer>

Note: For this to work (via editing ExagoWebAPI web.config), Feature Delegation for IP Address and Domain Restrictions must be enabled.

Permissions

Verify that the user running under the Exago instance within IIS has read/write privileges to:

Verify that the user running under the Exago instance within IIS has full control privileges to:

Configure Exago Scheduler

To configure the Scheduler Service, edit the file eWebReportsScheduler.xml in the folder where the scheduler service was installed. 

  <smtp_server>myEmailServer:port</smtp_server>
  <smtp_enable_ssl>false</smtp_enable_ssl>
  <smtp_user_id>myEmailAccount</smtp_user_id>
  <smtp_password>myEmailPassword</smtp_password>
  <smtp_from>address@myCompany.com</smtp_from>
  <smtp_from_name>Reports Scheduler</smtp_from_name>
  <error_report_to>admin@myCompany.com</error_report_to>

For complete details on the Scheduler settings, refer to the Exago_Technical_Guide documentation.

Start the Exago Scheduler

Start the Exago Scheduler (eWebReports Scheduler) windows service

Privileges

Using Dovetail Admin's Privilege Class page, grant reporting privileges to the appropriate privilege classes. There are two privileges used:

These privileges are defined with the $dovetailAgent\config\dat\agent_basic_data.dat file. If needed, import that dat file using DIET or dataex.

Dovetail Agent setup

Web Config

Agent uses the Exago Web API to generate secure links into the Exago Web application. You'll need to configure the service refererence binding in your Agent web application's web.config.

Service Reference

First look near the bottom of the web.config for the <system.serviceModel> element. 

<system.serviceModel>
<!-- 
The Exago reporting add-on uses a web service to generate secure links to the Exago reporting web application.  

Please select HTTP or HTTPS bindings and ensure the address is correct for your deployment. 
When using SSL ensure the {server.domain} host name you use matches the certificate.
-->

<!-- HTTP bindings for Exago web API -->
  <bindings>
    <basicHttpBinding>
      <binding name="ApiSoap">
        <security mode="None" />
      </binding>
      <binding name="ApiSoap1" />
    </basicHttpBinding>
  </bindings>
  <client>
    <endpoint address="http://localhost/ExagoWebAPI/api.asmx"
      binding="basicHttpBinding" bindingConfiguration="ApiSoap" contract="ExagoWebApi.ApiSoap"
      name="ApiSoap" />
  </client>

<!-- HTTPS (SSL) bindings for Exago web API -->
<!--
  <bindings>
    <basicHttpBinding>
      <binding name="ApiSoap">
        <security mode="Transport" />
      </binding>
      <binding name="ApiSoap1" />
    </basicHttpBinding>
  </bindings>
  <client>
    <endpoint address="https://server.domain/ExagoWebAPI/api.asmx"
      binding="basicHttpBinding" bindingConfiguration="ApiSoap" contract="ExagoWebApi.ApiSoap"
      name="ApiSoap" />
  </client>
-->

</system.serviceModel>

You need to select a HTTP or HTTPS binding and enter a correct <endpoint> .

Secure or not secure?

The out of the box binding is HTTP. If the web server hosting your Exago web applications has a Server Certificate and you wish the conversation between Agent and the Exago API to be secured, you should uncomment the HTTPS binding and comment the HTTP binding you are not going to use.

Web Service Url

Change the <endpoint> element's address attribute to be the full URL of your Exago web api. When using a HTTPS binding you need to make sure the host name if your URL matches the server name on your Server Certificate. setting to point to the full URL of your Exago API web service.

Application Settings

Agent's application configuration needs to be updated so that Agent knows where to find Exago's web services and web application. Open the Dovetail Agent appSettings.config file and scroll down to the <add> elements with keys starting with ExagoSettings.

Web Application Url

Change this setting to point to the full public facing URL of your Exago web application

<!-- Url to the root of your exago web reports application -->
<add key="ExagoSettings.WebApplicationUrl" value="http://localhost/Exago"/>
Homepage

If you have customized your exago home page (default is DovetailReports.aspx). Change this setting, but do not include the .aspx file extension.

<!-- Which home page should users be taken to. (Do not add .aspx to the end) -->
<add key="ExagoSettings.HomePage" value="DovetailReports"/>
Config XML

Your Exago web application can have multiple configurations. If you are running multiple configurations you'll need to change this setting to the configuration XML file which you wish Agent to use.

<!-- What configuration file should the integration use? -->
<add key="ExagoSettings.ConfigXml" value="dovetail.XML"/>
Dovetail Reporting Permissions

Agent configuration data files include 2 permissions you can use to control access to your Exago reporting integration. If you with to change the permissions which control this integration change these settings. You will need to make sure these exact permissions have matching Exago Roles. These roles are already defined within $exago\config\dovetail.xml, so these values should not need to be changed.

<!--
      Exago/Agent role names. Roles need to be present in both Exago and Agent.
      If a user is not a member of any roles they will not be linked to exago reports.
      Exago session links will grant users rights to Exago based on these roles.
-->
<add key="ExagoSettings.ReportUserRole" value="Report User"/>
<add key="ExagoSettings.ReportCreatorRole" value="Report Creator"/>

Deployment

This can be done from the Exago UI:

General -> Main Settings -> Allow direct access to Exago (bypassing API) = False

or via the dovetail.xml file:

<allowhomedirect>False</allowhomedirect>

Access the Reports app

Additional References

Additional Exago documentation is included within the product zip file:

Troubleshooting

In case of a problem, please refer to the following articles:

Error: Unable to find the requested .Net Framework Data Provider

An error has occurred that is preventing completion of this request

The XDL diffgram is not applicable to this XML document

If your problem scenario is different from the above, please let us know or search Exago Support.