Embedding BI

Advanced administration and
development
guidelines & reference
Niklas Derouche

Page |2
Advanced administration and development - guidelines and reference

About DSPanel
Decision Support Panel Intl AB is a Swedish company based out of Stockholm. It celebrated its 10th
anniversary in 2009 and have been supplying business intelligence software throughout its existence.
There are customers on every continent and virtually in every kind of business and even though the
company started out focusing on the intersection of SharePoint(tm) and SQL Server Analysis
Services(tm) the current toolset is certified for use with solutions from SAP and IBM as well.

About Performance Canvas
Performance Canvas is the market leading software for web based, web focused business intelligence.
With abilities from visual analytics to mash-ups, from simple, clear charts to complex pivoting and
everything in between in a highly customizable package it is certainly at the top of the class and then we
haven't even mentioned the fact that almost all of the core functionality (object configurations,
rendering, query parsing and transformations) are available as web services.

(c) Decision Support Panel AB 2009

Page |3

Contents
About Decision Support Panel .................................................................................................................. 2
About Performance Canvas 2009 ............................................................................................................. 2
Who is this document for ......................................................................................................................... 5
Introduction .............................................................................................................................................. 6
On administration ..................................................................................................................................... 7
On caches ................................................................................................................................................ 14
The Metadata cache ........................................................................................................................... 14
The Query cache ................................................................................................................................. 14
Client side caching .............................................................................................................................. 15
Related subjects .................................................................................................................................. 16
On query based security ......................................................................................................................... 17
On secure socket layer (SSL) and its implications ................................................................................... 19
On loose clusters ..................................................................................................................................... 21
On locales and languages........................................................................................................................ 22
On Kerberos ................................................................................................................................................ 23
Prerequisites ....................................................................................................................................... 23
Step 1: Creating the account............................................................................................................... 23
Step 2: Ensuring that the account can handle delegation .................................................................. 25
Step 3: Adding a host name ................................................................................................................ 26
Step 4: Generating the keytab ............................................................................................................ 27
Step 5: Installing the keytab file.......................................................................................................... 29
Step 6: Access Performance Canvas by using the new DNS record as URL ........................................ 29
Do's and Don’ts while installing the Kerberos setup .......................................................................... 29
Troubleshooting .................................................................................................................................. 30
On development ......................................................................................................................................... 31
On direct API usage ................................................................................................................................. 31
On web services .......................................................................................................................................... 31
On ConfigurationService ......................................................................................................................... 31
On methods ........................................................................................................................................ 32
Task: Retrieving an existing object...................................................................................................... 39
Task: Finding a list of objects .............................................................................................................. 40


Page |4
Task: Finding a list of objects that match a certain filter .................................................................... 41
Task: Creating an object ...................................................................................................................... 42
Task: Exporting a canvas ..................................................................................................................... 43
Task: Importing a canvas..................................................................................................................... 44
On RenderingService........................................................................................................................... 45
On methods ........................................................................................................................................ 45
On XMLAService .................................................................................................................................. 50
On object definitions............................................................................................................................... 56
On building new applications.................................................................................................................. 57
On .NET and PC ....................................................................................................................................... 69
Appendix A .................................................................................................................................................. 70
Configuring Performance Canvas using zenith.properties ..................................................................... 70
Appendix E .................................................................................................................................................. 74
ConfigurationService WSDL .................................................................................................................... 74
Appendix F .................................................................................................................................................. 89
RenderingService WSDL .......................................................................................................................... 89
Appendix G .................................................................................................................................................. 93
XMLAService WSDL ................................................................................................................................. 93
Index.......................................................................................................................................................... 106


Page |5

Who is this document for

This document assumes you have a working knowledge of a lot of things. However, even someone
without that knowledge should be able to glean bits of relevant information from the parts they are
interested in. For example, you do not need to be an MDX wizard to configure the caches, nor do you
need to understand the intricacies of networking to able to fathom how to use web services to render a
simple chart.
However, if you expect to understand everything covered in here you should have a passable knowledge
about

 HTTP1.1
 SSL
 Windows Security
 Active Directory
 WS-SOAP
 MDX
 Analysis Services
 IIS


Page |6

Introduction

So you managed to get past the part about who you are. This either means you will understand
everything in this document or that you know exactly what you are looking for. Either way, it is our
sincere hope that the information found in these chapters will help you get the most out of your
Performance Canvas (TM) (or PC).
Let us start off with the basics; what is PC? At the core it is a set of service pipelines served up by a
Tomcat instance. The fact that it happens to be Tomcat is purely circumstantial. It could just as easily
have been Resin, Jetty, Glassfish or any number of other, equally qualified, application servers out there.
Tomcat happened to be easier to work with and easy to embed. These pipelines are exposed as servlets
to the web client. These servlets however are not of much use to someone else as they use a very
specific RPC model specific to GWT (Google Web Toolkit) which is used to develop the front
end/client(s).
The same services do however have a different access point which is web services. If you have a look at
the chapter on web services you will find all the information you need to write a complete client
solution on top of the capabilities in PC. You could potentially - if you were so inclined, although it is this
author's sincere hope that you aren't - make your own PC web client. Please don't. There are much
more interesting applications for this technology.


Page |7

On administration

Administration in PC generally means opening /app/admin and setting up data sources, adding users to
roles and approving objects. There are however a number of things that can be done but require you to
edit text files. Don't worry, it's not very dangerous. OK, Maybe a little.

As in any large server application there are configuration options that really shouldn't be exposed to the
light of day as they have the potential for serious repercussions. Some of these are related to the data
sources (like the caching options) and can, for a large scale installation, easily turn your data layer into a
very slow mowing slug indeed. Others are related to things like protocol level security (SSL) or advanced
deployment (see On scaling out). We will try to go through these different subjects - and some of the
purely miscellaneous configuration options in this sections.

But let us start off with the basics. Below you will find a list of all the places you find configuration files,
what they are and what they contain. There are more of these than you would think. Note that all paths
are relative to the installation directory (hence /bin means C:Program FilesPerformance Canvasbin if
you installed in the default location).

Location: Installation directory

File zenith.properties
Format Key value pairs in key=value format

Description The main configuration file. Here you will add most of the configuration
switches you find within this document. Note that you can also use any java
configuration switches here as well as anything that is not PC-related will get
stored in System.properties. Yes, that means that you could do X, Y and Z. Yes,
it's done that way for a reason (see On proxies). This is not something everyone
will use but it certainly is useful.

Refer to Appendix A, section 1 for a complete description of all available
configuration options

Location: /bin

File service.properties

Description Used to configure the service. Some people will want to use a custom service
name or, perhaps more frequently, change the memory space settings. This is
where to go for that. In order to make the changes happen you need to

1: Stop the current service if it is running


Page |8

2: Run uninstallservice.bat located in the same directory as this file

3: Make the changes you want and save them

4: Run installservice.bat

5: Start the service

Refer to Appendix A, section 2 for a complete description of all available
configuration options

Location: /store/settings

File app.properties

Description Used to guide the automated page generation. Don't change this. If you change
it, things will break. If you absolutely have to change a title for a page, make
absolutely SURE you have a backup of the original file and can replace your
modified version with it if it doesn't work. But generally. Don't touch.

Refer to Appendix A, section 3 for a complete description of all the things you
shouldn't be changing.

File colors.xml
Format XML
Description Configuration of color schemes for the installation. You can add as many as you
of these. In Appendix B, section 1 you can find out more on how to do this if
you are so inclined. Note that schemes you don't like can be hidden. Look in
the section just mentioned.

File cubes.xml
Format XML
Description Cubes.xml defines which datasources are currently setup. The file is
autogenerated by the application and it would be very rare that you need to
modify this by hand. If you do then refer to Appendix B, section 2 for
information. If you just want to clear it out and don't feel like unchecking
seventyleven checkboxes in the web UI then just delete everything but
<DB></DB> and you are all set. Once PC is restarted you have no mapped
datasources.

File krb5.conf


Page |9

Format Configuration file specific
Description In most cases the krb5.conf file is autogenerated and never touched. Unless
you need to join realms together you should never, ever touch this file. Most of
the options can be accessed through the zenith.properties file and you are
better off changing those rather than editing this file. If you need to however -
and there are certain cases where you do - you will find the information you
need in Appendix C, section 1

File login.conf
Format Configuration file specific
Description Internal. Do NOT change.

File Userlocales.properties

Description Placeholder file for planned functionality

File Viewport.properties

Description Viewport.properties contains information about which properties are visible
for which chart (and table) types. For example, only gauge-related properties
are visible when you are editing a Gauge. If you would like to restrict your
users/designers to using only a subset of the properties, perhaps because you
have set up defaults that shouldn't be changed, then you can edit this file.
Before doing that, please refer to Appendix A, section 4.

Location: /store/settings/locale/<dirname>

(note, this is a special case. Here is where the locale specific language files are stored.

File keyed.properties
Format Key value pairs in key = value format

Description The main language file. If there are messages in the application that you want
to change this is where to do that. This file isn't described extensively since it
contains far too many properties to be usefully documented. It is sufficient to
say that <key>=<value> and that removing a required key will result in MISSING
RESOURCE errors in the client side UI. If you want to implement a new


P a g e | 10

language then

1: translate the contents of the file

2: create a subdirectory in /store/settings/locale where dirname is <language
code>_<variant code>. For example, if you have a translation for Canadian
French and one for regular French then the directory names would be fr_CA
and fr_FR respectively. Adding a default one with the name fr containing the
fr_FR is usually a good idea since there are territories where french is spoken
but that don't have a specific locale or that you would not want to make a
specific implementation for.

3: restart the service and set the server locale using the /app/admin UI or by
editing the zenith.properties file.

File Messages.properties
Format Key value pairs in key = value format

Description A support language file containing a specific subset of language constants - the
dynamic ones. Here we specify snippets that, combined with information from
the application, form complete statements.

For example the property

Example=My {0} example {1}

Used with the parameters 'simple' and 'string' will result in the message
'My simple example string'.

Refer to the previous section on keyed.properties to find out how to use this
for creating support for new languages.

Location: /store/properties

File analysis.p
Format DSP custom
Description Property file describing an Analysis.

Refer to Appendix D for complete information.

File annotation.p


P a g e | 11

Format DSP custom
Description Property file describing an Annotation.


File canvas.p
Format DSP custom
Description Property file describing a Canvas.


File chart.p
Format DSP custom
Description Property file describing a Chart.


File classification.p
Format DSP custom
Description Property file describing a Classification.


File filter.p
Format DSP custom
Description Property file describing a Filter.


File gem.p
Format DSP custom
Description Property file describing a Gem.


File kpi.p
Format DSP custom


P a g e | 12

Description Property file describing a KPI. (placeholder for future functionality)


File measure.p
Format DSP custom
Description Property file describing a Measure. (A virtual object that looks as if it existed in
the cube to the end user)


File report.p
Format DSP custom
Description Property file describing a Report.


File role.p
Format DSP custom
Description Property file describing a Role.


File slicer.p
Format DSP custom
Description Property file describing a Slicer.


File table.p
Format DSP custom
Description Property file describing a Table.


File tag.p


P a g e | 13

Format DSP custom
Description Property file describing a Tag.


File viewpoint.p
Format DSP custom
Description Property file describing a Viewpoint.



P a g e | 14

On caches

The various caches are at the core of what makes PC such a fast and responsive solution. It also serves
as protection to ensure that cubes in the data layer aren't unnecessarily accessed. Even though they, for
the most part, are highly efficient at answering queries, in many cases it makes a lot of sense to ensure
that they get as little traffic as possible.
There are multiple levels and forms of caching so let's go through them one by one:

The Metadata cache

A lot of the time we need to know things about the entities that reside in the cube we are working with.
It may be to be able to expand members in a filter on a Canvas. It may be to be able to find a specific
KPI. It may be to be able to do all sorts of other more or less interesting things that need doing while we
are transforming queries. To be able to do this, without drowning the cube in metadata queries, all this
data needs to be cached. It also needs to be cached on a per-user (from the cube's point of view) basis.
That means that for every account accessing the cube there needs to be a cache. One quickly realizes
that this means that Anonymous, Basic and NTLM are superior here in terms of performance from a
cube point of view and this is correct. However they do have shortcomings in terms of the granularity of
security that they provide. And it is of course possible to create n roles for n users using account
mapping so that n olap accounts are also created. Which basically creates the same kind of scenario as a
delegatable credentials (i.e. Kerberos) one. This is however unlikely and beyond the scope of the
discussion here. The point is that as much information as possible is cached on retrieval to ensure that
we don't ask the same question twice for a particular user unless the cube has been processed in which
case all caches are instantly invalidated.
This cache is largely uninteresting from a performance point of view. There are however some
implications that need to be considered. Most, if not all, of the data contained therein is String based
and to reduce the amount of memory used we use intern() to load and store these String instances in
the non-heap memory. This means that for very large cubes you will need to consider adding -
XX:PermSize=256M (where 256M basically means that 256 MB is used to store this data). Huge is a
relative term here. But if you are looking at caching tens of thousands of members then consider that
you can cost each member as 6KB approximately. Basically for each thousand you need 6 MB set up, the
default size is 64 MB so unless you are running into the absolute tens of thousands you should be ok.
However, if you know you have one or more very large cubes, consider using PermSize to ensure that
your users don't suddenly face error messages due to out of memory conditions.

Configuration options

There is discussion above about how to setup -XX:PermSize, this is really the only configuration option
that we allow - so far. There has been discussions about allowing the administrator to restrict caching
for certain hierarchies to reduce the memory footprint (this would then be a trade off against cube
metadata queries) but nothing conclusively has come out of that yet. If you feel that this would be
valuable functionality for you then please get in touch with us and let us know and we will consider it.

The Query cache


P a g e | 15
All queries create a result set in the form of a TableModel. This is cached and along with it we also cache
the renderings made with that particular result set. Note that these are user specific (again, talking
about cube users rather than PC users) so there is no risk of information leakage. This cache is important
in various ways. If you are running heavy queries then it becomes very important as it offloads the cube
by ensuring that groups of users share result sets between them. Note that the cache is access ordered
and when booting out anything over dsp.cache.maxqueries it will remove the LEAST used result set. You
probably understand that if you can deal with the memory overhead of the result set caching you are
going to over time ensure that the most frequent queries stay cached and highly responsive - just the
way you want it. Intrepid explorers that dive into the more advanced features of PC and do their own
analysis will find that their queries take slightly longer but at the same time their performance will
improve dramatically over a scenario where no caching is done at all since they are basically getting
access to a lot more of the processing capacity of the data layer than they would normally have.


dsp.cache.maxqueries (default value: 500)

This is the number of result sets that are stored. 500 is a decent size for a small installation with a
constrained memory footprint. If you run the service with dsp.log=3 (zenith.properties) you will be able
to see the current hit rate for the cache updated - if you want to see this live you can always run
/bin/PC.bat to see the log scroll by live in a command line window. Just make sure you stop the
"Performance Canvas" service first.

dsp.cache.expire (default value: 6000000)

This is the time until expiration of the cache. Here your knowledge about your local cube becomes
important. If it changes on a daily basis you may want to set this to some value that reflects that. Not
that if you have more than one cube you can set individual expirations by using
dsp.cache.expire.<cubename> (i.e dsp.cache.expire.DspSalesDemo=10000000000). Don't use short
values. It's pointless and it's better in that case to set the dsp.cache.maxqueries property to 0 or some
very low value (if you think that would be appropriate) to reduce the amount of caching going on for
resultsets.
Note - values are given in milliseconds

Client side caching

For the sake of completeness one should also note that there are client side caches as well. Two are
especially noteworthy, the render cache and the entity cache. Basically these are - in a way - client side
versions of the server side caches. The render cache is per page component and ensures that we don't
request renderings that we already have. This is only available in /app/client as chart settings are
constantly in potential flux in /app/designer. The entity cache is however even more important in
/app/designer as it ensures that any queries for cube entities (hierarchies, members, measures etc) are
stored client side. Basically the queries are of the form "Give me all the children of entity X in cube Y" or
"Give me all entities of type X for cube Y". These are stored and reused. Note that the measures are
invalidated when a new Calculated member is created and stored for reuse. This ensures that this
member is reusable on the next gem design/drag and drop excursion.


P a g e | 16
There are some minor differences in how different browser retrieve information as well which affect the
overall traffic profile of the PC server. If you are using IE clients only you will note that there is less
information sent "up front" to people using the /app/designer application. This is because Internet
Explorer, though surely a commendable piece of technology in other ways, is perhaps a tiny bit deficient
in terms of JavaScript performance compared to the market leaders in that space (i.e. everyone else).
This won't have a huge effect but it's worth knowing that the load on the network becomes differently
distributed when people are using IE. Enough said.


None.
We are considering adding some persistance handling a la HTML5 but it is very dependent on customer
feedback. If people have primarily static cubes (i.e. cubes processed weekly or less) then this might be a
good idea to give even better performance. But it remains to be seen.

Related subjects

Sometimes people can (inadvertently) create trivial queries that result in huge datasets, when
crossjoining two attribute hierarchies together it's easy to end up datasets that can easily eat up every
single scrap of processing capability that the browser has to offer. This is not strictly related to caching
but it is tangential so we cover it here. To get around this issue you can define a maximum resultset size
in number of cells.


dsp.memory.resultsetmax (default: 50 000)

This is the number of cells that a TableModel can contain. The process will stop once the dimensions of
the table exceeds this number and the end user will get a message informing him or her that the result
set is too large to be handled


P a g e | 17

On query based security

PC introduces the capacity to constrain result sets in situations where your security setup doesn't
include Kerberos. There are a multitude of reasons why this might be the case. Kerberos is notoriously
complex and some organizations simply are not willing to take the step. Another reason might be that
this might not be an internal solution. For an extranet, a mobile solution or something else where
delegated credentials simply aren't applicable query based security becomes a very powerful tool. It
should also be noted that some users claim that delegated credentials and granular dimension based
security is a very computationally expensive proposition. Decision Support Panel has no opinion in this
matter but simply allows people of differing opinions to setup security as best fits their intended
audience and infrastructure.

So. There are two ways of doing query based security. One is by narrowing only specific queries. This can
be done by using a placeholder in the queries which gets automatically replaced before sent to the cube.

Here is an example. We design a gem that shows actual for a specific set. The base query looks like this:

SELECT
{[Geography].[Geography].[Country].MEMBERS} ON COLUMNS,
{[Measures].[Actual]} ON ROWS
FROM [DspSalesDemo]

Now, if we happened to have a hierarchy in the cube where we have our login names as user defined properties
we can in fact do:

SELECT
FROM [DspSalesDemo]
WHERE ( { FILTER({
[User].[User].MEMBERS},[User].[User].CURRENTMEMBER.PROPERTIES("Login") =
"$PC09_USER")} )

Note the usage of $PC09_USER. It is a placeholder that will get replaced with the username of the current Principal
(i.e. the current logged on user). In this case, let's say Alan logs on to PC and opens his favorite canvas with the
gem using this query on it. The query will then be modified to read

SELECT
FROM [DspSalesDemo]
WHERE ( { FILTER({
[User].[User].MEMBERS},[User].[User].CURRENTMEMBER.PROPERTIES("Login") = "Alan")} )

Note: there are slightly more efficient ways of doing this where the login name is actually used as part of
the MEMBER_UNIQUE_NAME (like [User].[User].[$PC09_USER] but this is simply not always the case,
hence the above explanation).

Now, this would require you to modify all your queries. However, if you do have a way of filtering these
queries through a user based hierarchy you can do this automatically for all queries.


P a g e | 18
In zenith.properties add two lines.

dsp.filter.user=true
dsp.filter.user.definition=[User].[User].[$PC09_USER]

Note: if you have a hierarchy which stores the login name in a property then you can use

dsp.filter.user.definition=FILTER({[User].[User].MEMBERS},[User].[User].CURRENTMEMBE
R.PROPERTIES("Login") = "$PC09_USER")

This will modify every single query going through the system (no exceptions) and will provide a pretty
decent level of security - although it won't protect your data if someone for example downloads a
Microsoft Excel(tm) pivot file as they will then have access to all data.

IMPORTANT: If you use this you will want to use filters that are dependency filtered as that will allow
you to ensure that the contents of the individual slicers are only the members that a specific user
should be allowed to see.


P a g e | 19

On secure socket layer (SSL) and its implications

IMPORTANT NOTE: In order to use SSL you NEED to run the 32-bit JRE. If your copy of PC is installed on
a 64-bit machine you have to download the 32-bit JRE from Oracle (for Windows x86) and replace the
contents of the <INSTALL_DIR>/runtime folder with the contents of the JRE. The reason is that the
required sunmscapi.dll is not shipped with the 64-bit JRE.

The most important thing to remember about SSL is that even though it adds to the overall security of
an installation it does come with a cost. And that if you are using SSL towards PC you really should
consider using SSL between the Performance Canvas server and the IIS instance. Note: if you are putting
up a outwardly accessible instance, for example on your extranet or even as part of your public site then
SSL may in certain cases be preferable.
However, the cost is pretty straight forward, SSL costs CPU cycles and those CPU cycles increase as the
number of users increase. There are tons of resources on the internet on how to figure out what kind of
hardware to throw at the problem but it requires some understanding of the traffic profile and the
usage model.
Your mileage will vary.

Setting up SSL is slightly less straight forward than one might wish but hang in there, you will get there.

First of all, here are the configuration options:

dsp.security.ssl =true
dsp.security.ssl.protocol=TLS
dsp.security.ssl.keystoretype=JKS
dsp.security.ssl.keystorepass=ChangeThisPassword
dsp.security.ssl.keyalias=performancecanvas

Now. In order to be able to get a certificate from a CA (Certificate Authority) you have to create a CSR,
or a Certificate Signing Request. Once you send this to the CA they can create a Certificate which will let
clients know that the website is secure. Here's how you create a CSR.

Start a command line window and navigate to the installation directory where Performance Canvas
resides. Then run the following command

runtimebinkeytool -genkey -alias performancecanvas -keyalg RSA

This will generate a key and you will be prompted to supply a password. This is the password you will
supply as the value for dsp.security.ssl.keystorepass so make sure you remember it.
You will also be asked to supply various information about the company and so on and this is the
information that clients accessing the server will see in the certificate so be sure to fill it out
appropriately.
Finally you will be asked to give a password for the key itself (not the keystore), you HAVE TO use the
same password as you did before. Just pressing the ENTER key will ensure that this happens
automatically.


P a g e | 20
In order to get a true Certificate from a Certificate Authority (like Thawthe or Verisign), you should now
create what is called a CSR. This Certificate Signing Request is used by the CA to create the Certificate
that will later identify your server as secure to the end users. Here's how you do that.

Open a command line window and again navigate to the installation directory of performance canvas.
Create the CSR by running

runtimebinkeytool - certreg -keyalg RSA -alias performancecanvas -file certreq.csr
-keystore .keystore

This will create a file named certreq.csr that you send to the Certificate Authority of your choice, they
have ample documentation on their websites on how to make certificates. Within a short time frame
you will get a Certificate back. This has to be imported into your keystore. However, you have to start by
imported the Root or Chain Certificate first.

Go to the Certificate Authority you got your certificate from and download their Chain or Root
Certificate. Consult their documentation if you can't find it. Once you have downloaded that, start a
command line window and navigate to the installation directory of Performance Canvas and import it
with the following command

runtimebinkeytool -import -alias root -keystore .keystore -trustcacerts -file <the
filename of the root certificate>

Once that is done you can proceed with importing your own Certificate by running

runtimebinkeytool -import -alias performancecanvas -keystore .keystore -
trustcacerts -file <your certificate>

And you are all set. Once you update the zenith.properties file in the Performance Canvas installation
directory with the configuration options described above you will be all set and a quick restart will make
your Performance Canvas instance highly secure. (Note: if you want to use an internal certificate then
you have to use PKCS11 or PKCS12, refer to the OpenSSL documentation on how to turn a Microsoft Key
Manager certificate into a valid SSL certificate. This will require changing the keystoretype value as well.)


P a g e | 21

On loose clusters

There are situations where traffic warrants the use of several machines (or perhaps you simply want to
ensure better availability/response times). Moving to enterprise class licenses with support for
distributed caches is expensive and a better solution on the way there may be to consider doing loose
clustering. This centers around the fact that instances can share a single store location. This may be on a
networked disc somewhere where the /store folder is located. It contains all the definition files and as
long as you expect most of the traffic to be reads this really shouldn't be problematic at all. But it is your
network. Making predictions on the effects on it would be presumptuous. If you have good bandwidth
and hardware then by all means try it - it is a very viable solution. If you have a shaky network with loads
of timeouts and congestion then perhaps this isn't for you.

Basically the simplest scenario is that you have nodes A through Z and they all share a single store
folder. Their core configuration is unique, that means that they can be running on different ports if
that's what you want. However in the vast majority of the cases you will be running this with some form
of load balancing (DNS Round robin perhaps?) in which case they will all be identical.
What you need to do is make sure that they all have

dsp.store.path=<path to the store folder>

in their zenith.properties file. That's it. Let's say you have your networked disk on
Server01D$rscstore then simply add

dsp.store.path=Server01D$rscstore

to the zenith.properties files and you are all set. All your instances will now be running using the settings
and object definitions there. They will all have their own metadata caches however (be aware of this, it
will increase metadata traffic towards your cubes so you will have to keep an eye out for 503 errors in
the logs, signifying that you have contention issues in the IIS and need to increase the number of
workers/threads in order to keep up with demand).


P a g e | 22

On locales and languages

We understand the need for supporting multiple languages and Performance Canvas is built from the
ground up to support multiple locales both on the client and the server side. However, for performance
purposes you use a dedicated server per locale. This is on order to be able to effectively utilize the
naming cache, a cross-locale server would not be efficient as the number of values needing caching
would increase dramatically.

So, how do you set this up?
In the simplest case there is already an existing locale/translation of the client side. In this case the only
thing you have to do is set the server locale accordingly. You do this either by using the administrative
console at /app/admin or by changing the dsp.locale property in zenith.properties. NOTE: PC uses the
<ISO-language>_<ISO-country> code. This means that using numerical codes will NOT work. Here is an
example. The default configuration is
dsp.locale=en
This means that english is used. Not en_US (which is US English) or en_UK (which is UK english) but en
which is a common english translation suitable for all english speaking regions but which does not take
into account locale specific spelling. If you for example want to use french instead there are several
types of french.
dsp.locale=fr
dsp.locale=fr_CA
dsp.locale=fr_FR
are different in that they refer to different locale files. You can find the translations in
/store/settings/locale. The default (i.e. "en" files are in the /store/settings/locale/default directory and
these are the files that should be used as the basis for translation should you opt to implement a new
language for yourself or your customers)


P a g e | 23

On Kerberos
Kerberos is a notoriously complex protocol. It is highly secure and solves a lot of the typical issues with a
modern heterogenous IT environment but at the same time it can be problematic to set up and even
more problematic to troubleshoot. This document will explain how to setup Kerberos to work with
Performance Canvas. It is assumed that the reader has a basic knowledge of Active Directory
administration and knows one or two things about configuring a DNS as well. But if you don’t we have
tried to give as much information as possible to ensure that you are successful.

IMPORTANT
It is easy to assume that the hostname and username in the description below are different. They are
not. You will want to setup a user and a host with the EXACT same name. So if you create a user named
pc07 then the host will have to be called pc07 as well. This is easily overlooked and a common source of
error.

Prerequisites

1. To be able to use Active Directory, the Performance Canvas service must run by an AD account
and not by Local System.
2. That user account must have write permission in the Performance Canvas installation folder.
3. That user account must also have full rights to all cubes that are accessed by Performance
Canvas.

Step 1: Creating the account

The first thing you need to do is to create a new account that will act as the service (not the same
account as running the Performance Canvas service described above). In this particular example we will
call this user pc07krb5. Note that this name will also be the server name used to access the Performance
Canvas so choose something that is a good and descriptive hostname if people are going to be accessing
it directly in their browsers. Note that Kerberos as a protocol is notoriously case sensitive and even if
much of that is a non issue in a pure Microsoft environment it is considered best practice to stick with
lower case names.

In this example we are creating a new user in the Microsoft Active Directory™ with username pc07krb5
and the password pc07k5#123. Note that the username and password can be anything you want them
to be.


P a g e | 24

(Figure 1: setting up the username)

(Figure 2: setting up the password for the user – note the “password never expires” setting)


P a g e | 25

(Figure 3: Finalizing the user creation, just verify your settings and click finish)

Step 2: Ensuring that the account can handle delegation

Now you want to make sure that the account you created is trusted to do delegation. Delegation is the
Kerberos mechanism that allows a server to impersonate a user without having access to his or hers
actual credentials, instead it receives a forwardable ticket from the Kerberos server. To do this you need
to locate the newly created account under Users in your Active Directory. Now right click on it to open
the properties window. Select the tab named “Account” and make sure that the checkbox marked
“Account is trusted for delegation” is checked.


P a g e | 26

(Figure 4: setting the delegation flag on the user account is done on this tab in the user account
properties)

Note that certain Active Directory setups will NOT have this checkbox, in this case perform steps 3 and 4
and go back. Now there should be a tab called Delegation showing. This will include a radio button that
allows you enable the same option.

Step 3: Adding a host name

Kerberos uses what is known as SPN (Service Principal Names) as a way to locate services. In order for
that to work there needs to be an entry in the DNS called an A record that the Kerberos server can
find. Open your DNS management console (logged on to the domain controller server you can find this
under Administrative tools). Locate the domain you want. Note that if you are working on the domain
DOMAIN the zone you are looking for is called domain.local from a DNS perspective. Locate that under
Forward Lookup Zones, right click the folder and add a new A record. To be able to do this you will need
the IP address of the machine that Performance Canvas will be running on. If you don’t have it you can
locate the NETBIOS name in the DNS. If the machine is for example called server4 you can just locate
that name in the list. Neither of the checkboxes need to be checked for Kerberos to work. Note that the


P a g e | 27
hostname you want to use is exactly the same as the username you just created, in this case pc07krb5.
You don’t have to add the domain part itself, it will be taken care of automatically.

(Figure 5: the username has been entered as the hostname and we can now click Add Host)

Step 4: Generating the keytab

A keytab file is a shared secret that allows the service to communicate with the Kerberos service as a
service. This is the most complex part of the setup. You have to open a DOS window and navigate to
some directory where you can create files. First write: “ktpass” (without the quotes) on the command
line and press enter. If you get an error saying that the file can’t be found then you have to install
ktpass. It can be found on Microsoft’s website at http://support.microsoft.com/kb/892777.
Once you have downloaded this and installed it you can run the ktpass after exiting the DOS window and
starting it again.

Now write

ktpass -princ “HTTP/pc07krb5.dspDevDomain.local@DSPDEVDOMAIN.LOCAL” -mapUser pc07krb5
-pass pc07k5#123 -crypto RC4-HMAC-NT -out pc07.keytab
This will generate a file called pc07.keytab. Note that you need to replace the username, password and
domain parts with your particular information. If you are in the domain MYDOMAIN and just create a
username called pc07 with the password pwd123 then you would write


P a g e | 28
ktpass –princ “HTTP/pc07.mydomain.local@MYDOMAIN.LOCAL” –mapUser pc07 –pass pwd123 –
crypto RC4-HMAC-NT –out pc07.keytab
Not only will this generate a keytab, it will also associate the user with the SPN
(HTTP/pc07.mydomain.local@MYDOMAIN.LOCAL).

(Figure 6: This is what it looks like when you have created your keytab, note that the warning about non-
matching ptypes can be safely ignored)

You may get an error message saying that RC4-HMAC-NT is not supported. In this case you need to use
DES-CBC-MD5 instead. This also means you have to change the values in the zenith.properties file
(found in the Performance Canvas installation directory) from

dsp.security.krb5.conf.default_tgs_enctypes=rc4-hmac
dsp.security.krb5.conf.default_tkt_enctypes= rc4-hmac
to

dsp.security.krb5.conf.default_tgs_enctypes=des-cbc-md5 rc4-hmac
dsp.security.krb5.conf.default_tkt_enctypes=des-cbc-md5 rc4-hmac

This will enable the use of des-cbc-md5 as an encryption type for Performance Canvas.

To verify the SPN mapping you can run the command

setspn –L mydomainpc07
Or in our example

setspn –L dspDevDomainpc07krb5
This will list the associated SPN:s so you can verify that everything is correct. If there is a problem you
can delete the SPN by writing

setspn –D HTTP/pc07.mydomain.local@MYDOMAIN.LOCAL mydomainpc07
And then you can do the ktpass keytab generation over again.


P a g e | 29

Step 5: Installing the keytab file

Now that you have a keytab file you have to move it so that Performance Canvas can find it. The best
way to put it is in the Performance Canvas installation directory. Copy the file and transfer it there. Now
you have to make sure to tell Performance Canvas where it is. If it is running then stop the service. Now
open the zenith.properties file that you can find in the installation directory. Locate the property called

dsp.security.krb5.conf.default_keytab_name
Now you want to give the complete path of the keytab file, like this

dsp.security.krb5.conf.default_keytab_name=c:program filespc07pc07.keytab
Once that is done you can start the Performance Canvas service again. Congratulations, the hard part is
now done. If you now navigate to the security tab in the Administrative interface you can select the
“Windows Integrated Security” mode.

Step 6: Access Performance Canvas by using the new DNS record as URL

Once you have selected Windows Integrated Security and clicked save you can restart the service and
try it. In this example the URL will be http://pc07krb5

Make sure you do not use a browser on the same machine as Performance Canvas is running on. In
many situations Active Directory forces that browser to use NTLM to access local machines and this will
not work as the Performance Canvas server is now in Kerberos only mode.

Do's and Don’ts while installing the Kerberos setup

DO

• While creating the account (Step No.1) – Always create a new user account.

• While writing the ktpass command as given below – (Step No. 4)

ktpass – princ “HTTP/pc07.mydomain.local@MYDOMAIN.LOCAL” –mapUser pc07 –pass pwd123 –
crypto RC4-HMAC-NT –out pc07.keytab

• Write domain name before the username entered.

Example for User – PC

mydomainPC


P a g e | 30

DON’T

• While creating the account (Step No.1) – Do not use an already existing account.

Troubleshooting
• First of all, make sure that you have an entry called dsp.security.useNativeGssApi in your
zenith.properties file (see Step 5 above). If you don’t then add it to the file like
this dsp.security.useNativeGssApi=false. If the value is true then change it to false. Using true
will make it fail.

• Make sure that the host is trusted by the browser, if the browser is showing that the host is part of the
internet zone then you have to add the hostname to trusted sites. You can find the icon in the bottom
bar of your Internet Explorer. If it shows an icon looking like a very small earth then you are in the wrong
zone and the browser will attempt to use NTLM. Doubleclick the icon and add the host to trusted sites in
your local intranet zone

• Check that the host you are accessing has the exact same name as the user you created. This is
extremely important. The easiest way to test this is to open a DOS window (Run CMD) and write ping
<username> (if you created the user pc07 you would write “ping pc07” without quotes). If that fails with
an error message, you haven’t created the right user.

• If you can access PC but not the cubes you may have inadvertently setup an SPN at some point which
is interfering with the HTTP on the host machine. Use setspn –L MYDOMAINusername to check that
you don’t have any SPNs other thanHTTP/username.mydomain.local@MYDOMAIN.LOCAL.

• If you can’t access the Active Directory to setup users for your role, make sure that the username you
are using is just the username, don’t use MYDOMAINusername. Just username. The domain name is
specified elsewhere


P a g e | 31

On development

We have worked pretty hard on making sure that PC is more than just a design tool. It is a pretty
powerful development tool as well, regardless of whether you want to design mash ups, complex
dashboards or pretty much whatever you want from the web client side or if you want to do deep
integration into existing enterprise applications, delivering analytics functionality to places where people
actually see it in context. In this section we will try to describe how to go about these things by
describing a number of well defined basic tasks that are common and that would form the basis of a
solution. This will make your life easier and coupled with the information in appendices E through G you
should find enough (hopefully) to let you go about your work without having to scratch your head too
much.
We know as well as you do that good documentation is essential to a developer and we have tried to
put everything as clearly as possible but if there is something you are still wondering about then don't
hesitate to let us know so we can make this documentation better.

Since developers will work in different environments any code will be referred to as pseudo code and
will be sort of a bastard child of Java and C# since those two languages are the most commonly used for
building enterprise applications today. If you are working in a different environment completely then
hopefully at least you will be able to glean sufficient information from the examples that you can still
understand what should be going on and translate that to your own work situation. Mileages may vary.
As usual.

On direct API usage

This will be a mercifully short chapter. Is it possible to use the API directly. Yes. Are you allowed to? No,
not without licensing the PC technology in an appropriate manner. Not doing that will put you in breach
of the EULA and all sorts of bad things will happen. Fire. Brimstone. Wrath of least favorite deity. That
kind of thing. So don't. We know it's cool and neat and all. But be a cool person. License it. Then you will
get the appropriate documentation. The web services are just as useful. Promise.

On web services

On ConfigurationService

First of all. You will find the wsdl by accessing

http://yourserver:yourport/services/ConfigurationService?wsdl

Or you can just look in Appendix E if you have the stomach for reading WSDL files with the naked eye.


P a g e | 32
On methods

Below the methods in ConfigurationService are described along with parameters and return types. For
more in depth information, read the task sections to find out how they are used in various scenarios.

addCube

addCube(string url, string sqlServerName, string olapDBName, string cubeName, string
cubeDisplayname)

PARAMETER DESCRIPTION
url A valid URL pointing to an OLAP pump running on an IIS instance
(or in the case of other XMLA providers, the appropriate host).

Typical example: http://localhost:81/olap/msmdpump.dll

sqlServerName The SQL Server name
olapDBName The name of the OLAP database (or Catalog) where the cube
resides

cubeName The Name of the cube

cubeDisplayName The displayed name of the cube, becomes highly interesting if you
have autogenerated cube names

The method returns a boolean indicating whether the cube was added or not.

appendCubes

appendCube(string[] urls, string[] sqlServerNames, string[] olapDBNames, string[]
cubeNames, string[] cubeDisplaynames)

Note: all the parameters are arrays, the method expects one (1) value per added cube, meaning that all
of the arrays should have the same length. The parameters are exactly the same as in addCube above.

url A valid URL pointing to an OLAP pump running on an IIS instance
(or in the case of other XMLA providers, the appropriate host).

Typical example: http://localhost:81/olap/msmdpump.dll

sqlServerName The SQL Server name


P a g e | 33

olapDBName The name of the OLAP database (or Catalog) where the cube
resides

cubeName The Name of the cube

cubeDisplayName The displayed name of the cube, becomes highly interesting if you
have autogenerated cube names

The method returns a boolean indicating whether the cube was added or not.

constructCanvas

This method requires a bit of explanation perhaps, it will automatically construct a canvas given a set of
slicers and a set of gems.

constructCanvas(string canvasSettings, string[] slicers, string[] gems)

canvasSettings The base settings for the new canvas, is it mobile or not, what's the
current status and so on

slicers An array containing the slicer uids for inclusion in the canvas filter
block

gems An array containing the gem uids for gems that should be displayed
on the canvas

The method returns a string containing the UID of the newly constructed canvas.

deleteCanvas

deleteCanvas(string canvasUid, boolean deepDelete)

canvasUid The UID of the canvas you want to delete

deepDelete A boolean signifying whether all objects used on the canvas should
be deleted as well (basically a recursive delete). True deletes
everything, false deletes the canvas only.


P a g e | 34
The method returns a boolean signifying whether the delete was successful or not.

exportCanvas

exportCanvas(string canvasUid)

canvasUid The Uid of the Canvas to be exported

The method returns an array of strings, each string containing one object that is used on the Canvas.
This structure can be used directly with the importCanvas method.

flushCache

flushCache()


The method has a void return type. The only thing it does is attempts to flush the cache. Note that this is
synchronous so it may take a while for the method to return.

getConfigurations

This method retrieves a list of entities that match the supplied filters, if no filters are supplied then all
objects are returned. Filters are supplied in standard NVP format (i.e '<name>=<value>' - so, if you
wanted to get all published enterprise canvases you call this method with the arguments "canvas" and
{"canvas.basic.scope=ENTERPRISE", "canvas.basic.status"=PUBLISHED}

getConfigurations(string type, string[] filter)

type The object type you want to look for. Valid values are for example

- canvas

- gem

- chart

- table


P a g e | 35

- measure

- slicer

- filter

Etc..
filter An array containing the filters to be used for selecting a subset of
the total number of objects of the supplied type

The method returns a string array containing the objects that matched the query

getUniqueConfiguration

This method retrieves a unique (single) configuration for a specific object type. Note that sending "null"
for the ID will send the default base configuration for specified object type.
IMPORTANT: if you just want to check whether the server is responding, you can actually call this
method likes this
getUniqueConfiguration("canvas","ping");
which will give you an empty string as a return value.

getUniqueConfiguration(string type, string uid)

Type The object type you want to look for. Valid values are for example

- canvas

- gem

- chart

- table

- measure

- slicer

- filter

Etc..
uid The specific UID to load. A null or empty string will return the
default configuration. Sending "ping" will send an empty string
back.


P a g e | 36
The method returns a string containing the configuration represented as key-value pairs.

importCanvas

This method is the import version of exportCanvas. It takes an array of object definitions and stores
them locally.

importCanvas(string[] components)

components An array containing all the objects used on the canvas as well as
the canvas itself. Each object has it's own string in the array. This is
primarily used as a complement method to exportCanvas.

The method returns a string containing the uid of the newly saved Canvas.

saveConfiguration

This method saves the settings for a requested object type. Note that we don't do any type checking or
validation here so use all the save methods with appropriate care

saveConfiguration(string type, string settings)

type The object type you want to save. Valid values are for example

- canvas

- gem

- chart

- table

- measure

- slicer

- filter

Etc..
settings A string containing the KVP settings of the object


P a g e | 37
The method has a void return type

saveConfigurationAsNew

This method saves the settings for a requested object type as a guaranteed new object. This can be used
to clone objects or save minor variations in a an easy way. Note that we don't do any type checking or
validation here so use all the save methods with appropriate care

saveConfiguration(string type, string settings)

type The object type you want to save. Valid values are for example

- canvas

- gem

- chart

- table

- measure

- slicer

- filter

Etc..
settings A string containing the KVP settings of the object

The method returns a string containing the UID of the newly created object

simpleConstructCanvas

This method is an even simpler front for constructCanvas(). In this method you simply supply a list of
uids for the objects you want to add, without keeping track of the object types.

simpleConstructCanvas(string canvasSettings, string[] uids)

canvasSettings The base settings for the canvas you want to create

uids The uids for all the objects you want to use on the canvas, note


P a g e | 38

that anything which doesn't point to a gem or a slicer will be
discarded.

The method returns a string containing the uid of the newly constructed canvas.


P a g e | 39
Task: Retrieving an existing object
Retrieving an existing object requires you to have two distinct pieces of information. One of them is the
object type (is it a canvas, a gem et cetera), the other is the unique identifier. Now, the uniqueness of
these identifiers is local. They are not guaranteed to be globally unique. However, if a UID is generated
that matches an existing one in the system it WILL be discarded so there is no risk of accidentally
overwriting existing information.

Once you have this information you use the web services to retrieve the object. The method you want
is:

getUniqueConfiguration(type, uid)

This method returns a string containing the properties of the object as key value pairs in the usual PC
fashion. Let's say we retrieve a tag with the uid 1234.

pseudo code below

string result = getUniqueConfiguration("tag","1234");
string[] properties = result.split("n");
Map<string,string> propertyMap = new HashMap<string,string>();
foreach(string property;properties) {
string[] keyValue = property.split("="); // note this is error prone, a value
can contain = signs
propertyCollection.put(keyValue[0],keyValue[1]);
}

Now you can retrieve and edit the properties before using or saving the object.


P a g e | 40
Task: Finding a list of objects

It's not uncommon to have a need to retrieve a list of objects from the server. In the simplest case you
want to discover all the canvases (for example) on a specific PC server. Use the method

getConfigurations(string type, string[] filters)

In this example task we won't be using filters. You can pass null for this argument. Note that this method
returns an array of strings, meaning that each object will be contained in it's own string representation
of key value pairs (see Task: Retrieving an existing object for more information about this)

That means that to retrieve a string array containing all the objects you are looking for (and that you
have access to) you do

getConfigurations("canvas", null);

And that's it. (Note: depending on your WS framework this can be more or less work and the way to
accomplish this can be quite different but this will give you the general idea at least. Don't be afraid to
play around with this stuff. If you don't want to use the production server for development then either
download a trial version or use the development license that should come with all licenses of non-
embedded PC.


P a g e | 41
Task: Finding a list of objects that match a certain filter

Now that you know how to retrieve a list of objects it's time to start filtering your results. A filter is
represented as a key value pair. Let's say you want to find all gems that are in a PUBLISHED state. The
property name is gem.basic.status and the appropriate value is PUBLISHED (if you want to find out more
about properties, please have a look at Appendix C where all of the object types are described in mind
numbing detail).

You populate your string array used for filters with one string containing

string[] filters = new string[]{'gem.basic.status=PUBLISHED' };

and use the getConfigurations-method again.

getConfigurations("gem", filters);

to retrieve your array of objects as string representations. You can use more complex combinations of
filters obviously, here is an example which retrieves all published gems that are charts and use the
DspDemoSales cube.

string[] filters = new string[]{"gem.basic.status=PUBLISHED",
"gem.basic.viewtype=CHART","gem.basic.datasource=DspDemoSales"};
string[] result = getConfigurations("gem",filters);


P a g e | 42
Task: Creating an object
Creating a new object requires you to first fetch the settings, second modify them and third sending the
whole thing back to the server. In this example we will construct something simple without relationships
to other things, normally - for example in the case of a gem - object creation will require keeping track of
multiple Performance Canvas objects of different types.

In this case we will create a tag. The method you want to use is:

getUniqueConfiguration(type, uid)

This method returns a string containing the properties of the object as key value pairs in the usual PC
fashion. This time however we will send in null as the uid argument.

pseudo code below

string result = getUniqueConfiguration("tag",null);
string[] properties = result.split("n");
Map<string,string> propertyMap = new HashMap<string,string>();
foreach(string property;properties) {
string[] keyValue = property.split("="); // note this is error prone, a value
can contain = signs
propertyCollection.put(keyValue[0],keyValue[1]);
}

Now you can retrieve and edit the properties before using or saving the object. When you are ready to
save the tag in question you use the following method:

saveConfiguration(type, settings)

Note that settings is a string containing all the key value pairs that would look like this

value.a=a
value.b=b
value.c=c

pseudo code below

string uid = saveConfiguration("tag",settingsString);
//now we have the uid and can actually access the object directly in case we need
//to do some further modification, in this case we might just want to change the name
string tagData = getUniqueConfiguration("tag",uid); //this will fetch us the object
we just created
tagData = tagData.replace("name","newName");
saveConfiguration("tag",tagData);
//note what we just did is not a recommended way of doing things, just an example


P a g e | 43
Task: Exporting a canvas

Sometimes you will end up in a situation where you have a set of canvases on one PC instance that you
would like to deploy on another one. Finding it in the store and resolving all the relationships may be
extremely tricky however. We supply a simple and straight forward method for retrieving (or
"exporting") one or more canvases programmatically through the web services interface.

The method to use is:

exportCanvas(uid)

This method returns an array of strings, one string for each associated object (including gems, charts,
tables, filters, slicers and so on). In order to get the appropriate canvas you can always use the filtered
search capabilities (see "Finding a list of objects that match a certain filter").

pseudo code below

string uid = "1234";
string[] objects = exportCanvas(uid);

Now that you have your canvas represented as an array of strings you can import that into another
Performance Canvas server instance.


P a g e | 44
Task: Importing a canvas
So now you have successfully exported a canvas from a Performance Canvas Server and you want to
install it on another one. The method you would want to use is:

importCanvas(objects)

In fact this is so simple that a pseudo code example would be completely unnecessary. Once you have
done that the canvas and it's parts are available for the users on the import server. Well done.


P a g e | 45

On RenderingService


http://yourserver:yourport/services/RenderingService?wsdl


On methods
Here are all the methods of the RenderingService described with parameters and return types. For more
information on how to use them, check out the task section following the method definitions.

getChart

getChart(string mdxQuery, string settings, string format)

mdxQuery A valid query towards a cube which is mapped and installed in the
Performance Canvas instance. If the cube is not mapped then an
error will be thrown

settings Valid chart settings, these can be retrieved and modified using the
methods in ConfigurationService (see previous section)

format A string having one of the following values:

- html
- pdf
- image
- ppt

The method returns a string containing a a partial url, using the ContentService you can instantly
download the file which has already been generated.

getChartTypes

getChartTypes()


P a g e | 46

None

The method returns an array of strings containing all the available chart types on this Performance
Canvas instance

getColorSchemes

getColorSchemes()

None

The method returns an array of strings containing all the available color schemes on this Performance
Canvas Server

getTable

getTable(string mdxQuery, string settings, string format)

mdxQuery A valid MDX Query pointing to a cube which is mapped and
initialized in this Performance Canvas server

settings Valid settings for a Performance Canvas table. These can be
retrieved and modified using the ConfigurationService. Note - this
doesn't have to point to an exisiting object.

format A string describing what format you want the table in, valid values
are:

- html

- xls

- pdf


P a g e | 47

- image

- scaledimage

The method returns a string containing a a partial url, using the ContentService you can instantly
download the file which has already been generated.


P a g e | 48
Task: rendering a chart as an image
First of all you need to use the ConfigurationService to retrieve the correct base settings. Once you have
that you can modify the values, if you want to make sure you know what chart types and color schemes
are available you request them from the RenderingService and update the chart settings accordingly.
Once you are done and you have a valid query you can call the getChart() method and construct a URL
from the end result.

Pseudo code below

//see section on ConfigurationService for retrieving default settings, we will assume
//that the variable settings is a hashmap/hashtable containing our key value pairs
string[] chartTypes = getChartTypes();
string[] colorSchemes = getColorSchemes();
settings.put("chart.basic.type", chartTypes[0]);
settings.put("chart.basic.colorscheme", colorSchemes[0]);
//ok, now let's create a query
string query = "SELECT {[Geography].[Geography].[State].MEMBERS} ON
COLUMNS,{[Measures].[Actual],[Measures].[Plan]} ON ROWS FROM [DspDemoSales]";
string format = "IMG";

string file = getChart(query,toString(settings),format);
string url = "http://performancecanvashost:" + portValue + "/content/" + file;
//and you can retrieve your data from the URL


P a g e | 49
Task: rendering a table as Excel pivot

First of all you need to use the ConfigurationService to retrieve the correct base settings. Once you have
that you can modify the values, in this case we won't do anything at all since any changes would be
pointless as we are requesting an EXCEL_PIVOT. Once you are done and you have a valid query you can
call the getChart() method and construct a URL from the end result.

Pseudo code below

//see section on ConfigurationService for retrieving default settings, we will assume
//that the variable settings is a hashmap/hashtable containing our key value pairs
//ok, now let's create a query
string query = "SELECT {[Geography].[Geography].[State].MEMBERS} ON
COLUMNS,{[Measures].[Actual],[Measures].[Plan]} ON ROWS FROM [DspDemoSales]";
string format = "xls";
settings.set("table.basic.pivot","true"); //defines that we want a pivot and not a
//static excel file

string file = getTable(query,toString(settings),format);
string url = "http://performancecanvashost:" + portValue + "/content/" + file;
//and you can retrieve your data from the URL


P a g e | 50
On XMLAService


http://yourserver:yourport/services/XMLAService?wsdl


On methods

combine

This method combines two MDX queries. Note that they have to point to the same cube.

combine(string mdxA, string mdxB)

mdxA A valid MDX Query
mdxB A valid MDX Query

The method returns the combined query statement

filterByUser

This method injects a query based security part that is dependent on the query based security settings
of the server

filterByUser(string mdx, string userName)

mdx A valid MDX Query
userName The username to be filtered on

The method returns a filtered query statement or null if an error occured

getActions

This method retrieves all the actions available for the given entity.

getActions(string cube, string entity)


P a g e | 51

cube A valid cube name
entity A valid member in the cube

The method returns a string array containing the information about the actions available (one string per
action, data is in key=value format)

getChildren

This method retrieves the children of the specified type for a given member

getChildren(string cube,string parentName, int childType)

cube The name of the cube

parentName The unique name of the parent (if you want top level objects in the
cube, supply null)

childType Valid values are:
Dimension (0) (supply cube only)
Measure(1) (supply cube only)
Hierarchy(2) (supply cube and dimension)
Level (3) (supply cube and hierarchy)

Member(4) (supply cube and Level or Member

The method returns a string array, each string instance contains one child, data is in key=value format as
usual.

getCubeForMDX

Parses the MDX and gives you the appropriate cubename

getCubeForMDX(string mdx)



P a g e | 52
The method returns a string containing the cube name or null if an exception occured.

getCubes

This method retrieves data about all the installed and configured cubes in the Performance Canvas
service instance

getCubes()


This method returns a string array containing one string for each cube with data in key=value format.

getDrillthroughStatement

This method constructs a drillthrough statement for the given entity and the given mdx.

getDrillthroughStatement(string entity, string mdx)

entity A valid unique member name


The method returns a valid DRILLTHROUGH query for the entity or null if an exception occured.

getDynamicSet

This method supplies resolving of dynamic sets (or named sets) in the cube (or of any valid MDX
statement). What happens is that the snippet is used to create a query and that query is used to resolve
the set into distinct members.

getDynamicSet(string cube, string mdxSnippet)

cube A valid cube name for the PerformanceCanvas server instance

mdxSnippet The name of named set, a definition of some other kind (like
[Member].CHILDREN or ParallelPeriod or similar).


P a g e | 53
The method returns an array of strings, each strings containing the data for one of the members in the
resulting set. Data is in key=value format.

split

This method splits the MDX query into multiple sub queries based on the supplied hierarchy, it will
return one query for each member of the hierarchy used in the current query.

split(string hierarchy, string mdxQuery)

hierarchy The unique name of the hierarchy you want to split on

mdxQuery A valid MDX Query

The method returns an array of string arrays (string[][]), each string array contains two items, the first is
the member display name and the second is the MDX Query.

transform

This method transforms an MDX query . Note that names and treeOps have to have the same length.
Names also should refer to a single hierarchy. See below for valid values for treeOps.

transform(string cube, string[] names, int[] treeOps, string mdxQuery)

cube A valid cube name for the Performance Canvas server instance

names An array containing the unique names of the members you want to
transform.

treeOps The tree operands to be used (one for each name in names above).
Valid tree operand values are:

Children (1)
Siblings (2)

Parent (4)

Self (8)

Descendants (16)


P a g e | 54

Ancestors(32)
mdxQuery A valid MDX query

The method returns a transformed MDX query or null if the operation failed/an exception occured.

transformSingleMode

This method allows transformation for inline expansion (see inline drilldown in tables in Performance
Canvas to see what this means).

transformSingleMode(string cube, string[] names, string mdxQuery, int mode)

cube A valid cube name
names An array of unique names that should be expanded or closed

mode Mode signifies whether we should expand or close the members
supplied in names. Valid values are:
Expand (0)
Close(1)

The method returns a string containing the resulting query or null if an exception occured.

transformWithFilter

This method performs a transform based on the Performance Canvas filters. There are multiple kinds of
filters and many things you can do. Please refer to the section on filters for more on how to use this to
do complex modifications. Note: you can also build your own filters by subclassing
com.dsp.mdx.filter.TransformFilter. For more on this, see "On developing".

transformWithFilter(string filterProperties, string mdxQuery)

filterProperties A string containing the properties of the filter you want to use (see
ConfigurationService for descriptions on how to retrieve the
settings for Performance Canvas objects)


The method returns a modified/filtered MDX Query or null if an exception occured.


P a g e | 55


Embedding BI

Recomendados

Recomendados

Mais conteúdo relacionado

Mais procurados

Mais procurados (16)

Destaque

Destaque (6)

Semelhante a Embedding BI

Semelhante a Embedding BI (20)

Último

Último (20)

Embedding BI