Microsoft Excel

Preventing auto_open and Workbook_Open events from running

FredK — Tue, 15 Dec 2009 19:20:00 GMT

Today’s author is Jan Karel Pieterse, an Excel MVP. You can find more useful tips from Jan Karel on his website: http://www.jkp-ads.com/. This post provides detailed instructions to prevent auto-open and Workbook-Open events from running.

As a fulltime developer I oftentimes open files containing VBA and want to be able to run code. At the same time I sometimes want to prevent Workbook_Open event code or an Auto_Open macro from running. This little article shows you how to achieve that.

Excel 2010

Macro security set to low or trusted document

If you have set your macro security to "Enable All Macros" or you have already set the document to trusted or the document is in a trusted folder, click File, Open, select your file and hold down the shift key when you click the Open button:

Fig. 1: Selecting the file from the File, Open dialog (Excel 2010)

Of course your file might be listed in the Most Recently Used files (MRU) list. In that case, hold shift when you click the file in the list:

Fig. 2: Clicking the file on the MRU (Excel 2010)

Doing so will prevent the Workbook_Open event from firing and the Auto_Open macro from running.

Macro security set to prompt

If your document is not in a trusted folder, has never been set to be trusted and macro security is set to something other than enable all macros to run, you can repeat what I've shown above.

Normally, if you open such a document, Excel will show the security bar. In this situation however, due to you holding down shift, Excel shows this window:

Fig. 3: Enable macros dialog (Excel 2010)

Because you held down the shift button when you clicked the file in the MRU or when you clicked the Open button, you can now just click "Enable macros" and no Automacros will run.

Excel 2007

Macro security set to low or trusted document

Fig. 4: Selecting the file from the File, Open dialog (Excel 2007)

Of course your file might be listed in the Most Recently Used files (MRU) list. In that case, hold shift when you click the file in the list:

Fig. 5: Clicking the file on the MRU (Excel 2007)

Doing so will prevent the Workbook_Open event from firing and the Auto_Open macro from running.

Macro security set to prompt

If your document is not in a trusted folder, has never been set to be trusted and macro security is set to something other than enable all macros to run, you can repeat what I've shown above.

Normally, if you open such a document, Excel will show the security bar. In this situation however, due to you holding down shift, Excel shows this window:

Fig. 6: Enable macros dialog (Excel 2007)

Because you held down the shift button when you clicked the file in the MRU or when you clicked the Open button, you can now just click "Enable macros" and no Automacros will run.

Excel 97, 2000, XP, 2003

Macro security set to low or trusted document

In case your macro security is set to low, or your VBA code is signed and you have set the publisher as trusted, you must hold down the shift key when you click the Open button on the File, Open dialog:

Fig. 7: Opening the file from the File, Open dialog (Excel 97-2003)

Of course your file might be listed in the Most Recently Used files (MRU) list. In that case, hold shift when you click the file in the list:

Fig. 8: Clicking the file on the MRU (Excel 97-2003)

Doing so will prevent the Workbook_Open event from firing and the Auto_Open macro from running.

Macro security set to medium or higher

If your macro security is set to at least "Medium" and you have never set its publisher to trusted (for a signed macro) you can forget about holding shift when opening the file or clicking the file on the MRU list. Instead, you must hold shift when you enable macros:

Fig.9: Hold shift when you press Enable macros

Doing so will prevent the Workbook_Open event from firing and the Auto_Open macro from running.

Daniel’s Extreme Lookup Collection

FredK — Thu, 10 Dec 2009 23:08:53 GMT

Today’s author is Daniel Wiesenfeld, an Excel and Access Power User who is sharing his Extreme Lookup Collection with us so we can use the Excel User Defined Functions (UDFs) he created to enhance the lookup functionality. His web site daanalytics.com is currently under construction and should be available soon.

In the Visual Basic Editor, insert a Module and paste the following code:

' XVLOOKUP (& XHLOOKUP)
' Works just like a vlookup (and hlookup) except that the user refers to a lookup colum (or row)
' rather than a range, it is 0 based and the user can "look left" (or "look upward") by using a negative
' column (or row) index.
' There is also an optional argument to allow the user to offset the cell to be returned by any number
' of rows (or columns)
' I do not give users the option to choose between exact or approximate match - it is always exact

Function XVLOOKUP(Lookup_Column As Range, Lookup_Value As Variant, Column_Index As Integer, _
    Optional Row_Offset As Integer)

Dim DCol, DRow As Integer
Dim DSheet, strCRange, strARange As String
Dim ARange As Range


DCol = Lookup_Column.Column
DCol = DCol + Column_Index

If IsMissing(Row_Offset) Then
    Row_Offset = 0
End If

DSheet = Lookup_Column.Parent.Name
strCRange = Lookup_Column.Address

DRow = WorksheetFunction.Match(Lookup_Value, Worksheets(DSheet).Range(strCRange), 0)
DRow = DRow + (Lookup_Column.Row - 1) + Row_Offset

Set ARange = Range(Cells(DRow, DCol), Cells(DRow, DCol))
strARange = ARange.Address

XVLOOKUP = Worksheets(DSheet).Range(strARange).Value

End Function

Public Function XHLOOKUP(Lookup_Row As Range, Lookup_Value As Variant, Row_Index As Integer, _
    Optional Column_Offset As Integer)

Dim DCol, DRow As Integer
Dim DSheet, strRRange, strARange As String
Dim ARange As Range


DRow = Lookup_Row.Row
DRow = DRow + Row_Index

If IsMissing(Column_Offset) Then
    Column_Offset = 0
End If

DSheet = Lookup_Row.Parent.Name
strRRange = Lookup_Row.Address

DCol = WorksheetFunction.Match(Lookup_Value, Worksheets(DSheet).Range(strRRange), 0)
DCol = DCol + (Lookup_Row.Column - 1) + Column_Offset

Set ARange = Range(Cells(DRow, DCol), Cells(DRow, DCol))
strARange = ARange.Address

XHLOOKUP = Worksheets(DSheet).Range(strARange).Value

End Function

'XVHLOOKUP
'looks up value in a range based on column and row headers
Public Function XVHLOOKUP(Lookup_Range As Range, Row_Header As Variant, Column_Header As Variant)

Dim DCol, DRow, TRow, BRow, LCol, RCol As Integer
Dim DSheet, strCRange, strRRange, strARange As String
Dim CRange, RRange, ARange As Range
DSheet = Lookup_Range.Parent.Name

TRow = Lookup_Range.Row
BRow = TRow + Lookup_Range.Rows.Count - 1

LCol = Lookup_Range.Column
RCol = LCol + Lookup_Range.Columns.Count - 1


Set CRange = Range(Cells(TRow, LCol), Cells(BRow, LCol))
strCRange = CRange.Address

DRow = WorksheetFunction.Match(Row_Header, Worksheets(DSheet).Range(strCRange), 0)
DRow = DRow + Lookup_Range.Row - 1

Set RRange = Range(Cells(TRow, LCol), Cells(TRow, RCol))
strRRange = RRange.Address

DCol = WorksheetFunction.Match(Column_Header, Worksheets(DSheet).Range(strRRange), 0)
DCol = DCol + Lookup_Range.Column - 1

Set ARange = Range(Cells(DRow, DCol), Cells(DRow, DCol))
strARange = ARange.Address

XVHLOOKUP = Worksheets(DSheet).Range(strARange).Value

End Function


'XLOOKUP
'Looks up value in a range and returns value of cell that is a specified number of rows and columns
'away from lookup cells

Public Function XLOOKUP(Lookup_Range As Range, Lookup_Value As Variant, _
    Row_Offset As Integer, Column_Offset As Integer)

Dim DRow, DCol As Integer
Dim DSheet, DAddress, strARange As String
Dim ARange As Range

DRow = Lookup_Range.Find(Lookup_Value).Row
DCol = Lookup_Range.Find(Lookup_Value).Column

DRow = DRow + Row_Offset
DCol = DCol + Column_Offset

DSheet = Lookup_Range.Parent.Name

Set ARange = Range(Cells(DRow, DCol), Cells(DRow, DCol))
strARange = ARange.Address

XLOOKUP = Worksheets(DSheet).Range(strARange)

End Function

Introducing the JavaScript Object Model for Excel Services in SharePoint 2010

Joseph Chirilov — Tue, 01 Dec 2009 05:16:00 GMT

Thanks to Christian Stich, a consultant working on Excel Services projects, for putting together this series on the Excel Services JavaScript Object Model.

Excel Services 2010 has added two entirely new programming APIs: The REST API which I covered in an earlier series of posts and the JavaScript Object Model (JSOM) which I will discuss in this post.

The JavaScript Object Model (JSOM) enables a whole new set of solutions using Excel Services. With the JSOM it is possible to detect and react to a user's interactions with an Excel Web Access (EWA) web part and to programmatically interact with one or multiple EWA web parts.

How Do I Use It?

Using the JSOM is done by inserting JavaScript code on the page that contains the EWA web part(s). This can be done either by adding the code to the web part page using the Content Editor web part or by directly editing the .aspx page itself.

What Does It Offer?

The JSOM enables the developer to access items such as sheets, ranges, tables, PivotTables, and charts. It is possible to set and retrieve values from individual cells or from Excel style A1 ranges or named ranges. The JSOM also provides for events that are raised when the user changes the active selection or active cell or when the user starts editing a cell. Moreover, the JSOM can be used to scroll to a different region and to switch the displayed sheet or named item.

To see the class diagram for the JSOM please click the thumbnail below.

Please note that the class diagram is preliminary and may have some changes at the time when Excel Services 2010 is officially released.

Using the JSOM - A Simple Example

Often people want to use an EWA web part as a data source. EWA web parts can consume data via SharePoint's web part filter framework. However the opposite, using EWA web parts as data sources is not supported by SharePoint 2010.

The example showcases using the JSOM for the detection of user events in one EWA and using those user events and corresponding data to programmatically drive another EWA. This can be used to effectively use an EWA as a data source.

All the developer or user has to do apart from building a web part page with two EWA web parts is to add a Content Editor web part and link it to a file containing the JavaScript code such as the example below.

// initialize variables
var EWA1 = null;
var EWA2 = null;

//set page event handlers for onload, proceed to the PageLoad function defined below once the page has loaded if (window.attachEvent)
{
window.attachEvent("onload", PageLoad);
}

//proceed to the GetEWA function defined below once the Excel Services JavaScript OM is 'ready'
function PageLoad()
{
Ewa.EwaControl.add_applicationReady(GetEwa);
}

//attach to the individual Excel Web Access (EWA) web parts
function GetEwa()
{
EWA1 = Ewa.EwaControl.getInstances().getItem(0);
EWA2 = Ewa.EwaControl.getInstances().getItem(1);

    if(EWA1 && EWA2)
    {
        // add the event handler for the ActiveSelectionChanged event
        EWA1.add_activeSelectionChanged(activeSelectionChangedHandler);
    }
}

// This is the handler for the ActiveSelectionChanged event.
// When the user changes the selection in the EWA web part, this event is raised
function activeSelectionChangedHandler(rangeArgs)
{
    var sel = rangeArgs.getRange();
    var sheet = sel.getSheet().getName();
    var values = rangeArgs.getFormattedValues();

    // Make sure that the user selected cells on Sheet1 - we may not want any or a different action taken if the user is on a different sheet
    if(sheet = "Sheet1")
    {
        // Check to see if the user has clicked on cells A1, A2, B1, or B2 which act as buttons to select the view of the other web part
        if(sel.getColumn() >= 1 && sel.getColumn() <=2 && sel.getRow() >= 1 && sel.getRow() <= 2)
        {
            EWA2.getActiveWorkbook().getNamedItems().getItemByName(values[0][0]).activateAsync(activateCallBack,values[0][0]);
        }

        // Check to see if the user has clicked on cells A5 through A14 which contain the company names - copy the selected names to the other web part
        if(sel.getColumn() == 1 && sel.getColumnCount() == 1 && sel.getRow() >= 5 && sel.getRowCount() <= 10)
        {
            EWA2.getActiveWorkbook().getRange('Stocks',1,1,values.length,1).setValuesAsync(values,setCallBack,null);
        }
    }
}

function activateCallBack(returnValues)
{
    // All we are doing here is to set the status of the window to indicate that the named item has been activated in the second web part
    // We could also do nothing in this case - in other scenarios, it may be desirable or necessary to run code once an asynchronous function completes running
    window.status = 'Activated Named Item "' + returnValues.getUserContext() +'" in "Detailed Info" EWA Web Part';
}

function setCallBack(returnValues)
{
// All we are doing here is to set the status of the window to indicate that the data was copied from the first web part to the second web part
window.status = 'Selected values have been copied from the "StockInfo" EWA Web Part to the "Detailed Info" EWA Web Part';
}

</script>

So, let's see what these few lines of JavaScript code that we have embedded on the web part page can do.

The web part on the left side contains four "buttons" (cells A1, A2, B1, and B2) which contain strings that correspond to named items present in the web part on the right hand side. "Market Cap", "Volume", "P/E Ratio" are charts and "Stocks" is a named range.

Below these "buttons" is a list of company names - these do not have to be fixed and could be changed or new ones could be added by a viewer of the web part page. Next to the company names is the most recent share price of each company's stock. This data as well as the other stock market data used in this example could be live data retrieved either via Excel Services external data support, or via User Defined Functions.

The viewer of the web part page can select one or more companies by simply using the mouse to select the cells with the companies' names. In this case, the user has selected "Microsoft" and "Contoso" in the left web part - the JavaScript code detects the change of the active selection and copies these company names ("Microsoft" and "Contoso") to the right web part.

The user then clicks on the Market Cap "button" (cell A1) - again the JavaScript code detects the change in the active selection and accordingly switches the right web part to display the Market Cap chart.

Next, the user highlights all four companies - this change in the active selection is again detected and the selected companies are copied from the left web part to the right web part. This then results in the Market Cap chart being updated to show all four companies.

Finally, the user clicks on the Volume "button" (cell B1) - the JavaScript code thus causes the web part on the right to display the stock trade Volume chart, showing all four companies that had been selected.

Summary

The JSOM is a powerful new API that expands Excel Services capabilities and that enables Excel Services to be used for completely new solutions. The JSOM can be used by itself to provide a means for automating Excel Web Access, or to provide part-to-part communication between different EWA web parts. It can also be used with other APIs such as the new Visio Services JavaScript Object Model, Bing Maps SDK and many others to build custom solutions/mash-ups.

Create conditional drop-down lists

FredK — Tue, 24 Nov 2009 19:46:09 GMT

Today’s author is Reinout Dorreboom from the Netherlands, a Technical Consultant at Getronics, where he has worked with Office applications for many years, and where his Microsoft Certified Training skills enabled him to help other people get up to speed with Excel.

In Excel 2007 (and earlier), it’s possible to create a drop-down list. By using the INDIRECT function, you can then create additional drop-down lists that are conditional to the first drop-down list.

In this example we’ll create the following table:

	A	B	C	D
1		Country	City	Street
2	David	Netherlands	Rotterdam	Abraham van Stolkweg
3	Linda	Germany	Munich	MunichStreet1
4	Peter	Britain	London	Bacon Street (E1)

Columns B, C, and D contain drop-down lists. If you select Netherlands in the drop-down list in column B, only Dutch cities will be displayed in the drop-down list in Column C. If you select Germany, only German cities will be displayed in the drop-down list in Column C. Similarly, when you select a city in Column C, only the street names of that city will be displayed in column D.

To create conditional lists, complete the following procedures.

Enter the data

First, we’ll create the table as shown below.

Now, we’ll create a few lists.

First, we’ll create a list of countries. In this example, we create the following countries:

In Cell F1, type Netherlands.
In Cell G1, type Britain.
In Cell H1, type Germany.

As you can see I made a horizontal list instead of a vertical list. This isn’t really necessary, but it is easier to maintain to keep the cities under the right country.

Second, we’ll add three cities to pick from for each country.

Cell F2: Amsterdam	Cell G2: London	Cell H2: Bonn
Cell F3: Rotterdam	Cell G3: Canterbury	Cell H3: Berlin
Cell F4: Eindhoven	Cell G4: Manchester	Cell H4: Munich

Now, we’ll create a list of streets for each city. In the example, you can then choose from two streets per city.

Cell F8: AmsterdamStreet1	Cell G8: LondonStreet1	Cell H8: BonnStreet1
Cell F9: AmsterdamStreet2	Cell G9: LondonStreet2	Cell H9: BonnStreet2
Cell F11: RotterdamStreet1	Cell G11: CanterburyStreet1	Cell H11: BerlinStreet1
Cell F12: RotterdamStreet2	Cell G12: CanterburyStreet2	Cell H12: BerlinStreet2
Cell F14: EindhovenStreet1	Cell G14: ManchesterStreet1	Cell H14: MunichStreet1
Cell F15: EindhovenStreet2	Cell G15: ManchesterStreet2	Cell H15: MunichStreet2

The worksheet should look like this now:

Define the names

Ok, all content is provided. Now we can start creating a name for each range.

Select the cells F2:F4 and name the range: Netherlands
Select the cells G2:G4 and name the range: Britain
Select the cells H2:H4 and name the range: Germany
Select the cells F7:F8 and name the range: Amsterdam
Select the cells F10:F11 and name the range: Rotterdam
Select the cells F13:F14 and name the range: Eindhoven
Select the cells G7:G8 and name the range: London
Select the cells G10:G11 and name the range: Canterbury
Select the cells G13:G14 and name the range: Manchester
Select the cells H7:H8 and name the range: Bonn
Select the cells H10:H11 and name the range: Berlin
Select the cells H13:H14 and name the range: Munich

For information about how to define names, see Define and use names in formulas.

Create the drop-down lists

After defining the names, we can create the drop-down lists.

First, we’ll make a drop-down list for Country.

1. Select cell B2.

2. On the ribbon, click the Data tab.

3. In the Data Tools group, click Data Validation.

4. Fill the values as follows:

In the Allow box, select List.
In the Source box, type =$F$1:$H$1

Note: Dollar signs ($) are used in the formula so that we can drag the cell downwards from David to Peter.

5. Click OK.

6. Drag the cell content downwards.

Now, we’ll make the first conditional drop-down list.

1. Select Cell C1.

2. On the ribbon, click the Data tab.

3. In the Data Tools group, click Data Validation.

4. Fill the values as follows:

     In the Allow box, select List.
   In the Source box, type =INDIRECT($B2)


Note: In the formula, a Dollar sign ($) is not placed before the row. That is because we want to drag the cell formula downwards.

5. Click OK.

Note: If you click OK, you may get an error message indication that the evaluation of the formula was an error. This is correct, because the cell where this list depends on (B2) is empty.

6. Drag the cell content downwards.

Now, we’ll make our second conditional drop-down list.

1. Select cell D2.

2. On the ribbon, click the Data tab.

3. In the Data Tools group, click Data Validation.

4. Fill the values as follows:

     In the Allow box, select List.
   In the Source box, type =INDIRECT($C2)


Note: In the formula, a Dollar sign ($) is not placed before the row. That is because we want to drag the cell formula downwards.

5. Click OK.

Note: If you click OK, you may get an error message indicating that the evaluation of the formula was an error. This is correct, because the cell on which this list depends (C2) is empty.

6. Drag the cell content downwards.

Done!
If you choose a country, the City field displays only cities for that country. And only streets for the selected city will be shown.

Uncovering Publish to Excel Services in Excel 2010

Joseph Chirilov — Tue, 24 Nov 2009 05:50:00 GMT

Thanks to Amy Lin for putting together this post.

In Excel 2007, we introduced the ability to publish workbooks to SharePoint. This feature enabled users to upload Excel workbooks (or specific workbook items) on to their SharePoint sites for people to view and interact with using Excel Services.

In Excel 2010, this feature has all the same functionality but the entry point has changed. For the Technical Preview/Beta users, the entry point will look different since these changes will be reflected in the final release of Excel. I will walk through the workflow of how to publish workbook items to the server with the new user experience. If you want a refresher of how to publish workbooks in Excel 2007, see our previous blog entry on: How do I publish workbooks to the server?.

In Office 2010, the Office menu has been replaced by Backstage. To learn more about the Backstage View, read these blog entries:

In Backstage, the publish entry point is accessed from clicking the “Save & Send” tab on the left and then clicking the “Save to SharePoint” billboard in the middle.

Excel 2010 publish entry points

In “Save to SharePoint”, you will find the “Publish Options” button, a list of locations and the “Save As” button. The “Publish Options” button allows you to pick specific items you want to publish. The list of locations helps you save to common locations or you can click the “Save As” at the bottom of the list.

Publish Entry Points

The “Publish Options” button from Backstage and in the "Save As” dialog launches the dialog below:

Excel 2010 Publish Options dialog

For all the Excel 2007 users, this dialog will seem very familiar because it is the same dialog used to specify which workbook items to publish to the server. For example, if you want to publish a specific chart and a PivotTable, select “Items in the Workbook” from the drop down and check the Chart and PivotTable you desire. In the image below, we’ve selected “Chart 3” and “PivotTable1”.

Once you are done making your selections, click “OK”. If you clicked on “Publish Options” from Backstage, you will return back to that view. Once in Backstage, if you see a recent location you want to save to, double-click on it in the list or click “Save As” at the bottom of the locations.

The “Save As” button launches the following dialog where the default location is the location selected in the gallery. However, you can change the location of the file once you are in this dialog. The “Publish Options” button is exposed here so you can also select which workbook items to publish from this entry point.

Excel 2007 Save to SharePoint Save As Dialog

After clicking “Save”, your chart & Pivot Table can now be viewed in a browser!

Excel in the browser

Summary

The publish feature behaves the same as it did in 2007. The new Backstage in Office 2010 gave us an opportunity to move the entry point to a more natural location. I look forward to any feedback you have on the publishing experience. Happy publishing!

Excel Services in SharePoint 2010 Feature Support

Joseph Chirilov — Thu, 19 Nov 2009 17:00:00 GMT

Excel Services does a good job of rendering Excel spreadsheets with a high degree of fidelity. In other words, what you see in Excel is what you will see in Excel Services. Excel, however, is incredibly feature rich, comprising features added over decades of development. By comparison, Excel Services is a young product, so naturally Excel Services doesn’t yet support all the things you might create in Excel. So what does Excel Services in SharePoint 2010 support? And how does Excel Services deal with files that contain features it doesn’t support? That is the topic of today’s blog post.

I am going to assume readers are aware of our feature support in Excel Services 2007. If you need a refresher, read our original blog topic on the matter. The following sections build on top of this topic.

Support For New Excel 2010 Features

Hopefully by now you’ve heard about some of the great features in Excel 2010 (If not, read through our posts here). By and large, most of the new features you’ll hear talked about for Excel 2010 will work in some way in Excel Services. Some features will display as they do in Excel. Others are also interactive.

Sparklines can be viewed
Icon Set and Data Bar improvements can be viewed
The new functions are supported
Slicers can be viewed and interacted with
PivotTable Named Sets can be viewed
Other PivotTable improvements can be viewed
PowerPivot files can be viewed and interacted with

In addition to this, I am happy to announce that embedded images, a long time feature of Excel, are now supported and can be viewed in Excel Services. Here’s an example of a report with an embedded image:

Improved Handling of Unsupported Features

In Excel Services 2007, if a file contained an unsupported feature, Excel Services would not be able to open the file at all. This was a frustrating point for customers, as the unsupported feature was often something that the customer didn’t care about in the context of rendering in Excel Services. For example, a workbook may have a cell comment, which is unsupported, on Sheet3, but the workbook, when rendered via Excel Services, was only meant to show the chart on Sheet1. In this scenario, the only recourse for the customer was to remove the unsupported feature.

In the SharePoint 2010 release of Excel Services, a lot of work went into bringing support for new features as well the other investment areas that were discussed in the Excel Services overview post. With every release we narrow the functionality gap between Excel and Excel Services and reduce the number of unsupported features, but even in this new release, unsupported features still exist. To help users work with this limitation, Excel Services will simply “ignore” certain unsupported features. In other words, rather than blocking the entire file from loading, Excel Services will load the file just fine, you just won’t see the features that Excel Services doesn’t support.

So which features fall into this bucket? Here are the features that will not prevent Excel Services from loading a file:

Cell comments
Formula references to external books
Query Tables (also known as external data ranges)
VBA
Anything using OfficeArt technology, such as Shapes, WordArt, SmartArt, Org Chart, Diagrams, Signature Lines, Ink Annotations, etc.

A couple notes about the above list. These features continue to be unsupported, so that means they don’t render, execute, or work in any way like they do on the client. Most of the features in the above list will not render at all in Excel Services. For example, if there’s a shape near cell A1 when viewed in the client, you will see no shape at all when viewed on the server. Other features, like formula references and query tables, show you values that were last refreshed in the client. In other words, the values in the cells are still there, but you cannot update them in any way. Lastly, VBA code will not execute on the server.

One additional note about VBA. Excel Services 2007 didn’t support loading *.xlsm files at all because such files are meant to contain macros and files with macros would not load. Now that the SharePoint 2010 version of Excel Services knows how to ignore VBA macros, I am happy to say that also means *.xlsm files can now be loaded in Excel Services.

Viewing a File with Ignored Unsupported Features

You may be wondering, if Excel Services will load files and not render certain unsupported features, how do I know if the file I’m viewing is missing features? Excel Services will display a notification above the sheet that the file has missing features.

This is your first clue that the file is rendering different than Excel. If you’d like to learn more about which unsupported features Excel Services found in the file, click the “Details…” button.

What About Other Unsupported Features?

All other unsupported features will continue to behave as they do in Excel Services 2007. That is, Excel Services will block loading of the file if it detects the existence of one of these features.

This help topic for the 2007 release covers the detailed list (just ignore any mention of images, as I already mentioned those are now supported).

Summary

I hope that the changes we’ve made to how we handle unsupported features will alleviate many of the pain points our customers experience when rendering spreadsheet files with Excel Services. I would love to hear your feedback about the work we’ve done, as well as any thoughts you have on which unsupported features you’d like to see supported in a future release.

Deploying Office Web Apps in the Enterprise

Joseph Chirilov — Wed, 18 Nov 2009 18:58:00 GMT

Following on the heels of the Office 2010 beta availability announcement, the Office Web Apps blog has a new post discussing deploying office web apps in the enterprise. Have a read if you're looking to test drive the beta version of Office Web Apps.

Announcing Office 2010 and PowerPivot Beta Availability

Joseph Chirilov — Wed, 18 Nov 2009 17:22:00 GMT

From the Office 2010 Engineering blog:

Today is an exciting day! At PDC we announced the availability of the public betas of Microsoft Office 2010, SharePoint Server 2010, Visio 2010, Project 2010 and Office Web Apps for business customers. If you’d like to be one of the millions of people who try, test and give feedback on the latest and greatest, you can download the betas at www.microsoft.com/2010.

We also announced that Microsoft Office Mobile 2010 beta is available now too, and you can download it through the Windows Mobile Marketplace for Windows Mobile 6.5 phones.

The final release of Office 2010 will debut next year, but we’re excited to allow everyone to start using the new features and tools that will help you collaborate, connect and work better together with others across the PC, mobile phone and browser.

Also, we've talked a lot about PowerPivot (previously known as Gemini) on this blog, and I'm excited to let you know that we've announced the beta availability of PowerPivot today as well. Check out the details about PowerPivot here. Download link is here.

I look forward to hearing your feedback on both Excel 2010 and PowerPivot!

Easily manage defined names in Microsoft Excel

FredK — Tue, 17 Nov 2009 23:35:19 GMT

Today’s author is Jan Karel Pieterse, an Excel MVP. You can find more useful tips from Jan Karel on his website: http://www.jkp-ads.com/. This post informs you about Name Manager, a free utility that helps you manage defined names in your workbooks.

If you need a free utility to manage defined names in your workbooks, this one is a must-have. List all names in your active workbook. Filter them using 13 filters including "With external references," "With errors," "Hidden," and "Visible." Show only names that contain a substring. Show only names unused in worksheet cells. Edit them in a simple dialog box or edit them in a list and update all names at once. Supports the 2007 Office system.

To download Name Manager, visit www.jkp-ads.com/officemarketplacenm-en.asp.

For information about how to define names, see Define and use names in formulas.

Excel Services in SharePoint 2010 Administration Improvements

Joseph Chirilov — Tue, 17 Nov 2009 05:37:00 GMT

Thanks to John Campbell for putting together this post.

Ongoing management is key to any successful server product’s deployment. It can be challenging to figure out the right initial combination of settings, and to know how to further change those settings when problems arise. With that in mind, I have put this blog article together to go into what’s new in the Excel Services administration space.

First Things First: SharePoint Administration and Service Applications

Excel Services is a “Service Application” in SharePoint. Service Applications are the replacement for what used to be known as a Shared Service Provider (or SSP).

A service application is basically a global entity in the farm that performs some useful piece of functionality. In our case, Excel Services provides all the ‘Excel’ goodness in the browser that you see in SharePoint. The big things worth knowing about service applications are:

You can delegate administration of them – so the central administrator can find the Excel Service administrator and give that person rights to administer that service and nothing else.
Although in general you can have multiple service applications in a farm, Excel Services is really geared with the idea of a single service application per farm in mind. The reason for this is because only the default Excel Service application will respond to requests.
You can configure which physical machines in the farm run certain service applications and which don’t. So you can dedicate certain machines to be used only by certain service applications. This can be helpful when planning your deployments.
Unlike the old flavor of ‘Shared Services’ in 2007, you can choose which service applications to run independently, and you aren’t forced to provision and manage a separate database for them all.
They all support PowerShell! And now that the topic of PowerShell has come up, let’s talk about PowerShell…

PowerShell Support

Excel Services fully supports PowerShell in the 2010 release. PowerShell is the product that provides a simple command line style scripting interface, but it can be used to go much farther than that since it supports .Net and can be used for more advanced things like calling OM directly. PowerShell scripts are also reusable – i.e. you write it once, and can run it anytime in the future. So scripting setup, or performing some regular maintenance task, etc and reusing it when the need arises is a snap.

Commands you perform in PowerShell are done using “command-lets” or cmdlets for short. All the Excel Services PowerShell cmdlets are fairly simple in nature and are all flavors of Get, Set, New, and Remove. They basically all boil down to the action of getting some object (like an Excel Service application object, or a Trusted Location object from the trusted locations list) and modifying settings on it. To read the settings you use Get-object, to change settings you use Set-object. If the object is one of many in a list (like trusted locations or trusted UDFs), you use New-object to make a new entry in the list, or Remove-object to get rid of one. Let’s take a look at a couple of quick examples to illustrate what I mean.

At the highest level, there are general, global, settings for Excel Services. What if you want to see what all the setting values are? In the 2007 release this actually wasn’t possible using stsadm. With PowerShell you can use:

Get-SPExcelServiceApplication

That will show you the ‘basic’ settings for the service application (name, type, and Id). If you want to see all the settings and their values, then you send the object (via piping) to a different cmdlet to format it as a list:

Get-SPExcelServiceApplication | Format-list *

Since I’m not specifying a name of a specific application, it will get every Excel Service running in the farm, and for each one display all its settings.

Now suppose I want to change how many sessions a user is allowed to have on a single back end server machine running Excel Services. Here is the PowerShell to do that:

Set-SPExcelServiceApplication MyExcelService –SessionsPerUserMax 50

I call the Set cmdlet on the global Excel Services service application cmdlet (SPExcelServiceApplication), I specify which Excel Service application I am talking about in case there is more than one (in this case I want the one named MyExcelService), and then I instruct it to set the SessionsPerUserMax property to the value of 50.

Let’s look at a more advanced example.

A common request from the 2007 release was to look at all the trusted locations, and when some particular value was less than some amount, set that value to something new. (See the next section for an overview of trusted locations.) This wasn’t possible in 2007, but is pretty simple in 2010.

The following example will look at every trusted location for every Excel Service application running in the farm, and if external data refresh is allowed using embedded connections or connections from a data connection library (DCL), it makes it more secure via only allowing connections that are stored in a DCL.

Get-SPExcelServiceApplication | Get-SPExcelFileLocation | where { $_.ExternalDataAllowed –eq “DclAndEmbedded”} | Set-SPExcelFileLocation –ExternalDataAllowed Dcl

Notice the use of the “|” or the pipe operator. It just takes whatever the output from one cmdlet is, and sends it as the input to the next cmdlet. This is what makes it so easy to write a cmdlet that ‘loops’ over all the Excel Services in the farm, and for each one get all the trusted locations. The “where” clause just filters down the set of trusted locations to only the ones that match the logical criteria we are looking for, and then sends those results on to the next Set cmdlet to change the actual settings of that trusted location.

If you are interested in going a little deeper on PowerShell for SharePoint in general, check out the SharePoint team blog.

Default Settings for Trusted Locations

Excel Services has global settings, and also has trusted location level settings. Trusted locations are essentially just file paths (to a site, document library, portal, UNC share, etc) to places where the administrator has explicitly allowed workbook files to be loaded from. Excel Services will ONLY load workbooks that are stored in trusted locations. Excel Services can have many trusted locations, and each trusted location has a bunch of settings that dictate how the workbook can be used when it is loaded on the server. Simple example: by creating two trusted locations with different settings, you could specify that workbooks loaded from an externally facing site can only be up to 1MB in size, but workbooks from an internal site may be up to 15MB.

In Excel Services 2007 the administrator was forced to define at least one trusted location because by default in 2007, there were no trusted locations. And trusting something like, “all workbooks from anywhere in the SharePoint farm,” was non obvious.

By default in 2010 we load workbooks from anywhere in the farm, and we even allow data refresh (with warnings shown) by default. So no more trying to figure out what the settings should be, what level you should define them at, etc – it all works out of the box. Most administrators won’t need to make any changes here, but for those that do, they still have all the power and flexibility they had in 2007.

Tip – if you are trying to find an easy way to trust the entire farm in the 2007 release, you can add a trusted location as follows to achieve this:

Address: http://
Make sure the trust children checkbox is selected
Make sure the type is SharePoint

External Data – Better Error Messaging

Anyone that configured external data connectivity in 2007 probably has memories of struggling to figure out where and why things weren’t working. A lot can go into getting a back end application server running Excel Services connected to a data source. For a better treatment of the subject in 2007, including background, security issues, and step by step instructions with screen shots, see this whitepaper I wrote.

The thing worth calling out in this blog article is that the error messages in this space have gotten much better. Excel Services now has error messaging with specific information about what/where the external data failure is being caused. In most of the common cases, these errors should help you quickly pinpoint what needs to be updated to get connectivity working.

For the security minded administrators, you can explicitly turn these more detailed error messages off and just show something generic instead. There is a setting to enable granular external data error messages on each trusted location.

We hope you find the changes we have made in the administration space useful for Excel Services. We think we have made some of the common administration tasks easier – initial settings config, scripting, and troubleshooting external data. As always, we would love to hear your feedback about how we can continue to improve. This post only scratched the surface and was by no means a comprehensive guide to all things administration in Excel Services or in SharePoint. To learn more about SharePoint in general, see the SharePoint team blog.

Find Combinations

FredK — Thu, 12 Nov 2009 22:11:17 GMT

Today’s author is Bill Seddon from Lyquidity Solutions, who informs us about a free tool for Excel users that allows you to find combinations of numbers that total to a selected value. For more information and a video, see http://www.lyquidity.com/findcombinations.

Imagine you are an auditor or cash accountant and need to reconcile cash balances to their invoices. Which combination of values makes up each cash value? Not surprisingly, the Find Combinations add-in has been popular with the audit firms.

Excel Services in SharePoint 2010 Dashboard Improvements

Joseph Chirilov — Thu, 12 Nov 2009 03:34:00 GMT

Thanks to Dan Parish for putting together this post.

One of the great things about Excel Services is the Excel Web Access (EWA) web part. This web part allows you to render entire workbooks, or just portions of a workbook (for example a chart or a Table) in a SharePoint dashboard page. For a high level overview of what you can do with the EWA in SharePoint 2007, take a look at some of our existing blog entries:

We have made many improvements to the EWA in SharePoint 2010, and they can be lumped into three major buckets:

Support for more existing, as well as new Excel 2010 Features
Making the user experience even more familiar to users of Excel
Support for additional part-to-part scenarios

#1 is very broad and so has been and will continue to be covered by other blog entries. This entry will specifically deal with improvements to the dashboarding experience: numbers 2 and 3.

Making the user experience even more familiar to users of Excel

In SharePoint 2007, the EWA’s rendering of workbooks was virtually identical to that of the Excel client’s. However, actually using the EWA wasn’t always the same. While all the interactive functionality (sorting, filtering, drilling up/down in a PivotTable) worked the same as Excel, some fundamental things like scrolling and periodic data refresh worked quite differently. In SharePoint 2010, we’ve addressed all of these issues by making the EWA AJAX based, which allows for more user interaction to happen within the browser itself, thereby allowing for a more fluid, Excel-like experience. Specifically, the following areas have been revamped:

Scrolling
External data periodic refresh
New for 2010, the ability to type into the grid (when the Office Web Apps are installed)
Miscellaneous other improvements

Scrolling

In SharePoint 2007, the EWA rendered the grid in ‘pages’, which were by default 20 columns by 75 rows. If you had more data than that you had two options:

You could increase the number of rows and columns per ‘page’ using the web part properties
Your users could use the ‘paging buttons’ located at the top right of the EWA

In SharePoint 2010, we got rid of this model and made our scrolling work just like you’d expect: like Excel’s. The paging buttons are no more, and since the grid isn’t rendered in ‘pages’ anymore, the associated web part properties have also been removed.

In the EWA in SharePoint 2010, you can scroll around your entire used range (and beyond) quickly and easily, whether your range is ten rows or a million. Additionally, due to how scrolling has been implemented, the size of the range of data you want to display in the EWA has no impact on the amount of time the page takes to load. The EWA always just renders what it is you are actually looking at in order to keep loading and rendering times to a minimum.

Periodic external data refresh

The EWA in SharePoint 2007 supported periodic external data refresh, however it didn’t work the same as it does in Excel. Because in the EWA in SharePoint 2007 every action (including refreshing external data) caused a postback within the EWA, when external data was refreshing users were unable to continue to view their data or continue their work. This meant that web part page authors had two choices: they could set the EWA to refresh automatically, interrupting users every time it did so, or they could have the EWA prompt the user via a special notification bar for when they wanted to refresh like so:

In SharePoint 2010, because of the new AJAX grid, we’ve removed the need to even have to make this decision. Web part page authors can still decide if they want the EWA to periodically refresh data at all, but if they choose to allow it they’ll find that there is no more web part property to choose whether or not to notify the user. This is because in SharePoint 2010, the EWA can refresh external data in the background just like the Excel client. So, whenever it’s time for new data to be fetched, it will just appear on screen without affecting the user’s workflow or asking them to make a choice. It’s all automatic and seamless, just like it was intended to be.

New for 2010, the ability to type into the grid (when the Office Web Apps are installed)

One of the most requested features for the EWA in SharePoint 2007 was to let users type into the grid. Parameters, while good for some things, aren’t ideal when users need to enter many values or when the spreadsheet is authored in a way that encourages users to enter data into specific regions.

So, for 2010, we’ve added this capability as well. If the Office Web Apps are installed, you’ll see a new web part property in the Excel Web Access web part tool pane called ‘Typing and formula entry’. When selected, users will be able to type and enter formulas directly in the EWA.

This functionality allows for the creation of rich, interactive, what-if models using the EWA, and just like before, these changes are per-user, and will never affect the underlying workbook.

You may be wondering if there is a way to have the EWA save changes to the underlying workbook, but the answer is no. The EWA is all about allowing users to consume and explore models created in workbooks, while preserving the underlying workbook itself. Stay tuned for future posts however on ways to accomplish something similar once you have the Excel Web App installed using our new JavaScript Object Model.

Miscellaneous other improvements

There are a whole host of other improvements to the user experience within the EWA. Some of the most requested features that have been added include:

The ability to move around the grid using the keyboard
The ability to select multiple cells, rows or columns
The ability to copy from the EWA and paste into another application
The ability to resize rows and columns
Support for many Excel keyboard shortcuts
And more!

While we’ve kept the rendering just as good (and in many cases made it better) as in SharePoint 2007, we’ve done a lot of work this release to really make the overall experience of using the EWA more familiar, while at the same time opening up new scenarios that simply weren’t possible before.

Support for additional part-to-part scenarios

In SharePoint 2007, the EWA could connect with virtually all SharePoint web parts (as well as custom built web parts) using the IFilterValues web part interface. This worked great in many scenarios, as this interface allows a web part to send a value (or set of values) into a single parameter in the EWA. However, we frequently got asked if there was any way to send multiple values from a single web part into multiple parameters in the EWA, and the answer was unfortunately no.

In SharePoint 2010, we’ve removed this limitation by supporting the IWebPartParameters interface. This interface is also supported by virtually all SharePoint web parts, and is also documented on MSDN to allow for customers to build their own web parts using it as well. This interface allows one web part to send multiple values into multiple parameters in the EWA.

To setup a connection using the multiple-to-multiple capabilities of this interface, you will need to use SharePoint Designer, and then you can follow these simple steps:

Create your web part page either on the server using SharePoint, or directly in SharePoint Designer, including both the EWA web part and the web part you would like to have send values into the EWA
Open the web part page in SharePoint Designer
Right-click on the EWA and select ‘Add Connection’
In the Web Part Connections Wizard that will appear, select ‘Get Values for Multiple Parameters From’
Select the source web part
Map the values from the source web part to your defined parameters in the EWA
You’re done!

Remember that in order for the EWA to accept values, you must first define parameters. See the Using Parameters In Dashboards blog entry for details on how to do that.

Conclusion

As you can see, we’ve greatly expanded the capabilities of the Excel Web Access web part in SharePoint 2010. It’s now easier to use, more Excel-like in how it functions, and it opens up new dashboarding possibilities with its support for typing and its support for the IWebPartParameters interface.

Please take a look at some of the previous blog entries related to sparklines and slicers for some of the new functionality offered in the Excel client that is also supported in the EWA, and stay tuned for more blog entries detailing the improved support for existing Excel functionality as well.

If you have any specific scenarios you are wondering if we have added support for, please ask your question in the Comments section and I’ll be sure to respond.

New Posts From One of the Principal Developers Behind Excel Services

Joseph Chirilov — Wed, 11 Nov 2009 03:01:00 GMT

One of our most senior developers on Excel Services, Shahar Prish, is busy writing posts in his blog on the new programmability features in the 2010 version of Excel Services. The first set of posts talk about REST and moving forward he will expand to the new JavaScript OM we added this release. Here are the links, if you care at all about building custom solutions for Excel and Excel Services they are a great read:

General posts about REST:

Welcome to the new Excel Services

So what does REST on Excel Services look like???

Discovery via the Excel Services REST APIs

Getting ranges via Excel Services REST as well as Charts and Discovery

Excel Services REST APIs – the basics

Advanced Excel Services REST API capabilities – passing parameters to a spreadsheet

How to seamlessly embed data from Excel Services spreadsheets into Word

The Excel Services Windows Gadget:

Introducing the Excel Services Windows 7 Gadget

Showing Excel ranges in the Excel Services Gadget

Bringing it all back home – using advanced REST functionality with the Excel Services Gadget

And the blog is starting to show how to actually code the gadget:

Coding the Excel Services Windows 7 Gadget – Part 1 - Settings

Excel Services in SharePoint 2010 REST API Examples

Joseph Chirilov — Tue, 10 Nov 2009 07:29:00 GMT

Thanks to Christian Stich for putting together this series on the REST API.

In this final installment on the REST API, we’ll walk through a couple examples of using the REST API to embed spreadsheet data in new and interesting ways.

Embedding a ‘Live’ Chart on a SharePoint Wiki Page.

For this example we are embedding an Excel scatter chart on a SharePoint wiki page. The scatter chart works like an analog clock, so that you can see that the data returned via REST is dynamic, and the workbook containing the chart and the logic is attached to this blog post.

First upload the Clock.xlsx workbook to a SharePoint document library. (the workbook is included in the archive folder that is attached to this post)

Let’s assume that the workbook has been uploaded to the following location:

http://contoso/Shared%20Documents/Clock.xlsx.
Then craft the REST API URI to the scatter chart named Clock

http://contoso/_vti_bin/ExcelRest.aspx/Shared%20Documents/Clock.xlsx/Model/Charts('Clock')

You might want to post the URI into a browser’s address bar to verify that you can access the chart before proceeding with the next steps.
Create a SharePoint Wiki page.
Next, start editing the wiki page by clicking on ‘Edit Page’. Since we are inserting a chart which the REST API returns as a PNG image file click on the ‘Insert’ tab on the ribbon, then click on the ‘Image’ icon and then select ‘From Address’ from the dropdown box.
Paste the URI that you have created earlier into ‘Address’ field.
Finally, ‘Stop Editing’ the page

We see the clock when the wiki page reloads.

And when we reload the wiki page again, the scatter chart representing the analog clock will be retrieved again using the REST API – and will have been updated with the new time – showcasing the dynamic and live nature of Excel Services REST API calls.

A more business focused scenario could include a chart on a wiki page that shows the latest sales figures for a division of a company which are retrieved by Excel Services from a SQL Server database or Analysis Services cube when the wiki page is opened (or refreshed) by a user.

Inserting a Chart in a Word Document Using the Excel Services REST API.

Similarly, we can use the Excel Services REST API to insert live charts in Word and PowerPoint documents.

In Microsoft Word, select the ‘Insert’ tab on the ribbon, then click on the ‘Quick Parts’ icon, followed by selecting ‘Field’.

Then select ‘IncludePicture’ and paste the REST URI for displaying the RevenueChart from the Tax.xlsx workbook

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)

into the ‘Filename or URL field’. Also, select ‘Data not stored with document’ in the ‘Field options’ column – this results in Word refreshing the chart (reflecting potentially updated numbers) each time the document is opened.

Thus, we have created a Word document that contains a live and up-to-date Excel Services chart. If the data in the workbook (which itself can come from an external source, such as a SQL data base or Analysis Services Cube) is updated, so will the chart in the Word document each time the document is re-opened or when the document is refreshed (by pressing the F9 function key).

Building a Mash Up with Bing Maps and the Excel Services REST API.

Bing Maps provides an SDK that enables developers to determine the location of a mouse click on the map and to get the address corresponding to this location. In this demo, the (U.S.) state corresponding to the click location is extracted from the address. Then an Excel Services REST URI is created that requests a chart with the census rankings of that state by setting the state’s name/abbreviation into the Excel Workbook.

Clicking on the city of Seattle brings up the Census Rankings for Washington State.

Similarly, clicking on the city of Houston brings up the Census Rankings for the State of Texas.

The entire code required to load the Excel Services Chart with the Census Rankings for each state is:

document.getElementById('resultDiv').innerHTML = "<img src='http://contoso/_vti_bin/ExcelRest.aspx/Shared%20Documents/StateRankings.xlsx/Model/Charts(%27Report%27)?Ranges(%27State%27)="+s+"'/>";

We assemble the REST API URI string by taking the URL to the workbook’s location and setting the range ‘State’ to the JavaScript variable ‘s’ which contains the state’s name/abbreviation.

The entire JavaScript code (including the code to get the location from Bing Maps) and the workbook for this demo are included in the archive folder that is attached to this article.

Summary

The Excel Services REST API is a powerful yet very easy to use means of embedding Excel Services content on web pages and for creating mash-up applications. It enables users to retrieve image, HTML and Atom feed representations of items in Excel workbooks and modifying those by setting values into the workbook. The REST API also leverages the other capabilities of Excel Services, such as external data connections and user defined functions which can be used to fetch up-to-date values from external sources, which can then be retrieved, displayed or otherwise consumed by simply specifying a REST URI.

If you’d like to read more about REST, Shahar Prish, a developer on the Excel Services team who worked on the REST feature, has written a series of blog posts about REST on his blog.

I look forward to your feedback on this feature.

Excel Services in SharePoint 2010 REST API Syntax

Joseph Chirilov — Fri, 06 Nov 2009 05:08:00 GMT

Thanks to Christian Stich for putting together this series on the REST API.

As we saw in the previous post, using the Excel Services REST API is as simple as specifying a URI (Uniform Resource Identifier) in your web browser. In this post we’ll walk through the details of the URI syntax.

We start out with a simple Excel workbook stored on a SharePoint 2010 server at the following URL:

http://contoso/Finance/Shared%20Documents/Tax.xlsx

This example workbook contains two named ranges, a chart, a table and a PivotTable.

In order to create a URI that can be used to access the REST API we insert _vti_bin/ExcelRest.aspx/ in the above URL behind the site part (in this case /Finance).

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx

Discovering Items in a Workbook

Next we add /Model behind the filename (in this case /Tax.xlsx)

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model

We now have a URI that can be used to discover the items in the workbook – the REST API returns an ATOM feed that contains the types of items that are accessible – currently ranges, charts, tables and PivotTables are supported.

Note: In the case where the workbook resides in the root site of the SharePoint server then you would insert the _vti_bin/ExcelRest.aspx/ behind the server name.

http://contoso/Shared%20Documents/Tax.xlsx

becomes…

http://contoso/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model

Retrieving Items in a Workbook

We can get a list of the named ranges in the workbook by simply appending /Ranges to the previous URI or you can click the link for Ranges that was returned in the previous example.

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges

The REST API returns an ATOM feed that contains the named ranges in the workbook – this workbook contains two named ranges: TaxRate and Revenue.

We can also get also get an HTML representation of a range by specifying the range using /Ranges(‘range name’) and by adding ?$format=HTML.

To get the HTML representation of the name range Revenue we specify the following URI:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges(‘Revenue’)?$format=HTML

Discovering and accessing tables, PivotTables and charts is similar to discovering and accessing ranges as shown above.

Tables:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Tables

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Tables(‘RevenueTable’)?$format=html

PivotTables:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/PivotTables

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/PivotTables(‘PivotTable’)?$format=html

Charts:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?$format=image

Supported REST API Return Formats

Notice in the previous paragraph that we added a query string parameter to the URI in the previous examples where we were accessing the actual items. This query string parameter is used to specify the format that the REST API should return. The currently supported formats are:

html
atom
image
workbook

When ?$format=html is specified the REST API returns an HTML representation of the item that can be displayed by the web browser.

When ?$format=atom is specified the REST API returns an ATOM feed representation of the item.

When ?$format=image is specified the REST API returns an image file (at this time the format is always PNG).

I’ll cover the ?$format=atom return format in a future post on the REST API. At that time we will also address the differences between the ATOM feeds for /Ranges, /Tables and /PivotTables.

When ?$format=workbook is specified the REST API returns the workbook which can then be opened in Excel or saved. The format of the workbook being returned matches the format of the original file – if the original file is in .xlsx format, then the workbook being returned will be in .xlsx format; if the original file is in .xlsb format, then the workbook being returned will be in .xlsb format. Same for .xlsm format.

Which Requests Support Which Formats?

Not all formats are supported with all items. Moreover, different types of REST API requests have different default values. For example /Charts(‘chart name’) default return format is image - this means that you don’t have to specify ?$format=image as part of the URI. Similarly, with /Ranges(‘range name’) you can omit ?$format=html if that is the format you would like to be returned.

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)

is equivalent to

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?$format=image

Both URIs return an image in PNG format.

Below is a matrix that shows the supported formats for different types of REST API requests. Specifying ?$format=… allow you to override the default return format with another supported format.

What About Normal Ranges?

The example above showed how to access a named range. It is also possible to access arbitrary, non-named, ranges using A1-style notation. The following URIs show how it’s done for accessing single cell ranges and multiple cell ranges.

To get an HTML representation of the content of cell A1 on Sheet1:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges(‘Sheet1!A1’)?$format=HTML

To get an HTML representation of the content of the range A1:D4 on Sheet2:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Ranges(‘Sheet2!A1|D4’)?$format=HTML

NOTE: you need to replace the colon in the A1 style notation for ranges with a pipe character when used with the REST API -> the range A1:D4 is entered as A1|D4

Inserting Values

The Excel Services REST API provides a means to change values in the workbook. These changes only affect the values, HTML rendering info or charts returned by the REST API for that particular request. These changes are NOT saved back to the workbook, nor do they affect other REST API or Excel Web Access browser sessions.

Setting values is simple and can be done by specifying single cells using A1 style notation, or by specifying a single cell named range or a parameter.

In the following example, we have a workbook with a named range called “Tax Rate”, which is currently set to 10%.

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)

results in the original chart being returned

Changing the Tax Rate to 50% in the workbook by adding ?Ranges(‘TaxRate’)=0.50

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘TaxRate’)=0.50

results in an updated chart being returned:

We could also have used A1 style notation to specify the cell to be changed (‘TaxRate’ has the A1 style address ‘Sheet1!B1’)

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘Sheet1!B1’)=0.50

It is also possible to set multiple values into different cells. Additional query string parameters are separated by the ampersand & character.

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘TaxRate’)=0.50&Ranges(‘FiscalYear’)=2008

And you can combine this with specifying the return format – the order of the query string parameters does not matter. For example:

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘TaxRate’)=0.50&Ranges(‘FiscalYear’)=2008&$format=html

and

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?Ranges(‘FiscalYear’)=2008&$format=html&Ranges(‘TaxRate’)=0.50

and

http://contoso/Finance/_vti_bin/ExcelRest.aspx/Shared%20Documents/Tax.xlsx/Model/Charts(‘RevenueChart’)?$format=html&Ranges(‘FiscalYear’)=2008&Ranges(‘TaxRate’)=0.50

are all equivalent and return the same result.

More To Come

This concludes our walk through the REST API syntax. You should now have enough knowledge to start building REST-based solutions with Excel Services. In my next post I’ll showcase a few simple scenarios that you can quickly build yourself.