Embedding BI

1,143 views

Published on

This guide will show you how to embed Performance Canvas into your own software offerings.

Published in: Business, Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total views
1,143
On SlideShare
0
From Embeds
0
Number of Embeds
4
Actions
Shares
0
Downloads
9
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

Embedding BI

  1. 1. Advanced administration and development guidelines & reference Niklas Derouche
  2. 2. Page |2Advanced administration and development - guidelines and referenceAbout DSPanelDecision Support Panel Intl AB is a Swedish company based out of Stockholm. It celebrated its 10thanniversary 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 thecompany started out focusing on the intersection of SharePoint(tm) and SQL Server AnalysisServices(tm) the current toolset is certified for use with solutions from SAP and IBM as well.About Performance CanvasPerformance 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 andeverything in between in a highly customizable package it is certainly at the top of the class and then wehavent 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
  3. 3. Page |3Advanced administration and development - guidelines and referenceContents 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........................................................................................................................ 22On 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 Dos and Don’ts while installing the Kerberos setup .......................................................................... 29 Troubleshooting .................................................................................................................................. 30On development ......................................................................................................................................... 31 On direct API usage ................................................................................................................................. 31On web services .......................................................................................................................................... 31 On ConfigurationService ......................................................................................................................... 31 On methods ........................................................................................................................................ 32 Task: Retrieving an existing object...................................................................................................... 39 Task: Finding a list of objects .............................................................................................................. 40 (c) Decision Support Panel AB 2009
  4. 4. Page |4Advanced administration and development - guidelines and reference 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 ....................................................................................................................................... 69Appendix A .................................................................................................................................................. 70 Configuring Performance Canvas using zenith.properties ..................................................................... 70Appendix E .................................................................................................................................................. 74 ConfigurationService WSDL .................................................................................................................... 74Appendix F .................................................................................................................................................. 89 RenderingService WSDL .......................................................................................................................... 89Appendix G .................................................................................................................................................. 93 XMLAService WSDL ................................................................................................................................. 93Index.......................................................................................................................................................... 106 (c) Decision Support Panel AB 2009
  5. 5. Page |5Advanced administration and development - guidelines and referenceWho is this document forThis document assumes you have a working knowledge of a lot of things. However, even someonewithout that knowledge should be able to glean bits of relevant information from the parts they areinterested in. For example, you do not need to be an MDX wizard to configure the caches, nor do youneed to understand the intricacies of networking to able to fathom how to use web services to render asimple chart.However, if you expect to understand everything covered in here you should have a passable knowledgeabout  HTTP1.1  SSL  Windows Security  Active Directory  WS-SOAP  MDX  Analysis Services  IIS (c) Decision Support Panel AB 2009
  6. 6. Page |6Advanced administration and development - guidelines and referenceIntroductionSo you managed to get past the part about who you are. This either means you will understandeverything in this document or that you know exactly what you are looking for. Either way, it is oursincere hope that the information found in these chapters will help you get the most out of yourPerformance 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 aTomcat instance. The fact that it happens to be Tomcat is purely circumstantial. It could just as easilyhave 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 servletsto the web client. These servlets however are not of much use to someone else as they use a veryspecific RPC model specific to GWT (Google Web Toolkit) which is used to develop the frontend/client(s).The same services do however have a different access point which is web services. If you have a look atthe chapter on web services you will find all the information you need to write a complete clientsolution on top of the capabilities in PC. You could potentially - if you were so inclined, although it is thisauthors sincere hope that you arent - make your own PC web client. Please dont. There are muchmore interesting applications for this technology. (c) Decision Support Panel AB 2009
  7. 7. Page |7Advanced administration and development - guidelines and referenceOn administrationAdministration in PC generally means opening /app/admin and setting up data sources, adding users toroles and approving objects. There are however a number of things that can be done but require you toedit text files. Dont worry, its not very dangerous. OK, Maybe a little.As in any large server application there are configuration options that really shouldnt be exposed to thelight of day as they have the potential for serious repercussions. Some of these are related to the datasources (like the caching options) and can, for a large scale installation, easily turn your data layer into avery slow mowing slug indeed. Others are related to things like protocol level security (SSL) or advanceddeployment (see On scaling out). We will try to go through these different subjects - and some of thepurely 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 pathsare relative to the installation directory (hence /bin means C:Program FilesPerformance Canvasbin ifyou installed in the default location).Location: Installation directoryFile zenith.propertiesFormat Key value pairs in key=value formatDescription 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, its 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 optionsLocation: /binFile service.propertiesFormat Key value pairs in key=value formatDescription 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 (c) Decision Support Panel AB 2009
  8. 8. Page |8Advanced administration and development - guidelines and reference 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 optionsLocation: /store/settingsFile app.propertiesFormat Key value pairs in key=value formatDescription Used to guide the automated page generation. Dont 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 doesnt work. But generally. Dont touch. Refer to Appendix A, section 3 for a complete description of all the things you shouldnt be changing.File colors.xmlFormat XMLDescription 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 dont like can be hidden. Look in the section just mentioned.File cubes.xmlFormat XMLDescription 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 dont 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 (c) Decision Support Panel AB 2009
  9. 9. Page |9Advanced administration and development - guidelines and referenceFormat Configuration file specificDescription 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 1File login.confFormat Configuration file specificDescription Internal. Do NOT change.File Userlocales.propertiesFormat Key value pairs in key=value formatDescription Placeholder file for planned functionalityFile Viewport.propertiesFormat Key value pairs in key=value formatDescription 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 shouldnt 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.propertiesFormat Key value pairs in key = value formatDescription The main language file. If there are messages in the application that you want to change this is where to do that. This file isnt 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 (c) Decision Support Panel AB 2009
  10. 10. P a g e | 10Advanced administration and development - guidelines and reference 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 dont 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.propertiesFormat Key value pairs in key = value formatDescription 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/propertiesFile analysis.pFormat DSP customDescription Property file describing an Analysis. Refer to Appendix D for complete information.File annotation.p (c) Decision Support Panel AB 2009
  11. 11. P a g e | 11Advanced administration and development - guidelines and referenceFormat DSP customDescription Property file describing an Annotation. Refer to Appendix D for complete information.File canvas.pFormat DSP customDescription Property file describing a Canvas. Refer to Appendix D for complete information.File chart.pFormat DSP customDescription Property file describing a Chart. Refer to Appendix D for complete information.File classification.pFormat DSP customDescription Property file describing a Classification. Refer to Appendix D for complete information.File filter.pFormat DSP customDescription Property file describing a Filter. Refer to Appendix D for complete information.File gem.pFormat DSP customDescription Property file describing a Gem. Refer to Appendix D for complete information.File kpi.pFormat DSP custom (c) Decision Support Panel AB 2009
  12. 12. P a g e | 12Advanced administration and development - guidelines and referenceDescription Property file describing a KPI. (placeholder for future functionality) Refer to Appendix D for complete information.File measure.pFormat DSP customDescription Property file describing a Measure. (A virtual object that looks as if it existed in the cube to the end user) Refer to Appendix D for complete information.File report.pFormat DSP customDescription Property file describing a Report. Refer to Appendix D for complete information.File role.pFormat DSP customDescription Property file describing a Role. Refer to Appendix D for complete information.File slicer.pFormat DSP customDescription Property file describing a Slicer. Refer to Appendix D for complete information.File table.pFormat DSP customDescription Property file describing a Table. Refer to Appendix D for complete information.File tag.p (c) Decision Support Panel AB 2009
  13. 13. P a g e | 13Advanced administration and development - guidelines and referenceFormat DSP customDescription Property file describing a Tag. Refer to Appendix D for complete information.File viewpoint.pFormat DSP customDescription Property file describing a Viewpoint. Refer to Appendix D for complete information. (c) Decision Support Panel AB 2009
  14. 14. P a g e | 14Advanced administration and development - guidelines and referenceOn cachesThe various caches are at the core of what makes PC such a fast and responsive solution. It also servesas protection to ensure that cubes in the data layer arent unnecessarily accessed. Even though they, forthe most part, are highly efficient at answering queries, in many cases it makes a lot of sense to ensurethat they get as little traffic as possible.There are multiple levels and forms of caching so lets go through them one by one:The Metadata cacheA 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 specificKPI. It may be to be able to do all sorts of other more or less interesting things that need doing while weare transforming queries. To be able to do this, without drowning the cube in metadata queries, all thisdata needs to be cached. It also needs to be cached on a per-user (from the cubes point of view) basis.That means that for every account accessing the cube there needs to be a cache. One quickly realizesthat this means that Anonymous, Basic and NTLM are superior here in terms of performance from acube point of view and this is correct. However they do have shortcomings in terms of the granularity ofsecurity that they provide. And it is of course possible to create n roles for n users using accountmapping so that n olap accounts are also created. Which basically creates the same kind of scenario as adelegatable credentials (i.e. Kerberos) one. This is however unlikely and beyond the scope of thediscussion here. The point is that as much information as possible is cached on retrieval to ensure thatwe dont ask the same question twice for a particular user unless the cube has been processed in whichcase all caches are instantly invalidated.This cache is largely uninteresting from a performance point of view. There are however someimplications that need to be considered. Most, if not all, of the data contained therein is String basedand to reduce the amount of memory used we use intern() to load and store these String instances inthe 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 arelative term here. But if you are looking at caching tens of thousands of members then consider thatyou can cost each member as 6KB approximately. Basically for each thousand you need 6 MB set up, thedefault 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 thatyour users dont suddenly face error messages due to out of memory conditions.Configuration optionsThere is discussion above about how to setup -XX:PermSize, this is really the only configuration optionthat we allow - so far. There has been discussions about allowing the administrator to restrict cachingfor certain hierarchies to reduce the memory footprint (this would then be a trade off against cubemetadata queries) but nothing conclusively has come out of that yet. If you feel that this would bevaluable functionality for you then please get in touch with us and let us know and we will consider it.The Query cache (c) Decision Support Panel AB 2009
  15. 15. P a g e | 15Advanced administration and development - guidelines and referenceAll queries create a result set in the form of a TableModel. This is cached and along with it we also cachethe renderings made with that particular result set. Note that these are user specific (again, talkingabout cube users rather than PC users) so there is no risk of information leakage. This cache is importantin various ways. If you are running heavy queries then it becomes very important as it offloads the cubeby ensuring that groups of users share result sets between them. Note that the cache is access orderedand when booting out anything over dsp.cache.maxqueries it will remove the LEAST used result set. Youprobably understand that if you can deal with the memory overhead of the result set caching you aregoing to over time ensure that the most frequent queries stay cached and highly responsive - just theway you want it. Intrepid explorers that dive into the more advanced features of PC and do their ownanalysis will find that their queries take slightly longer but at the same time their performance willimprove dramatically over a scenario where no caching is done at all since they are basically gettingaccess to a lot more of the processing capacity of the data layer than they would normally have.Configuration optionsdsp.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 aconstrained memory footprint. If you run the service with dsp.log=3 (zenith.properties) you will be ableto 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 becomesimportant. If it changes on a daily basis you may want to set this to some value that reflects that. Notthat if you have more than one cube you can set individual expirations by usingdsp.cache.expire.<cubename> (i.e dsp.cache.expire.DspSalesDemo=10000000000). Dont use shortvalues. Its pointless and its better in that case to set the dsp.cache.maxqueries property to 0 or somevery low value (if you think that would be appropriate) to reduce the amount of caching going on forresultsets.Note - values are given in millisecondsClient side cachingFor the sake of completeness one should also note that there are client side caches as well. Two areespecially noteworthy, the render cache and the entity cache. Basically these are - in a way - client sideversions of the server side caches. The render cache is per page component and ensures that we dontrequest renderings that we already have. This is only available in /app/client as chart settings areconstantly 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) arestored 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 areinvalidated when a new Calculated member is created and stored for reuse. This ensures that thismember is reusable on the next gem design/drag and drop excursion. (c) Decision Support Panel AB 2009
  16. 16. P a g e | 16Advanced administration and development - guidelines and referenceThere are some minor differences in how different browser retrieve information as well which affect theoverall traffic profile of the PC server. If you are using IE clients only you will note that there is lessinformation sent "up front" to people using the /app/designer application. This is because InternetExplorer, though surely a commendable piece of technology in other ways, is perhaps a tiny bit deficientin terms of JavaScript performance compared to the market leaders in that space (i.e. everyone else).This wont have a huge effect but its worth knowing that the load on the network becomes differentlydistributed when people are using IE. Enough said.Configuration optionsNone.We are considering adding some persistance handling a la HTML5 but it is very dependent on customerfeedback. If people have primarily static cubes (i.e. cubes processed weekly or less) then this might be agood idea to give even better performance. But it remains to be seen.Related subjectsSometimes people can (inadvertently) create trivial queries that result in huge datasets, whencrossjoining two attribute hierarchies together its easy to end up datasets that can easily eat up everysingle scrap of processing capability that the browser has to offer. This is not strictly related to cachingbut it is tangential so we cover it here. To get around this issue you can define a maximum resultset sizein number of cells.Configuration optionsdsp.memory.resultsetmax (default: 50 000)This is the number of cells that a TableModel can contain. The process will stop once the dimensions ofthe table exceeds this number and the end user will get a message informing him or her that the resultset is too large to be handled (c) Decision Support Panel AB 2009
  17. 17. P a g e | 17Advanced administration and development - guidelines and referenceOn query based securityPC introduces the capacity to constrain result sets in situations where your security setup doesntinclude Kerberos. There are a multitude of reasons why this might be the case. Kerberos is notoriouslycomplex and some organizations simply are not willing to take the step. Another reason might be thatthis might not be an internal solution. For an extranet, a mobile solution or something else wheredelegated credentials simply arent applicable query based security becomes a very powerful tool. Itshould also be noted that some users claim that delegated credentials and granular dimension basedsecurity is a very computationally expensive proposition. Decision Support Panel has no opinion in thismatter but simply allows people of differing opinions to setup security as best fits their intendedaudience and infrastructure.So. There are two ways of doing query based security. One is by narrowing only specific queries. This canbe 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 ROWSFROM [DspSalesDemo]Now, if we happened to have a hierarchy in the cube where we have our login names as user defined propertieswe can in fact do:SELECT{[Geography].[Geography].[Country].MEMBERS} ON COLUMNS,{[Measures].[Actual]} ON ROWSFROM [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, lets say Alan logs on to PC and opens his favorite canvas with thegem using this query on it. The query will then be modified to readSELECT{[Geography].[Geography].[Country].MEMBERS} ON COLUMNS,{[Measures].[Actual]} ON ROWSFROM [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 ofthe 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 thesequeries through a user based hierarchy you can do this automatically for all queries. (c) Decision Support Panel AB 2009
  18. 18. P a g e | 18Advanced administration and development - guidelines and referenceIn zenith.properties add two lines.dsp.filter.user=truedsp.filter.user.definition=[User].[User].[$PC09_USER]Note: if you have a hierarchy which stores the login name in a property then you can usedsp.filter.user.definition=FILTER({[User].[User].MEMBERS},[User].[User].CURRENTMEMBER.PROPERTIES("Login") = "$PC09_USER")This will modify every single query going through the system (no exceptions) and will provide a prettydecent level of security - although it wont protect your data if someone for example downloads aMicrosoft 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 allowyou to ensure that the contents of the individual slicers are only the members that a specific usershould be allowed to see. (c) Decision Support Panel AB 2009
  19. 19. P a g e | 19Advanced administration and development - guidelines and referenceOn secure socket layer (SSL) and its implicationsIMPORTANT NOTE: In order to use SSL you NEED to run the 32-bit JRE. If your copy of PC is installed ona 64-bit machine you have to download the 32-bit JRE from Oracle (for Windows x86) and replace thecontents of the <INSTALL_DIR>/runtime folder with the contents of the JRE. The reason is that therequired 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 ofan installation it does come with a cost. And that if you are using SSL towards PC you really shouldconsider using SSL between the Performance Canvas server and the IIS instance. Note: if you are puttingup a outwardly accessible instance, for example on your extranet or even as part of your public site thenSSL may in certain cases be preferable.However, the cost is pretty straight forward, SSL costs CPU cycles and those CPU cycles increase as thenumber of users increase. There are tons of resources on the internet on how to figure out what kind ofhardware to throw at the problem but it requires some understanding of the traffic profile and theusage 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 =truedsp.security.ssl.protocol=TLSdsp.security.ssl.keystoretype=JKSdsp.security.ssl.keystorepass=ChangeThisPassworddsp.security.ssl.keyalias=performancecanvasNow. 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 letclients know that the website is secure. Heres how you create a CSR.Start a command line window and navigate to the installation directory where Performance Canvasresides. Then run the following commandruntimebinkeytool -genkey -alias performancecanvas -keyalg RSAThis will generate a key and you will be prompted to supply a password. This is the password you willsupply 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 theinformation that clients accessing the server will see in the certificate so be sure to fill it outappropriately.Finally you will be asked to give a password for the key itself (not the keystore), you HAVE TO use thesame password as you did before. Just pressing the ENTER key will ensure that this happensautomatically. (c) Decision Support Panel AB 2009
  20. 20. P a g e | 20Advanced administration and development - guidelines and referenceIn order to get a true Certificate from a Certificate Authority (like Thawthe or Verisign), you should nowcreate what is called a CSR. This Certificate Signing Request is used by the CA to create the Certificatethat will later identify your server as secure to the end users. Heres how you do that.Open a command line window and again navigate to the installation directory of performance canvas.Create the CSR by runningruntimebinkeytool - certreg -keyalg RSA -alias performancecanvas -file certreq.csr-keystore .keystoreThis will create a file named certreq.csr that you send to the Certificate Authority of your choice, theyhave ample documentation on their websites on how to make certificates. Within a short time frameyou will get a Certificate back. This has to be imported into your keystore. However, you have to start byimported the Root or Chain Certificate first.Go to the Certificate Authority you got your certificate from and download their Chain or RootCertificate. Consult their documentation if you cant find it. Once you have downloaded that, start acommand line window and navigate to the installation directory of Performance Canvas and import itwith the following commandruntimebinkeytool -import -alias root -keystore .keystore -trustcacerts -file <thefilename of the root certificate>Once that is done you can proceed with importing your own Certificate by runningruntimebinkeytool -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 installationdirectory with the configuration options described above you will be all set and a quick restart will makeyour Performance Canvas instance highly secure. (Note: if you want to use an internal certificate thenyou have to use PKCS11 or PKCS12, refer to the OpenSSL documentation on how to turn a Microsoft KeyManager certificate into a valid SSL certificate. This will require changing the keystoretype value as well.) (c) Decision Support Panel AB 2009
  21. 21. P a g e | 21Advanced administration and development - guidelines and referenceOn loose clustersThere are situations where traffic warrants the use of several machines (or perhaps you simply want toensure better availability/response times). Moving to enterprise class licenses with support fordistributed caches is expensive and a better solution on the way there may be to consider doing looseclustering. This centers around the fact that instances can share a single store location. This may be on anetworked disc somewhere where the /store folder is located. It contains all the definition files and aslong as you expect most of the traffic to be reads this really shouldnt be problematic at all. But it is yournetwork. Making predictions on the effects on it would be presumptuous. If you have good bandwidthand hardware then by all means try it - it is a very viable solution. If you have a shaky network with loadsof timeouts and congestion then perhaps this isnt for you.Basically the simplest scenario is that you have nodes A through Z and they all share a single storefolder. Their core configuration is unique, that means that they can be running on different ports ifthats what you want. However in the vast majority of the cases you will be running this with some formof 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 havedsp.store.path=<path to the store folder>in their zenith.properties file. Thats it. Lets say you have your networked disk onServer01D$rscstore then simply adddsp.store.path=Server01D$rscstoreto the zenith.properties files and you are all set. All your instances will now be running using the settingsand object definitions there. They will all have their own metadata caches however (be aware of this, itwill increase metadata traffic towards your cubes so you will have to keep an eye out for 503 errors inthe logs, signifying that you have contention issues in the IIS and need to increase the number ofworkers/threads in order to keep up with demand). (c) Decision Support Panel AB 2009
  22. 22. P a g e | 22Advanced administration and development - guidelines and referenceOn locales and languagesWe understand the need for supporting multiple languages and Performance Canvas is built from theground up to support multiple locales both on the client and the server side. However, for performancepurposes you use a dedicated server per locale. This is on order to be able to effectively utilize thenaming cache, a cross-locale server would not be efficient as the number of values needing cachingwould 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 onlything you have to do is set the server locale accordingly. You do this either by using the administrativeconsole 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 anexample. The default configuration isdsp.locale=enThis means that english is used. Not en_US (which is US English) or en_UK (which is UK english) but enwhich is a common english translation suitable for all english speaking regions but which does not takeinto account locale specific spelling. If you for example want to use french instead there are severaltypes of french.dsp.locale=frdsp.locale=fr_CAdsp.locale=fr_FRare 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 andthese are the files that should be used as the basis for translation should you opt to implement a newlanguage for yourself or your customers) (c) Decision Support Panel AB 2009
  23. 23. P a g e | 23Advanced administration and development - guidelines and referenceOn KerberosKerberos is a notoriously complex protocol. It is highly secure and solves a lot of the typical issues with amodern heterogenous IT environment but at the same time it can be problematic to set up and evenmore problematic to troubleshoot. This document will explain how to setup Kerberos to work withPerformance Canvas. It is assumed that the reader has a basic knowledge of Active Directoryadministration and knows one or two things about configuring a DNS as well. But if you don’t we havetried to give as much information as possible to ensure that you are successful.IMPORTANTIt is easy to assume that the hostname and username in the description below are different. They arenot. You will want to setup a user and a host with the EXACT same name. So if you create a user namedpc07 then the host will have to be called pc07 as well. This is easily overlooked and a common source oferror.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 accountThe first thing you need to do is to create a new account that will act as the service (not the sameaccount as running the Performance Canvas service described above). In this particular example we willcall this user pc07krb5. Note that this name will also be the server name used to access the PerformanceCanvas so choose something that is a good and descriptive hostname if people are going to be accessingit directly in their browsers. Note that Kerberos as a protocol is notoriously case sensitive and even ifmuch of that is a non issue in a pure Microsoft environment it is considered best practice to stick withlower case names.In this example we are creating a new user in the Microsoft Active Directory™ with username pc07krb5and the password pc07k5#123. Note that the username and password can be anything you want themto be. (c) Decision Support Panel AB 2009
  24. 24. P a g e | 24Advanced administration and development - guidelines and reference(Figure 1: setting up the username)(Figure 2: setting up the password for the user – note the “password never expires” setting) (c) Decision Support Panel AB 2009
  25. 25. P a g e | 25Advanced administration and development - guidelines and reference(Figure 3: Finalizing the user creation, just verify your settings and click finish)Step 2: Ensuring that the account can handle delegationNow you want to make sure that the account you created is trusted to do delegation. Delegation is theKerberos mechanism that allows a server to impersonate a user without having access to his or hersactual credentials, instead it receives a forwardable ticket from the Kerberos server. To do this you needto locate the newly created account under Users in your Active Directory. Now right click on it to openthe properties window. Select the tab named “Account” and make sure that the checkbox marked“Account is trusted for delegation” is checked. (c) Decision Support Panel AB 2009
  26. 26. P a g e | 26Advanced administration and development - guidelines and reference(Figure 4: setting the delegation flag on the user account is done on this tab in the user accountproperties)Note that certain Active Directory setups will NOT have this checkbox, in this case perform steps 3 and 4and go back. Now there should be a tab called Delegation showing. This will include a radio button thatallows you enable the same option.Step 3: Adding a host nameKerberos uses what is known as SPN (Service Principal Names) as a way to locate services. In order forthat to work there needs to be an entry in the DNS called an A record that the Kerberos server canfind. Open your DNS management console (logged on to the domain controller server you can find thisunder Administrative tools). Locate the domain you want. Note that if you are working on the domainDOMAIN the zone you are looking for is called domain.local from a DNS perspective. Locate that underForward Lookup Zones, right click the folder and add a new A record. To be able to do this you will needthe IP address of the machine that Performance Canvas will be running on. If you don’t have it you canlocate the NETBIOS name in the DNS. If the machine is for example called server4 you can just locatethat name in the list. Neither of the checkboxes need to be checked for Kerberos to work. Note that the (c) Decision Support Panel AB 2009
  27. 27. P a g e | 27Advanced administration and development - guidelines and referencehostname 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 keytabA keytab file is a shared secret that allows the service to communicate with the Kerberos service as aservice. This is the most complex part of the setup. You have to open a DOS window and navigate tosome directory where you can create files. First write: “ktpass” (without the quotes) on the commandline and press enter. If you get an error saying that the file can’t be found then you have to installktpass. 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 andstarting it again.Now writektpass -princ “HTTP/pc07krb5.dspDevDomain.local@DSPDEVDOMAIN.LOCAL” -mapUser pc07krb5-pass pc07k5#123 -crypto RC4-HMAC-NT -out pc07.keytabThis will generate a file called pc07.keytab. Note that you need to replace the username, password anddomain parts with your particular information. If you are in the domain MYDOMAIN and just create ausername called pc07 with the password pwd123 then you would write (c) Decision Support Panel AB 2009
  28. 28. P a g e | 28Advanced administration and development - guidelines and referencektpass –princ “HTTP/pc07.mydomain.local@MYDOMAIN.LOCAL” –mapUser pc07 –pass pwd123 –crypto RC4-HMAC-NT –out pc07.keytabNot 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 useDES-CBC-MD5 instead. This also means you have to change the values in the zenith.properties file(found in the Performance Canvas installation directory) fromdsp.security.krb5.conf.default_tgs_enctypes=rc4-hmacdsp.security.krb5.conf.default_tkt_enctypes= rc4-hmactodsp.security.krb5.conf.default_tgs_enctypes=des-cbc-md5 rc4-hmacdsp.security.krb5.conf.default_tkt_enctypes=des-cbc-md5 rc4-hmacThis will enable the use of des-cbc-md5 as an encryption type for Performance Canvas.To verify the SPN mapping you can run the commandsetspn –L mydomainpc07Or in our examplesetspn –L dspDevDomainpc07krb5This will list the associated SPN:s so you can verify that everything is correct. If there is a problem youcan delete the SPN by writingsetspn –D HTTP/pc07.mydomain.local@MYDOMAIN.LOCAL mydomainpc07And then you can do the ktpass keytab generation over again. (c) Decision Support Panel AB 2009
  29. 29. P a g e | 29Advanced administration and development - guidelines and referenceStep 5: Installing the keytab fileNow that you have a keytab file you have to move it so that Performance Canvas can find it. The bestway to put it is in the Performance Canvas installation directory. Copy the file and transfer it there. Nowyou have to make sure to tell Performance Canvas where it is. If it is running then stop the service. Nowopen the zenith.properties file that you can find in the installation directory. Locate the property calleddsp.security.krb5.conf.default_keytab_nameNow you want to give the complete path of the keytab file, like thisdsp.security.krb5.conf.default_keytab_name=c:program filespc07pc07.keytabOnce that is done you can start the Performance Canvas service again. Congratulations, the hard part isnow 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 URLOnce you have selected Windows Integrated Security and clicked save you can restart the service andtry it. In this example the URL will be http://pc07krb5Make sure you do not use a browser on the same machine as Performance Canvas is running on. Inmany situations Active Directory forces that browser to use NTLM to access local machines and this willnot work as the Performance Canvas server is now in Kerberos only mode.Dos and Don’ts while installing the Kerberos setupDO• 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 – PCmydomainPC (c) Decision Support Panel AB 2009
  30. 30. P a g e | 30Advanced administration and development - guidelines and referenceDON’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 yourzenith.properties file (see Step 5 above). If you don’t then add it to the file likethis dsp.security.useNativeGssApi=false. If the value is true then change it to false. Using truewill make it fail.• Make sure that the host is trusted by the browser, if the browser is showing that the host is part of theinternet zone then you have to add the hostname to trusted sites. You can find the icon in the bottombar of your Internet Explorer. If it shows an icon looking like a very small earth then you are in the wrongzone and the browser will attempt to use NTLM. Doubleclick the icon and add the host to trusted sites inyour local intranet zone• Check that the host you are accessing has the exact same name as the user you created. This isextremely 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 withan 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 whichis interfering with the HTTP on the host machine. Use setspn –L MYDOMAINusername to check thatyou 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 youare using is just the username, don’t use MYDOMAINusername. Just username. The domain name isspecified elsewhere (c) Decision Support Panel AB 2009
  31. 31. P a g e | 31Advanced administration and development - guidelines and referenceOn developmentWe have worked pretty hard on making sure that PC is more than just a design tool. It is a prettypowerful development tool as well, regardless of whether you want to design mash ups, complexdashboards or pretty much whatever you want from the web client side or if you want to do deepintegration into existing enterprise applications, delivering analytics functionality to places where peopleactually see it in context. In this section we will try to describe how to go about these things bydescribing a number of well defined basic tasks that are common and that would form the basis of asolution. This will make your life easier and coupled with the information in appendices E through G youshould find enough (hopefully) to let you go about your work without having to scratch your head toomuch.We know as well as you do that good documentation is essential to a developer and we have tried toput everything as clearly as possible but if there is something you are still wondering about then donthesitate 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 andwill be sort of a bastard child of Java and C# since those two languages are the most commonly used forbuilding enterprise applications today. If you are working in a different environment completely thenhopefully at least you will be able to glean sufficient information from the examples that you can stillunderstand what should be going on and translate that to your own work situation. Mileages may vary.As usual.On direct API usageThis 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 breachof the EULA and all sorts of bad things will happen. Fire. Brimstone. Wrath of least favorite deity. Thatkind of thing. So dont. We know its cool and neat and all. But be a cool person. License it. Then you willget the appropriate documentation. The web services are just as useful. Promise.On web servicesOn ConfigurationServiceFirst of all. You will find the wsdl by accessinghttp://yourserver:yourport/services/ConfigurationService?wsdlOr you can just look in Appendix E if you have the stomach for reading WSDL files with the naked eye. (c) Decision Support Panel AB 2009
  32. 32. P a g e | 32Advanced administration and development - guidelines and referenceOn methodsBelow the methods in ConfigurationService are described along with parameters and return types. Formore in depth information, read the task sections to find out how they are used in various scenarios.addCubeaddCube(string url, string sqlServerName, string olapDBName, string cubeName, stringcubeDisplayname)PARAMETER DESCRIPTIONurl 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.dllsqlServerName The SQL Server nameolapDBName The name of the OLAP database (or Catalog) where the cube residescubeName The Name of the cubecubeDisplayName The displayed name of the cube, becomes highly interesting if you have autogenerated cube namesThe method returns a boolean indicating whether the cube was added or not.appendCubesappendCube(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 allof the arrays should have the same length. The parameters are exactly the same as in addCube above.PARAMETER DESCRIPTIONurl 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.dllsqlServerName The SQL Server name (c) Decision Support Panel AB 2009
  33. 33. P a g e | 33Advanced administration and development - guidelines and referenceolapDBName The name of the OLAP database (or Catalog) where the cube residescubeName The Name of the cubecubeDisplayName The displayed name of the cube, becomes highly interesting if you have autogenerated cube namesThe method returns a boolean indicating whether the cube was added or not.constructCanvasThis method requires a bit of explanation perhaps, it will automatically construct a canvas given a set ofslicers and a set of gems.constructCanvas(string canvasSettings, string[] slicers, string[] gems)PARAMETER DESCRIPTIONcanvasSettings The base settings for the new canvas, is it mobile or not, whats the current status and so onslicers An array containing the slicer uids for inclusion in the canvas filter blockgems An array containing the gem uids for gems that should be displayed on the canvasThe method returns a string containing the UID of the newly constructed canvas.deleteCanvasdeleteCanvas(string canvasUid, boolean deepDelete)PARAMETER DESCRIPTIONcanvasUid The UID of the canvas you want to deletedeepDelete 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. (c) Decision Support Panel AB 2009
  34. 34. P a g e | 34Advanced administration and development - guidelines and referenceThe method returns a boolean signifying whether the delete was successful or not.exportCanvasexportCanvas(string canvasUid)PARAMETER DESCRIPTIONcanvasUid The Uid of the Canvas to be exportedThe 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.flushCacheflushCache()PARAMETER DESCRIPTIONThe method has a void return type. The only thing it does is attempts to flush the cache. Note that this issynchronous so it may take a while for the method to return.getConfigurationsThis method retrieves a list of entities that match the supplied filters, if no filters are supplied then allobjects are returned. Filters are supplied in standard NVP format (i.e <name>=<value> - so, if youwanted 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)PARAMETER DESCRIPTIONtype The object type you want to look for. Valid values are for example - canvas - gem - chart - table (c) Decision Support Panel AB 2009
  35. 35. P a g e | 35Advanced administration and development - guidelines and reference - 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 typeThe method returns a string array containing the objects that matched the querygetUniqueConfigurationThis 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 thismethod likes thisgetUniqueConfiguration("canvas","ping");which will give you an empty string as a return value.getUniqueConfiguration(string type, string uid)PARAMETER DESCRIPTIONType 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. (c) Decision Support Panel AB 2009
  36. 36. P a g e | 36Advanced administration and development - guidelines and referenceThe method returns a string containing the configuration represented as key-value pairs.importCanvasThis method is the import version of exportCanvas. It takes an array of object definitions and storesthem locally.importCanvas(string[] components)PARAMETER DESCRIPTIONcomponents An array containing all the objects used on the canvas as well as the canvas itself. Each object has its 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.saveConfigurationThis method saves the settings for a requested object type. Note that we dont do any type checking orvalidation here so use all the save methods with appropriate caresaveConfiguration(string type, string settings)PARAMETER DESCRIPTIONtype 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 (c) Decision Support Panel AB 2009
  37. 37. P a g e | 37Advanced administration and development - guidelines and referenceThe method has a void return typesaveConfigurationAsNewThis method saves the settings for a requested object type as a guaranteed new object. This can be usedto clone objects or save minor variations in a an easy way. Note that we dont do any type checking orvalidation here so use all the save methods with appropriate caresaveConfiguration(string type, string settings)PARAMETER DESCRIPTIONtype 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 objectThe method returns a string containing the UID of the newly created objectsimpleConstructCanvasThis method is an even simpler front for constructCanvas(). In this method you simply supply a list ofuids for the objects you want to add, without keeping track of the object types.simpleConstructCanvas(string canvasSettings, string[] uids)PARAMETER DESCRIPTIONcanvasSettings The base settings for the canvas you want to createuids The uids for all the objects you want to use on the canvas, note (c) Decision Support Panel AB 2009
  38. 38. P a g e | 38Advanced administration and development - guidelines and reference that anything which doesnt point to a gem or a slicer will be discarded.The method returns a string containing the uid of the newly constructed canvas. (c) Decision Support Panel AB 2009
  39. 39. P a g e | 39Advanced administration and development - guidelines and referenceTask: Retrieving an existing objectRetrieving an existing object requires you to have two distinct pieces of information. One of them is theobject type (is it a canvas, a gem et cetera), the other is the unique identifier. Now, the uniqueness ofthese identifiers is local. They are not guaranteed to be globally unique. However, if a UID is generatedthat matches an existing one in the system it WILL be discarded so there is no risk of accidentallyoverwriting existing information.Once you have this information you use the web services to retrieve the object. The method you wantis:getUniqueConfiguration(type, uid)This method returns a string containing the properties of the object as key value pairs in the usual PCfashion. Lets say we retrieve a tag with the uid 1234.pseudo code belowstring 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 valuecan contain = signs propertyCollection.put(keyValue[0],keyValue[1]);}Now you can retrieve and edit the properties before using or saving the object. (c) Decision Support Panel AB 2009
  40. 40. P a g e | 40Advanced administration and development - guidelines and referenceTask: Finding a list of objectsIts not uncommon to have a need to retrieve a list of objects from the server. In the simplest case youwant to discover all the canvases (for example) on a specific PC server. Use the methodgetConfigurations(string type, string[] filters)In this example task we wont be using filters. You can pass null for this argument. Note that this methodreturns an array of strings, meaning that each object will be contained in its own string representationof 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 youhave access to) you dogetConfigurations("canvas", null);And thats it. (Note: depending on your WS framework this can be more or less work and the way toaccomplish this can be quite different but this will give you the general idea at least. Dont be afraid toplay around with this stuff. If you dont want to use the production server for development then eitherdownload a trial version or use the development license that should come with all licenses of non-embedded PC. (c) Decision Support Panel AB 2009
  41. 41. P a g e | 41Advanced administration and development - guidelines and referenceTask: Finding a list of objects that match a certain filterNow that you know how to retrieve a list of objects its time to start filtering your results. A filter isrepresented as a key value pair. Lets say you want to find all gems that are in a PUBLISHED state. Theproperty name is gem.basic.status and the appropriate value is PUBLISHED (if you want to find out moreabout properties, please have a look at Appendix C where all of the object types are described in mindnumbing detail).You populate your string array used for filters with one string containingstring[] 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 offilters obviously, here is an example which retrieves all published gems that are charts and use theDspDemoSales cube.string[] filters = new string[]{"gem.basic.status=PUBLISHED","gem.basic.viewtype=CHART","gem.basic.datasource=DspDemoSales"};string[] result = getConfigurations("gem",filters); (c) Decision Support Panel AB 2009
  42. 42. P a g e | 42Advanced administration and development - guidelines and referenceTask: Creating an objectCreating a new object requires you to first fetch the settings, second modify them and third sending thewhole thing back to the server. In this example we will construct something simple without relationshipsto other things, normally - for example in the case of a gem - object creation will require keeping track ofmultiple 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 PCfashion. This time however we will send in null as the uid argument.pseudo code belowstring 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 valuecan 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 tosave 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 thisvalue.a=avalue.b=bvalue.c=cpseudo code belowstring 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 namestring tagData = getUniqueConfiguration("tag",uid); //this will fetch us the objectwe just createdtagData = tagData.replace("name","newName");saveConfiguration("tag",tagData);//note what we just did is not a recommended way of doing things, just an example (c) Decision Support Panel AB 2009
  43. 43. P a g e | 43Advanced administration and development - guidelines and referenceTask: Exporting a canvasSometimes you will end up in a situation where you have a set of canvases on one PC instance that youwould like to deploy on another one. Finding it in the store and resolving all the relationships may beextremely 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 filteredsearch capabilities (see "Finding a list of objects that match a certain filter").pseudo code belowstring uid = "1234";string[] objects = exportCanvas(uid);Now that you have your canvas represented as an array of strings you can import that into anotherPerformance Canvas server instance. (c) Decision Support Panel AB 2009
  44. 44. P a g e | 44Advanced administration and development - guidelines and referenceTask: Importing a canvasSo now you have successfully exported a canvas from a Performance Canvas Server and you want toinstall 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 havedone that the canvas and its parts are available for the users on the import server. Well done. (c) Decision Support Panel AB 2009
  45. 45. P a g e | 45Advanced administration and development - guidelines and referenceOn RenderingServiceFirst of all. You will find the wsdl by accessinghttp://yourserver:yourport/services/RenderingService?wsdlOr you can just look in Appendix E if you have the stomach for reading WSDL files with the naked eye.On methodsHere are all the methods of the RenderingService described with parameters and return types. For moreinformation on how to use them, check out the task section following the method definitions.getChartgetChart(string mdxQuery, string settings, string format)PARAMETER DESCRIPTIONmdxQuery 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 thrownsettings 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 - pptThe method returns a string containing a a partial url, using the ContentService you can instantlydownload the file which has already been generated.getChartTypesgetChartTypes() (c) Decision Support Panel AB 2009
  46. 46. P a g e | 46Advanced administration and development - guidelines and referencePARAMETER DESCRIPTIONNoneThe method returns an array of strings containing all the available chart types on this PerformanceCanvas instancegetColorSchemesgetColorSchemes()PARAMETER DESCRIPTIONNoneThe method returns an array of strings containing all the available color schemes on this PerformanceCanvas ServergetTablegetTable(string mdxQuery, string settings, string format)PARAMETER DESCRIPTIONmdxQuery A valid MDX Query pointing to a cube which is mapped and initialized in this Performance Canvas serversettings Valid settings for a Performance Canvas table. These can be retrieved and modified using the ConfigurationService. Note - this doesnt have to point to an exisiting object.format A string describing what format you want the table in, valid values are: - html - xls - pdf (c) Decision Support Panel AB 2009
  47. 47. P a g e | 47Advanced administration and development - guidelines and reference - image - scaledimageThe method returns a string containing a a partial url, using the ContentService you can instantlydownload the file which has already been generated. (c) Decision Support Panel AB 2009
  48. 48. P a g e | 48Advanced administration and development - guidelines and referenceTask: rendering a chart as an imageFirst of all you need to use the ConfigurationService to retrieve the correct base settings. Once you havethat you can modify the values, if you want to make sure you know what chart types and color schemesare 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 URLfrom 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 pairsstring[] chartTypes = getChartTypes();string[] colorSchemes = getColorSchemes();settings.put("chart.basic.type", chartTypes[0]);settings.put("chart.basic.colorscheme", colorSchemes[0]);//ok, now lets create a querystring query = "SELECT {[Geography].[Geography].[State].MEMBERS} ONCOLUMNS,{[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 (c) Decision Support Panel AB 2009
  49. 49. P a g e | 49Advanced administration and development - guidelines and referenceTask: rendering a table as Excel pivotFirst of all you need to use the ConfigurationService to retrieve the correct base settings. Once you havethat you can modify the values, in this case we wont do anything at all since any changes would bepointless as we are requesting an EXCEL_PIVOT. Once you are done and you have a valid query you cancall 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 lets create a querystring query = "SELECT {[Geography].[Geography].[State].MEMBERS} ONCOLUMNS,{[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 filestring file = getTable(query,toString(settings),format);string url = "http://performancecanvashost:" + portValue + "/content/" + file;//and you can retrieve your data from the URL (c) Decision Support Panel AB 2009
  50. 50. P a g e | 50Advanced administration and development - guidelines and referenceOn XMLAServiceFirst of all. You will find the wsdl by accessinghttp://yourserver:yourport/services/XMLAService?wsdlOr you can just look in Appendix E if you have the stomach for reading WSDL files with the naked eye.On methodscombineThis method combines two MDX queries. Note that they have to point to the same cube.combine(string mdxA, string mdxB)PARAMETER DESCRIPTIONmdxA A valid MDX QuerymdxB A valid MDX QueryThe method returns the combined query statementfilterByUserThis method injects a query based security part that is dependent on the query based security settingsof the serverfilterByUser(string mdx, string userName)PARAMETER DESCRIPTIONmdx A valid MDX QueryuserName The username to be filtered onThe method returns a filtered query statement or null if an error occuredgetActionsThis method retrieves all the actions available for the given entity.getActions(string cube, string entity) (c) Decision Support Panel AB 2009
  51. 51. P a g e | 51Advanced administration and development - guidelines and referencePARAMETER DESCRIPTIONcube A valid cube nameentity A valid member in the cubeThe method returns a string array containing the information about the actions available (one string peraction, data is in key=value format)getChildrenThis method retrieves the children of the specified type for a given membergetChildren(string cube,string parentName, int childType)PARAMETER DESCRIPTIONcube The name of the cubeparentName 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 MemberThe method returns a string array, each string instance contains one child, data is in key=value format asusual.getCubeForMDXParses the MDX and gives you the appropriate cubenamegetCubeForMDX(string mdx)PARAMETER DESCRIPTIONmdx A valid MDX Query (c) Decision Support Panel AB 2009
  52. 52. P a g e | 52Advanced administration and development - guidelines and referenceThe method returns a string containing the cube name or null if an exception occured.getCubesThis method retrieves data about all the installed and configured cubes in the Performance Canvasservice instancegetCubes()PARAMETER DESCRIPTIONThis method returns a string array containing one string for each cube with data in key=value format.getDrillthroughStatementThis method constructs a drillthrough statement for the given entity and the given mdx.getDrillthroughStatement(string entity, string mdx)PARAMETER DESCRIPTIONentity A valid unique member namemdx A valid MDX QueryThe method returns a valid DRILLTHROUGH query for the entity or null if an exception occured.getDynamicSetThis method supplies resolving of dynamic sets (or named sets) in the cube (or of any valid MDXstatement). What happens is that the snippet is used to create a query and that query is used to resolvethe set into distinct members.getDynamicSet(string cube, string mdxSnippet)PARAMETER DESCRIPTIONcube A valid cube name for the PerformanceCanvas server instancemdxSnippet The name of named set, a definition of some other kind (like [Member].CHILDREN or ParallelPeriod or similar). (c) Decision Support Panel AB 2009
  53. 53. P a g e | 53Advanced administration and development - guidelines and referenceThe method returns an array of strings, each strings containing the data for one of the members in theresulting set. Data is in key=value format.splitThis method splits the MDX query into multiple sub queries based on the supplied hierarchy, it willreturn one query for each member of the hierarchy used in the current query.split(string hierarchy, string mdxQuery)PARAMETER DESCRIPTIONhierarchy The unique name of the hierarchy you want to split onmdxQuery A valid MDX QueryThe method returns an array of string arrays (string[][]), each string array contains two items, the first isthe member display name and the second is the MDX Query.transformThis 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)PARAMETER DESCRIPTIONcube A valid cube name for the Performance Canvas server instancenames 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) (c) Decision Support Panel AB 2009

×