LuisBE on Services : Excel Services Programmability

New MSDN Article on Extending Excel Services Through UDFs

LuisBE — Wed, 07 Feb 2007 00:11:00 GMT

From yours truly: Summary: Optimize version 1 of the Excel Services programmability framework to extend Microsoft Office Excel 2007 and Excel Services functionalities to work with SharePoint lists, query tables on Excel Services, external workbook references,...(read more)

Enable Paging in Your Array Formula UDFs

LuisBE — Fri, 02 Feb 2007 00:04:00 GMT

As I alluded to earlier, one way to overcome the limitation that array formulas do not dynamically resize to fit the dimensionality of the data being returned by your UDF is to use paging. Here is a simple way of enabling paging, without having to modify...(read more)

Consuming Business Data Catalog Entities in Excel Services

LuisBE — Thu, 01 Feb 2007 07:47:00 GMT

One of the coolest (only?) SharePoint external data features is the Business Data Catalog (BDC). The BDC is brand new with SharePoint 2007, and is not yet fully integrated into Excel and Excel Services... though, if you've read one or two other entries...(read more)

Working Around Dimensional Limitations of Using Array Formulas for UDF Return Values.

LuisBE — Tue, 09 Jan 2007 22:42:00 GMT

As you have noticed, many of my samples below use an Array Formula in Excel to retrieve an array of data returned by your UDF code. The biggest issue with taking this approach is that you need to know ahead of time the exact dimensions of the data being...(read more)

Using UDFs and Excel Formulas to Get a Query Table on Excel Services

LuisBE — Mon, 11 Dec 2006 22:36:00 GMT

As you may or may not know by now, one of the limitations in this version of Excel Services is the inability to publish workbooks containing Query Tables (tables that have external data as their source). There have been numerous blog posts on the web...(read more)

Refreshing EWA Automatically when Sharepoint Filters are Changed

LuisBE — Thu, 09 Nov 2006 09:08:00 GMT

If you played around with the post on using UDFs to write to SQL databases, you probably ended up creating a PivotTable connected to the SQL database the UDFs were writing to in order to see the new data showing up on the database. As you would have noticed...(read more)

Using UDFs to Write to SQL Databases from Excel Services

LuisBE — Thu, 09 Nov 2006 08:14:00 GMT

There are many reasons why writing straight to a SQL database is a desirable feature on a server. For example, one could imagine a solution where users would load up a workbook on Excel Services, change some parameters, and have that new data saved to...(read more)

Reloading an EWA Workbook Programmatically.

LuisBE — Fri, 27 Oct 2006 09:06:00 GMT

This will be a quickie.

I mentioned the EwaGetSessionId(id) function on my earlier post and didn't want to forget the other useful Javascript function we're shipping in the EwrScripts.js file.

With a simple Javascript function call you can trigger a workbook reload in EWR. All you have to do is call:

EwaReloadWorkbook(id)

And pass it the Web Part ID of the ECS web part (you can use the same technique from my earlier post on how to do this).

Enjoy!

Harvesting and Using the Session ID from EWA.

LuisBE — Fri, 27 Oct 2006 08:01:00 GMT

Every time you open a workbook in Excel Services you are actually creating your own instance of that workbook. Excel Services keeps track of those instances by assigning them a text string called a session ID. Once a session is created you can perform API calls to that session simply by passing that string into the API call.

For the greater part of this release it was impossible to determine what session ID was being used by an EWA web part. After some complaining from myself and others, as well as an infrastructure change due to other issues this is now possible. Excel Services now provides a Javascript function that will return the session ID corresponding to the web part ID passed in. Here’s the signature:

EwaGetSessionId(id)

Where id is a text string corresponding to the web part ID for the Excel Services web part (you can get this programmatically or by looking at the source of a web part page containing an EWA part, and searching for ECSFrame. The ID will be of the form “WebPartWPQ#” where # will be 1, 2, 3…).

Show Me:

One useful thing to do with the session ID would be to pass it to the EWA web part through a parameter, so that it can be referenced from within the workbook, or even used in a call to a User Defined Function. You can see where this would be useful in creating a session management workbook, user tracking, or to enable your UDFs to make API calls that affect the current, or other live sessions. NOTE: Changing sessions being used in EWA through API calls can be troublesome, as sessions are not re-entrant and EWA will return an error if it attempts to access session information while an API call is currently using that session.

Below I will show you how to harvest the session ID from an EWA part, and pass it into an Excel workbook through a parameter.

Example:

First you will need to create a web part or dashboard page with the following Sharepoint web parts:

1. Excel Web Access

2. Text Filter

3. Filter Actions

4. Content Editor (This one should be below all other web parts, as it will contain Javascript that will reference the parts created above)

Once you publish this page you will need to get the following information from the page’s source (right click in IE and View Source).

1. ECS Web Part ID – Search for “ECSFrame” in the source and get the corresponding “WebPartWPQ#”.

2. Text Filter Web Part ID – Same as above, but search for “TextSlicer”.

3. Filter Actions Web Part ID – Same as above, but search for “Apply Filters”.

Now that you have the values for the above ID’s you can create a text file which will contain your Javascript. Here’s what I have (replace the IDs under “DEFINE WEB PART NAMES” with the values you got from above):

function setSession(sessionId)

{

if(sessionId == null)

{

setTimeout('setSession(EwaGetSessionId(ECSWebPartID))', 1000);

}

else

{

var filterId = 'ctl00$m$g_' +

document.getElementById(TextSlicerWebPartID).WebPartID.replace(/-/g, "_") +

'$SPTextSlicerValueTextControl';

if(sessionId != document.getElementById(filterId).value)

{

document.getElementById(filterId).value = sessionId;

var actionId = 'ctl00_m_g_' +

document.getElementById(FilterActionsWebPartID).WebPartID.replace(/-/g, "_") +

'_PostBack(this)';

setTimeout(actionId,0);

}

var ECSWebPartID = 'WebPartWPQ3';

var TextSlicerWebPartID = 'WebPartWPQ5';

var FilterActionsWebPartID = 'WebPartWPQ4';

setTimeout('setSession(EwaGetSessionId(ECSWebPartID))', 1000);

</script>

Now save this text file to a Sharepoint document library and remember the path to it (e.g. http://MYSERVER/Documents/Scripts.txt). On your web part or dashboard page modify the Content Editor web part such that it’s Content Link points to your script file above. That script will now run every time the page is loaded.

Load a workbook in your EWA web part with a parameter defined, and connect the Text Filter web part to send it’s value to EWA’s parameter. If you like, you can also minimize the Filter Actions and Text Filter web parts to get them out of the way.

You’re DONE!!!

Now, every time you load this page the Javascript above will run, and once it successfully harvests the session ID from EWA it will stuff it into the Text Filter web part and call the Filter Actions function to pass it along to EWA. You should see your session ID in the workbook cell defined as the parameter.

Customizing EWA in the XLViewer.aspx Page

LuisBE — Thu, 19 Oct 2006 11:54:00 GMT

As you may have noticed if you have started to play around with Excel Services, the XLViewer.aspx page is the leanest way to open up a workbook on the server. There is very little Sharepoint UI added to this page and you are basically given a full screen Excel Web Access web part.

The biggest drawbacks of the XLViewer.aspx page are the lack of support for adding other web parts and connecting filter web parts, and the lack of customizability of the EWA properties.

This post will teach you how to get around the second drawback, and enable you to customize the EWA web part in XLViewer.aspx simply by sending it the query string parameters to be used.

How:

The coding here is actually pretty simple, and will enable you to do things like loading XLViewer.aspx in an IFRAME and specifying how many columns or rows to display, or whether or not to display the navigation toolbar. On a later date I will even show you how to create a Live.com gadget that will embed this page on http://www.live.com/.

The first thing you need to do is create a copy of XLViewer.aspx which is located in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\TEMPLATE\LAYOUTS (your mileage may vary). I named my copy MyXLViewer.aspx. You can now access this by going to http://SERVERNAME/_layouts/MyXLViewer.aspx, but obviously it won't be doing anything special just yet.

The next step is to open MyXLViewer.aspx in Notepad or any other text editor. Our goal here is to modify the Page_Load() event such that when the page loads we will set the properties passed in through the query string directly into the EWA web part object.

To accomplish this we first need to enable events on this page. You can do this by changing the 4th line on the page from reading:

<%@ Page language="C#" Codebehind="XlViewer.aspx.cs" AutoEventWireup="false"...
To read:
<%@ Page language="C#" Codebehind="XlViewer.aspx.cs" AutoEventWireup="true"...

Congratulations! You have now enabled us to handle events in the page. The next thing we need is a little bit of code to parse the query string for the properties we want, and stuff them into the EWA web part object so that it does what we tell it to do.

Here's the code you want to place just before the </HEAD> tag on the page:

private void Page_Load(object sender, System.EventArgs e)

{

if (Request.QueryString["RowsToDisplay"] != null)

m_excelWebRenderer.RowsToDisplay =

Int32.Parse(Request.QueryString["RowsToDisplay"]);

if (Request.QueryString["ColumnsToDisplay"] != null)

m_excelWebRenderer.ColumnsToDisplay =

Int32.Parse(Request.QueryString["ColumnsToDisplay"]);

if (Request.QueryString["ToolbarVisibilityStyle"] != null)

if (Request.QueryString["ToolbarVisibilityStyle"] == "1")

m_excelWebRenderer.ToolbarStyle =

ToolbarVisibilityStyle.FullToolbar;

else

m_excelWebRenderer.ToolbarStyle =

ToolbarVisibilityStyle.None;

}

</script>

The code above will add support for 3 query string parameters, namely: RowsToDisplay, ColumnsToDisplay, and ToolbarVisibilityStyle. You use these parameters simply by appending them to the query string, so if you want to load http://SERVERNAME/Documents/Book1.xlsx showing 5 columns, 10 rows, but no Toolbar you would browse to http://SERVERNAME/_layouts/MyXLViewer.aspx? id=http://SERVERNAME/Documents/Book1.xlsx &RowsToDisplay=10&ColumnsToDisplay=5&ToolbarVisibilityStyle=0

That's all! I told you it would be simple. Using this same method you can customize any of the Excel Web Access web part properties just by adding them to the Page_Load event as I have shown above. In order to figure out all of the variable names and types for the properties we provide you can open up an existing EWA web part page, click on Modify Web Part drop down and choose Export. You can save the *.webpart file anywhere and open it on Notepad. Here's what I'm seeing on our current builds:

<properties>
<property name="Height" type="string" />
<property name="HelpMode" type="helpmode">Modeless</property>
<property name="CatalogIconImageUrl" type="string">/_layouts/images/ewr023.gif</property>
<property name="AutomaticPeriodicDataRefresh" Type="Microsoft.Office.Excel.WebUI.AutomaticPeriodicDataRefreshMode, Microsoft.Office.Excel.WebUI, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">Disabled</property>
<property name="ColumnsToDisplay" type="int">20</property>
<property name="Description" type="string"></property>
<property name="ShowVisibleItemButton" type="bool">True</property>
<property name="Direction" type="direction">NotSet</property>
<property name="MissingAssembly" type="string"></property>
<property name="Width" type="string" />
<property name="AllowConnect" type="bool">True</property>
<property name="AllowSorting" type="bool">True</property>
<property name="AllowHyperlinks" type="bool">True</property>
<property name="TitleUrl" type="string" />
<property name="AllowEdit" type="bool">True</property>
<property name="RowsToDisplay" type="int">75</property>
<property name="ShowWorkbookParameters" type="bool">True</property>
<property name="CloseWorkbookSessions" type="bool">False</property>
<property name="WorkbookUri" type="string" />
<property name="ChromeType" type="chrometype">TitleOnly</property>
<property name="ChromeState" type="chromestate">Normal</property>
<property name="AllowPivotSpecificOperations" type="bool">True</property>
<property name="AutoGenerateTitle" type="bool">True</property>
<property name="AllowFiltering" type="bool">True</property>
<property name="VisibleItem" type="string" />
<property name="AllowInExcelOperations" type="bool">True</property>
<property name="AllowNavigation" type="bool">True</property>
<property name="ExportMode" type="exportmode">All</property>
<property name="ToolbarStyle" type="Microsoft.Office.Excel.WebUI.ToolbarVisibilityStyle, Microsoft.Office.Excel.WebUI, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">FullToolbar</property>
<property name="AllowInteractivity" type="bool">True</property>
<property name="HelpUrl" type="string" />
<property name="AllowPeriodicDataRefresh" type="bool">True</property>
<property name="AllowClose" type="bool">True</property>
<property name="Hidden" type="bool">False</property>
<property name="TitleIconImageUrl" type="string">/_layouts/images/ewr023.gif</property>
<property name="AllowManualDataRefresh" type="bool">True</property>
<property name="AllowHide" type="bool">True</property>
<property name="AllowZoneChange" type="bool">True</property>
<property name="AutoGenerateDetailLink" type="bool">True</property>
<property name="AllowRecalculation" type="bool">True</property>
<property name="Title" type="string">Excel Web Access</property>
<property name="AllowParameterModification" type="bool">True</property>
<property name="AllowMinimize" type="bool">True</property>
</properties>

NOTE: The list above is only there for you to be able to get the "property name" for everything we support in the Excel Web Renderer object, and the "type" it maps to. For example, if you wanted to set this particular property from the list above:

You would simply add code to the Page_Load() handler to do this:

m_excelWebRenderer.AllowMinimize = true; // or false if you want since type is bool

SEE ATTACHED MYXLVIEWER.ASPX PAGE!

Consuming Sharepoint Lists in Excel Services

LuisBE — Fri, 29 Sep 2006 09:42:00 GMT

<UPDATE: New CS file attached with a minor bug fix and some major code reduction since I found the SharePoint format converter method :o) >

There are a few features that the v1 of Excel Services will not support out of the box. One of these is grabbing data from Sharepoint Lists.

Luckily enough the UDF framework allows us to write some pretty simple code that can grab the data from Sharepoint and return it to the Excel grid through an array formula.

Since I ran into this limitation a few times and numerous people have been asking for this feature I decided to write a UDF that does just that.

The goal here is to have an UDF that can be called as an array formula, whose function is to grab data from a Sharepoint and return it to the Excel grid.

Here is the signature for the UDF I created:

public object[,] getSharepointView(string serverName, string siteName, string listName, string viewName, bool getTitles)

Usage:

Basically you select the range in an Excel grid that you would like the List data returned to, type “=getSharepointView(“http://myserver.com”, “MySSPSite”, “MyList”, “MyView”, TRUE)” and CTRL+SHFT+ENTER.

That last parameter will return only the list data when it is FALSE, and will also return the list column titles when it is TRUE.

Once you load the workbook to a server that has the UDF loaded (or on a client that has the COM add-in for this dll registered) you will get the data that user would see had he gone to the Sharepoint site himself.

At that point you can do with the data as you please… add some Conditional Formatting, use it as the source data for a Pivot, etc…

Code:

The code is a bit extensive to paste inline here, so I’m attaching the .cs file to this post. You will notice that I’m using the Microsoft.Sharepoint namespace which can be found in the Microsoft.Sharepoint.dll binary located in C:\Program Files\Common Files\Microsoft Shared\web server extensions\12\ISAPI on the Sharepoint server. I have also decorated my class so that you can register it as a COM add-in and use it in the Client as well as the Server.

SEE .CS FILE ATTACHED!

Impersonating EWA users in your UDFs

LuisBE — Fri, 29 Sep 2006 09:18:00 GMT

Excel Services UDFs are generally run under the credentials of the service account used by the Office Server installation. This may not be exactly what you want if you would like your UDFs to return data that is specific to the user that opened the workbook. This is also not what you would want if you want the UDF code to perform other functions (e.g. read/write to SQL, access system resources, etc...) under the credentials of the user that opened the workbook.

In a more thorough example, you may want to have an UDF that will read certain information from a SQL database. It may be the case that depending on the user's credentials the information returned by SQL is different, and we want that reflected in our UDF so the data that is returned to Excel is correct.

The function below will do everything you need. All you have to do is call this function in your UDF (which needs to be decorated with the ReturnsPersonalInformation=true UdfMethod attribute) before you do anything that needs that user's credentials:

NOTE: Shahar pointed out a bug that I left out here, once you are done doing what you'd like to do as the impersonated EWR user you will want to release the impersonation from the thread, so that it goes back to the default account, that way you don't have an Excel Server thread running with the user's credentials when it's not needed. I have changed the code to fix this problem, here's the new code and how to use it.

// Causes the current UDF to impersonate the user that loaded it through EWR

private WindowsImpersonationContext impersonateUser()

{

WindowsIdentity wi = null;

try

{

// Get the user that loaded Workbook & impersonate

// NOTE: To re-use this for a Client UDF first

// check that your process name is w3wp since

// impersonation is not needed on the Client.

wi = (WindowsIdentity)

System.Threading.Thread.CurrentPrincipal.Identity;

}

catch (System.Exception ex)

{

throw new InvalidOperationException(

"Impersonation failed.")

}

return wi.Impersonate();

}

USAGE:

To use this code such that you only impersonate the user during the needed block, here's what you do:

// uses impersonation

public void useImpersonation()

{

using (WindowsImpersonationContext wiContext = impersonateUser())

{

// Inside this block you are impersonating the user

}

// No longer impersonating user

}