PerformancePoint Monitoring Web Service – Part 2

In my last post we looked at the basics of connecting to the web service and using some simple functions to retrieve some metadata.  Those of you who downloaded the sample project would have spotted that I added some functionality to retrieve all the annotations for a given scorecard – something we’ve been asked for by a number of clients.  This time we’ll look a little deeper and look at how we could automate production of the FCOs (First Class Objects) within PPSM.

The process of building a dashboard in code is in essence just as you would do it in Dashboard Designer.  Remember when you are using Dashboard Designer it’s actually making calls to the web service behind the scenes – no dll’s involved.  If you use a tool such as Fiddler2 you can see exactly what is getting passed in the calls.

So first we need to create a data source.  Once again our friendly PPSM dev team have named the functions just as you would expect so no prizes for guessing we need to use the CreateDataSource function.  You then need to create a datasource object in your code which is passed to that function.  This is fairly straight-forward in that you set the attributes of the data source object you’ve created and give it a unique ID (GUID).  The usual apologies for the state of my code!

private void CreatePPSDS(PPSM.PmService mon)
{
   //declare the datasource
    PPSM.DataSource ds = new PPSM.DataSource();

    //set the attributes of the data source
    ds.SourceName = "ADOMD.NET";
    ds.ServerName = "Localhost";
    ds.DatabaseName = "Adventure Works DW Standard Edition";
    ds.CubeName = "Adventure Works";
    ds.CubeDisplayName = "Adventure Works";

    //give the data source a GUID
    ds.Guid = System.Guid.NewGuid();

The first quirk is that the data source name, owner and description aren’t directly exposed on the DataSource object but in a BpmProperty array called Properties so first you need to declare each element individually so you can set it’s individual properties; Name is a BpmPropertyText, Description is a BpmPropertyLongText and Owner is a BpmPropertyUser.  This properties array is common to all FCO’s (and in fact inherited from the base Element Object) so this will be the same method we use for Data Sources, Scorecards, Dashboards etc.

        //declare the three individual property types for the property array
        PPSM.BpmPropertyText dsName = new PPSM.BpmPropertyText();
        PPSM.BpmPropertyLongText dsDesc = new PPSM.BpmPropertyLongText();
        PPSM.BpmPropertyUser dsOwner = new PPSM.BpmPropertyUser();
        
        //set some details for the properties
        dsName.DisplayName = "Name";
        dsName.Description = "Name Description";
        dsName.Text = "A data source name";
        dsName.Visible = true;
        dsDesc.Text = "MyDataSourceDescription";
        dsOwner.Login = "TCK";

Next we have to initialise the Properties array on the DataSource object itself so we can assign the individual properties we declared earlier to the elements within it.  And here comes the next quirk – and I’ll unashamedly admit that this one had me completely foxed! Each element of the DataSource properties array requires a uniquename, and not just any unique name but a very specific one – 8dd07d4d87794510afdb1f07664359bc.  Without this your data source will be created but won’t have a name, description or owner!  Thanks to Alyson Powell Erwin of the PPSM Team for solving this one for me 🙂

        //initialise the properties array of the data source
        ds.Properties = new PPSM.BpmProperty[3];

        //set the properties array with the three elements
        ds.Properties[0] = dsName;
        ds.Properties[1] = dsDesc;
        ds.Properties[2] = dsOwner;

        //declare a GUID and set the unique id of each property
        ds.Properties[0].UniqueName = "8dd07d4d87794510afdb1f07664359bc_Element_Name";
        ds.Properties[1].UniqueName = "8dd07d4d87794510afdb1f07664359bc_Element_Description";
        ds.Properties[2].UniqueName = "8dd07d4d87794510afdb1f07664359bc_Element_Owner";

Note the “_Element_…” on the end of the UniqueName – this is also mandatory.  That’s all the quirks now 🙂

Next we can add members to our roles if required.  These are stored in the Memberships array of the DataSource

        //initialise the Memberships array
        ds.Memberships = new PPSM.Membership[1];
        //for each membership you want to add you then need to initialise the element of the array
        ds.Memberships[0] = new PPSM.Membership();
        //then set the properties (note the control backslash in the login name)
        ds.Memberships[0].Login = "Domain\login";
        ds.Memberships[0].Role = "Editor";

Finally call the CreateDataSource method passing your DataSource object of the web service and your work here is done!

        //finally pass to the web service call
        mon.CreateDataSource(ds);

If you need to update the data source then you retrieve the data source using GetDataSource, update the properties as before and then pass the object the CreateDataSource function. This automatically deals with versioning.

The sample project is here: PPSMWebService.zip (24.93 kb)  (don’t forget to open as a web site rather than a project in VS)

Next time we’ll look at how to create one of the other 1st class objects using our data source.