PRIMAVERA Analytics v1 filePRIMAVERA Analytics – Adapter Implementation Guide PRIMAVERA – Business Software Solutions, S.A. 4

PRIMAVERA Analytics v1.0 ADAPTER IMPLEMENTATION GUIDE

Version 1.0

October 2010

PRIMAVERA Analytics – Adapter Implementation Guide

PRIMAVERA – Business Software Solutions, S.A. 2

Index

Index ............................................................................................................................ 2

Introduction .................................................................................................................. 3

Key Performance Indicators .......................................................................................... 4

Architecture ................................................................................................................ 4

Adapters ..................................................................................................................... 5

Interfaces description .................................................................................................. 6

Primavera.Analytics.Adapters.IKpiAdapter .................................................................... 6

Primavera.Analytics.Adapters.IKpiConfiguration ............................................................ 7

KpiDataSource ...................................................................................................... 7

MetadataDefinition ................................................................................................. 7

Property ............................................................................................................... 8

Primavera.Analytics.Adapters.IKpiDataSource .............................................................. 8

Primavera.Analytics.Adapters.IKpiSecurity ................................................................... 9

Primavera.Analytics.Adapters.IKpiPresenter ................................................................. 9

Case study example .................................................................................................. 10

Context ................................................................................................................ 10

Implementation ..................................................................................................... 10

KpiAdapter class .................................................................................................. 10

Configuration class .............................................................................................. 12

DataSource class ................................................................................................. 14

AdapterHelper class ............................................................................................. 16

Security class ...................................................................................................... 19



Introduction

This document describes the guidelines to implement adapters for PRIMAVERA

Analytics framework.

PRIMAVERA Analytics is a collection, organisation, sharing and monitoring

mechanism of data that supports business management.

There is an enormous quantity of data, distributed by many ERP, CRM and

Corporative Portals, etc, in companies. However, "a lot of information" is not

necessarily a synonym of "useful information" – a symptom that is normally

called an Analysis Gap.

PRIMAVERA Analytics’s objective is to resolve this problem, by transforming

dispersed data in transactional systems into management information with

reader friendly formats, in order to sustain and facilitate decision taking

processes, at the varios hierarchical levels in the organisation. It enables the

creation of indicators through various data sousces (SQL Server, ORACLE,

.XLS, etc.).

PKB

PRIMAVERA Analytics

http://www.primaverabss.com/pkb/PortalRender.aspx?PageID=e42fbca7-fea6-4a84-a9c2-9a346bdd7433&KBCategoryID=be946f40-290f-11de-a916-00155d060811



Key Performance Indicators Key Performance Indicators are quantifiable measurements, agreed to

beforehand, that reflect the critical success factors of an organization. They

will differ depending on the organization.

Architecture One of the goals of the framework is to provide a centralized system for

configuration and management for key performance indicators, whatever the

source of the information or the client used to consume it.

In this context, the framework is based on the following main elements:

Analytics Shell: in this application, the user will create, configure and

schedule the kpis execution.

Execution engine: this component, based on a windows service will be

responsible for the kpis calculation and results storage, according to the

scheduling defined for each kpi.

API to integrate multiple data sources and clients: in order to a

client system be recognized by the framework, a set of .Net components

must be implemented, so the information provided will be available to the

Analytics environment. These components are known as Adapters.

The following diagram represents the logical architecture of the system with an

example of client adapters:

Examples of possible connected systems (client applications and adapters):

PRIMAVERA ERP;

PRIMAVERA WebCentral.



Adapters As previously referred, in order to external systems integrate with the

PRIMAVERA Analytics, a set of components must be implemented. These

components are identified by the following diagram:

A client adapter, in practice, is composed by the following components:

Configuration: this component is responsible to provide information

about the data that the connected system supported by the adapter can

supply.

Datasource: this component is responsible to supply resultset’s of data

whenever an kpi is calculated by the calculation engine.

Security: this component supplies information about the security entities

that the connected system, so the access to the kpis results can be

restricted.

Presenter: this component is responsible to subscribe and respond to

operations actions, during kpis calculation performed by the calculation

engine.

In order to an adapter be recognized by the framework, a new entry must be

added in the Analytics configuration file (analytics.config), in the adapters

section. The following elements must be provided:

name: name of the adapter.

description: full description of the adapter.

typeName: full type name of the adapter’s entry point, which must

correspond to a concretization class of the following interface:

Primavera.Analytics.Adapters.IKpiAdapter

assemblyPath: the path of the assembly that holds the concretization

class.

initParams (optional): allows the definition of startup parameters. Each

parameter must be supply as a pair key/value, and separated by a

comma.

Example of entry point in the configuration file:

<analyticsConfiguration>

<KpiAdapters>

<add name="DummyAdapter1"

description="Kpi Dummy Adapter"

typeName="Primavera.DummyAdapter.KpiDummyAdapter"

assemblyPath ="C:\prjNET\Adapters\DummyAdapter.dll"

initParams ="param1=value1, param2=value2" />

</KpiAdapters>

</analyticsConfiguration>



Interfaces description

The following diagram represents the structure of the interfaces that composes

an adapter:

Primavera.Analytics.Adapters.IKpiAdapter

The implementation of this interface will be the main class, and entry point for

any operation performed in the adapter’s components.

The class must implement the following properties:

Property Description

Configuration Instance of the IKpiConfiguration implementation class.

DataSource Instance of the IKpiDataSource implementation class.

Description Brief description of the adapter implementation.

Identifier Unique identifier of the adapter implementation.

Security Instance of the IKpiSecurity implementation class.

Presenter Instance of the IKpiPresenter implementation class.

The following methods must also be implemented:

Method Description

Initialize Performs the initializations of the interface components.

The instances of the depending classes must be created

here. The initial parameters defined in the Analytics

configuration file are passed as a Dictionary object.



Primavera.Analytics.Adapters.IKpiConfiguration

The implementation of this interface will provide information related with the

data that may be used to create and configure kpis.

The following methods must be implemented:

Method Description

GetAdapterMetadata Returns an object with the metadata

definition for the adapter, typically pair’s

name-value. The following elements types

can be supplied:

Text properties (optionally with

password mask)

List values (with single or multiple

selection)

Boolean properties (checkbox)

GetCalculationActions Returns calculation actions that may be

configured in the kpi calculation process.

GetKpiDataSourceCategories Returns the datasource categories.

GetKpiDataSources Returns a list of datasource objects (which

may be filtered by a category). The objects

of this list will define the candidates for kpi

configurations.

ValidateAdapterMetadata Given a configuration based on the

adapter’s metadata, performs specific

validations, returning a boolean value

indicating that the configuration is valid or

not (with an error message in this case).

For example, mandatory fields can be

validated with this method.

KpiDataSource

Defines a kpi data source.


Name Name of the data source.

Description Description of the data source.

QueryDataSource Internal use only.

MetadataDefinition

Defines the metadata definition of an adapter.


Properties Collection of the properties supported by the

adapter.



Property

Defines a property.


Name Property name.

Description Property description. This will be used as

caption in the adapter’s configuration

window.

PropertyType Property type. The following types are

supported:

Text

List

Checkbox

Password For the Text property type, indicates if the

property has a password format (password

char).

AllowMultiple For the List property type, indicates if

multiple selection is allowed (Listbox or

Combo)

Values For the List property type, defines the

possible values to be selected.

Primavera.Analytics.Adapters.IKpiDataSource

The implementation of this interface will be used essentially for data metadata

and retrieval whenever a kpi associated to the adapter is being configured or

calculated.


Method Description

GetKpiDataSourceData Returns the data associated to a specific

datasource. This data may be filtered by initial

and end dates (in this case, the date column

name is supplied).

GetDataSourceMetadata Given a specific data source identifier, returns

the associated metadata. This metadata is

defined in a collection of fields with the following

information:

Id

Name

Description

PropertyName (corresponds tipically to

the column name of the datasource).



Primavera.Analytics.Adapters.IKpiSecurity

The implementation of this interface will provide information about the security

entities defined in the system supported by the adapter, such as

authentication.


Method Description

AuthenticateUser Performs the authentication of a user,

according to the credentials supplied.

Primavera.Analytics.Adapters.IKpiPresenter

The implementation of this interface will be used by the framework to inform

the adapter about some key operations whenever they are performed by the

calculation engine, so some custom actions can be implemented by the

adapter, according to the data supplied by the framework.


Method Description

ExecuteAction Executes a specific action according to an action type

triggered by the framework.



Case study example

In this chapter, a simple adapter implementation will be presented with code

examples for the main properties and methods.

Context

The context of this adapter is a simple ERP sales system (the data will be

focused on sales movements).

In this context, our adapter will be called ERPSalesAdapter.

Implementation

We will start by creating a new Visual Studio 2008 project (class library) called

ERPSalesAdapter.

After loading the new project, we need to add the following assembly

references (located in c:\..\Primavera\Analytics100\Shell):

Primavera.Analytics.Adapters

Primavera.Analytics.Domain.Entities

Primavera.Athena.BusinessEntities

Primavera.Athena.Core

Let’s create now the following classes and create the methods skeletons of it’s

implementations:

Class Implements

KpiAdapter Primavera.Analytics.Adapters.IKpiAdapter

Configuration Primavera.Analytics.Adapters.IKpiConfiguration

DataSource Primavera.Analytics.Adapters.IKpiDataSource

Security Primavera.Analytics.Adapters.IKpiSecurity

Presenter Primavera.Analytics.Adapters.IKpiPresenter

KpiAdapter class

Here’s an example of the KpiAdapter class implementation:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

using Primavera.Analytics.Adapters;

namespace Analytics.Adapters

{

public class ERPSalesAdapter : IKpiAdapter

{

#region Members

private IKpiConfiguration configuration;

private IKpiDataSource datasource;

private IKpiSecurity security;

private IKpiPresenter presenter;

#endregion



#region IKpiAdapter Members

/// <summary>

/// Gets the adapter's identifier.

/// </summary>

/// <value></value>

public Guid Identifier

{

get { return new Guid("84C185FE-2A91-4D70-9605-CBCF2699022C"); }

}

/// <summary>

/// Gets the adapter's description.

/// </summary>

/// <value></value>

public string Description

{

get { return "ERP Sales"; }

}

/// <summary>

/// Gets the configuration instance.

/// </summary>

/// <value>The configuration.</value>

public IKpiConfiguration Configuration

{

get { return this.configuration; }

}

/// <summary>

/// Gets the data source adapter instance.

/// </summary>

/// <value></value>

public IKpiDataSource DataSource

{

get { return this.datasource; }

}

/// <summary>

/// Gets the presenter instance.

/// </summary>

/// <value>The presenter.</value>

public IKpiPresenter Presenter

{

get { return this.presenter; }

}

/// <summary>

/// Gets the security instance.

/// </summary>



/// <value>The security.</value>

public IKpiSecurity Security

{

get { return this.security; }

}

/// <summary>

/// Initializes the adapter.

/// </summary>

public void Initialize(IDictionary<string, string> initParams)

{

this.configuration = new ConfigurationDummyAdapter();

this.datasource = new DatasourceDummyAdapter();

this.security = new SecurityDummyAdapter();

this.presenter = new PresentationDummyAdapter();

}

#endregion

This class will be the one configured in the Analytics configuration file

(analytics.config).

Configuration class

Assuming that our data will be stored in a SQL Server database, let’s define

the necessary properties to connect to the SQL Server instance. Additionally,

we will define a simple data source (for the sales movements), and the

associated metadata (dimensions and measures).

Example of the GetAdapterMetadata, GetDataSourceCategories and

GetKpiDataSources implementation:

/// <summary>

/// Gets the adapter metadata.

/// </summary>

/// <returns>The adapter metadata.</returns>

public MetadataDefinition GetAdapterMetadata()

{

MetadataDefinition metadatadefinition = new MetadataDefinition();

// Server.

Property serverProperty = new Property("Server", "Database server", PropertyType.Text);

// Login.

Property loginProperty = new Property("Login", "Login", PropertyType.Text);

// Password.

Property passwordProperty = new Property("Password", "Password", PropertyType.Text);

passwordProperty.Password = true;



// Database.

Property databaseProperty = new Property("Database", "Database", PropertyType.Text);

metadatadefinition.Properties.Add(serverProperty);

metadatadefinition.Properties.Add(loginProperty);

metadatadefinition.Properties.Add(passwordProperty);

metadatadefinition.Properties.Add(databaseProperty);

// Return.

return metadatadefinition;

}

/// <summary>

/// Gets the kpi data source categories.

/// </summary>

/// <param name="metadata">The metadata.</param>

/// <returns>The data source categories.</returns>

public IList<DataSourceCategory> GetKpiDataSourceCategories(MetadataValues metadata)

{

return new List<DataSourceCategory>() { new DataSourceCategory(AdapterHelper.SalesCategory, "Sales") };

}

/// <summary>

/// Gets the kpi data sources.

/// </summary>

/// <param name="category">The category.</param>


/// <returns>The kpi data sources.</returns>

public IList<KpiDataSource> GetKpiDataSources(string category, MetadataValues metadata)

{

var kpiDataSources = new List<KpiDataSource>();

if (category == AdapterHelper.SalesCategory)

{

kpiDataSources.Add(new KpiDataSource()

{

Id = new Guid(AdapterHelper.CompaniesDatasourceId),

Name = "Comp",

Description = "Companies"

});


{

Id = new Guid(AdapterHelper.DepartmentsDatasourceId),

Name = "Dep",



Description = "Departments"

});


{

Id = new Guid(AdapterHelper.SalesPersonsDatasourceId),

Name = "SlsPer",

Description = "Sales persons"

});


{

Id = new Guid(AdapterHelper.SalesResumeDatasourceId),

Name = "SLSResume",

Description = "Sales Resume"

});

}

// Return

return kpiDataSources;

}

The remaining methods of this class should be easily implemented, according

to the adapter’s context.

DataSource class

As previously referred, this class will be responsible of data retrieval.

Let’s look at an example of the GetDataSourceMetadata and

GetDataSourceData methods implementation:

/// <summary>

/// Gets the data source metadata.

/// </summary>

/// <param name="dataSourceId">The data source id.</param>


/// <returns>The data source metadata.</returns>

public DataSourceMetadata GetDataSourceMetadata(Guid dataSourceId, MetadataValues metadata)

{

SqlConnection connection = AdapterHelper.GetSqlConnection(metadata);

// Get only one row to obtain the fields list.

string query = AdapterHelper.GetQueryForDatasource(dataSourceId, false);



if (connection != null && !string.IsNullOrEmpty(query))

{

DataSet dataSet = AdapterHelper.ExecuteQuery(query, connection);

if (dataSet.Tables.Count > 0)

{

// Process the fields.

var dataSourceMetadata = new DataSourceMetadata();

foreach (DataColumn dataColumn in dataSet.Tables[0].Columns)

{

dataSourceMetadata.Fields.Add(

new DataSourceFieldMetadata()

{

Name = dataColumn.ColumnName,

Description = dataColumn.ColumnName,

PropertyName = dataColumn.ColumnName

});

}

// Return.

return dataSourceMetadata;

}

}

// Default.

return null;

}

/// <summary>

/// Gets the data source data.

/// </summary>



/// <returns>The data source data.</returns>

public KpiData GetDataSourceData(Guid dataSourceId, MetadataValues metadata)

{

SqlConnection connection = AdapterHelper.GetSqlConnection(metadata);

string query = AdapterHelper.GetQueryForDatasource(dataSourceId);

if (connection != null && !string.IsNullOrEmpty(query))

{

DataSet dataSet = AdapterHelper.ExecuteQuery(query, connection);



return new KpiData() { ResultSet = dataSet };

}

// Default.

return null;

}

AdapterHelper class

/// <summary>

/// Helper methods for the adapter implementation.

/// </summary>

public class AdapterHelper

{

#region Constants

public const string SalesCategory = "SLS";

public const string SalesResumeDatasourceId = "{0FA15771-C3DD-463d-88E8-AEE1E5F8FB54}";

public const string CompaniesDatasourceId = "{76228A03-FB52-4483-AE3C-B67DE7ED2C26}";

public const string DepartmentsDatasourceId = "{86A9D1E3-368E-4139-8E5B-F50074E557BD}";

public const string SalesPersonsDatasourceId = "{6423E14B-C74C-4b26-AA98-F82DEFA9F8E5}";

#endregion

#region Public Methods

/// <summary>

/// Gets the SQL connection for the specified metadata.

/// </summary>


/// <returns>The SQL connection</returns>

public static SqlConnection GetSqlConnection(MetadataValues metadata)

{

SqlConnection connection = new SqlConnection();

string connectionString = string.Format(

System.Globalization.CultureInfo.InvariantCulture,

"Data Source = {0}; Initial Catalog = {1}; User Id= {2}; Password = {3};",

GetPropertySingleValue(metadata, "Server"),

GetPropertySingleValue(metadata, "Database"),

GetPropertySingleValue(metadata, "Login"),

GetPropertySingleValue(metadata, "Password"));

connection.ConnectionString = connectionString;



return connection;

}

/// <summary>

/// Gets the property single value.

/// </summary>


/// <param name="propertyName">Name of the property.</param>

/// <returns>The property value.</returns>

public static string GetPropertySingleValue(MetadataValues metadata, string propertyName)

{

PropertyValue propertyValue = null;

propertyValue = metadata.PropertyValues.Where(p => p.PropertyName.Equals(propertyName)).FirstOrDefault();

if (propertyValue != null)

{

return propertyValue.Values[0].Text;

}

// Default.

return string.Empty;

}

/// <summary>

/// Executes the query.

/// </summary>

/// <param name="query">The query.</param>

/// <param name="connection">The connection.</param>

/// <returns>A DataSet with the data.</returns>

public static DataSet ExecuteQuery(string query, SqlConnection connection)

{

DataSet dsResult = new DataSet("Results");

try

{

connection.Open();

SqlCommand command = new SqlCommand();

command.CommandType = CommandType.Text;

command.CommandText = query;

command.Connection = connection;

SqlDataAdapter adapter = new SqlDataAdapter(command);

adapter.Fill(dsResult);

return dsResult;



}

finally

{

if (connection.State != ConnectionState.Closed)

{

connection.Close();

}

}

}

/// <summary>

/// Gets the query for the specified datasource.

/// </summary>


/// <returns>The query.</returns>

public static string GetQueryForDatasource(Guid dataSourceId)

{

return GetQueryForDatasource(dataSourceId, true);

}

/// <summary>

/// Gets the query for the specified datasource.

/// </summary>


/// <param name="allRows">if set to <c>true</c> all rows; false, otherwise.</param>

/// <returns>The query.</returns>

public static string GetQueryForDatasource(Guid dataSourceId, bool allRows)

{

string table = string.Empty;

if (dataSourceId.Equals(new Guid(AdapterHelper.CompaniesDatasourceId)))

{

table = "Companies";

}

if (dataSourceId.Equals(new Guid(AdapterHelper.DepartmentsDatasourceId)))

{

table = "Departments";

}

if (dataSourceId.Equals(new Guid(AdapterHelper.SalesPersonsDatasourceId)))

{

table = "SalesPersons";

}

if (dataSourceId.Equals(new Guid(AdapterHelper.SalesResumeDatasourceId)))

{



table = "SalesResume";

}

if (string.IsNullOrEmpty(table))

{

return string.Empty;

}

string query = "SELECT {0} * FROM {1}";

// Return.

return string.Format(query, allRows ? string.Empty : "TOP 1", table);

}

#endregion

}

Security class

The main method of this class is the method that grants user access to the

Analytics Shell (AuthenticateUser). Since the Analytics system does not

manage an integrated security subsystem, due to its integration architecture,

it is assumed that the adapter implementation is responsible for this

authentication.

/// <summary>

/// Authenticates the user.

/// </summary>

/// <param name="userName">Name of the user.</param>

/// <param name="password">The password.</param>

/// <param name="windowsAuthentication"><c>True</c>, for windows authentication; oherwise, <c>false</c>.</param>

/// <returns>

/// <c>True</c>, if the authentication succeeds; otherwise, <c>false</c>.

/// </returns>

public bool AuthenticateUser(string userName, string password, bool windowsAuthentication)

{

return AuthenticationService.Instance.AuthenticateUser(userName, password, bool);

}

© 1993 – 2010 PRIMAVERA Business Software Solutions S. A. All rights

reserved.

Documents

PRIMAVERA Analytics v1 filePRIMAVERA Analytics – Adapter Implementation Guide PRIMAVERA – Business Software Solutions, S.A. 4