PRIMAVERA Analytics v1 filePRIMAVERA Analytics – Adapter Implementation Guide PRIMAVERA –...
Transcript of PRIMAVERA Analytics v1 filePRIMAVERA Analytics – Adapter Implementation Guide PRIMAVERA –...
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
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 3
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
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 4
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.
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 5
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>
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 6
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 – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 7
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.
Property Description
Name Name of the data source.
Description Description of the data source.
QueryDataSource Internal use only.
MetadataDefinition
Defines the metadata definition of an adapter.
Property Description
Properties Collection of the properties supported by the
adapter.
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 8
Property
Defines a property.
Property Description
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.
The following methods must be implemented:
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 – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 9
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.
The following methods must be implemented:
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.
The following methods must be implemented:
Method Description
ExecuteAction Executes a specific action according to an action type
triggered by the framework.
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 10
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
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 11
#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>
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 12
/// <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;
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 13
// 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>
/// <param name="metadata">The metadata.</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"
});
kpiDataSources.Add(new KpiDataSource()
{
Id = new Guid(AdapterHelper.DepartmentsDatasourceId),
Name = "Dep",
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 14
Description = "Departments"
});
kpiDataSources.Add(new KpiDataSource()
{
Id = new Guid(AdapterHelper.SalesPersonsDatasourceId),
Name = "SlsPer",
Description = "Sales persons"
});
kpiDataSources.Add(new KpiDataSource()
{
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>
/// <param name="metadata">The metadata.</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);
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 15
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>
/// <param name="dataSourceId">The data source id.</param>
/// <param name="metadata">The metadata.</param>
/// <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);
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 16
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>
/// <param name="metadata">The metadata.</param>
/// <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;
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 17
return connection;
}
/// <summary>
/// Gets the property single value.
/// </summary>
/// <param name="metadata">The metadata.</param>
/// <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;
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 18
}
finally
{
if (connection.State != ConnectionState.Closed)
{
connection.Close();
}
}
}
/// <summary>
/// Gets the query for the specified datasource.
/// </summary>
/// <param name="dataSourceId">The data source id.</param>
/// <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="dataSourceId">The data source id.</param>
/// <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)))
{
PRIMAVERA Analytics – Adapter Implementation Guide
PRIMAVERA – Business Software Solutions, S.A. 19
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.