Reports Documentation

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

• Install the Exago Web Application
• Install the Exago Web Service API
• Install the Exago Scheduling Windows Service

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.

• IIS Manager
• Click on the root server
• Double click Feature Delegation (under Management)
• Click IPv4 Address and Domain Restrictions
• Change the delegation to Read/Write

Permissions

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

• The report path (C:\exago\Reports)
• The temp path (C:\exago\Temp)

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

• The Config sub-folder of the Exago\ExagoWeb installation.

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:

• Report User - can run reports
• Report Creator - can create and run reports

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

• Before going in to production you should lock down the Exago web application to only support API access to the application.

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

• Log into Dovetail Agent as a user with Report User or Report Creator privilege
• Click on the Reports link in the header
• This should navigate to the reports home page (DovetailReports.aspx).