Office Developer Blog

Introducing WOPI

S. D. Oliver — Thu, 21 Mar 2013 16:43:00 GMT

This blog post describes how to create a custom WOPI host. A WOPI host is document storage location that can connect to Office Web Apps Server to open Office documents in the browser. When the WOPI host is configured to use Office Web Apps Server, users are able to view and edit documents stored on the WOPI host by using Office Web Apps. Tyler Butler, Program Manager, Office Shared Experiences team, authored today’s post.

One of the great things about the Office Web Apps is that they let people work with their documents anywhere, on any computer. It turns out that there are lots of documents in lots of different places. For example, consider Outlook.com, or more generally, web-based email. You probably get documents sent to you via email every so often, and you probably want to open those documents to read them. One option is to download the file and open it in an application on your local computer. But if you're really just wanting to quickly check out the contents of the document, wouldn't it be easier if you could just click the document and have it open immediately in the browser? Wouldn't it be cool if that worked regardless of what software you had installed on your local computer? It could work when you're traveling and using an internet cafe computer, when you're using a friend's computer, or when you're at a conference and using a shared computer there.

With the most recent release of the Office Web Apps, developers can enable such scenarios in their apps directly by implementing the Web Application Open Platform Interface (WOPI). WOPI provides web-based services a way to view and edit documents in the Office Web Apps, with all the high-fidelity and richness that you expect from an Office document. While email attachments are a great example, there are plenty of other places where documents are used on the web -- bank statements, file-synchronization services like SkyDrive and Dropbox, etc. -- and there are compelling ways developers can leverage WOPI to treat those documents as something more than just a file that users download.

So if you’re a developer, this post is for you. Simply put, WOPI is the glue that connects the web apps to your documents, and it's an interface that you can implement yourself -- to dazzling effect. In this post series I'll talk about what WOPI is, walk through the basics of implementing it, and show you an example implementation.

In addition to this post, WOPI is documented in the [MS-WOPI] protocol document. That document is the authoritative documentation on the interface.

Fundamentals

To better understand what WOPI is conceptually, consider this: Have you ever opened a document on your computer by double-clicking the file and watch it open in Word? When you did that, you signaled the operating system that you wanted to open the file, so the OS figured out what application was associated with that file type, then passed the file over to the application to handle. That's a very basic description of the process, but conceptually that's what happens.

WOPI provides similar semantics for web applications, but the web is a little different than your local hard drive, so the process of opening the file is also a little different. In my simplified example above, the document was stored on your hard drive, and the operating system handled passing the file off to the application to open. In the scenarios for which WOPI was designed, though, the document is stored somewhere on the web. We call those document storage locations WOPI hosts or WOPI servers. This term will become a little clearer in just a moment, but think of a WOPI host as a service like SkyDrive. It's a place where you can put your documents or other files and make them accessible on the web.

If a WOPI host is a place where your files are stored, then what about the actual applications that open those files? We unsurprisingly call those WOPI applications or WOPI clients; the Word/Excel/PowerPoint/OneNote web apps are all examples of WOPI applications. These applications support various different actions, such as view or edit, and these actions can apply to different file types.

Going back to my original example of the document on your hard drive, the WOPI host is kind of like the hard drive -- but a little smarter. It stores the documents. The WOPI application is the app capable of performing an action -- doing something, in other words -- on those files, and WOPI is the interface that those two entities use to talk to one another. If you're a service or application that stores documents, then you can implement WOPI, making yourself a WOPI host, and WOPI applications such as the Office Web Apps can then consume the documents you're storing. Pretty compelling, huh? The rest of this post will go into the details of the interface.

WOPI itself is more or less a callback interface that operates over REST. As a WOPI host, you expose a number of endpoints, in the form of URLs, and then you load a WOPI application, passing it the URL to your endpoint. The WOPI application then calls your endpoint -- again, this is REST, so the application issues an HTTP request to the URL you passed it earlier -- and you respond appropriately based on the information that the WOPI application sent you via its request. WOPI defines a number of different endpoints that you can expose. Many of these are optional and necessary only if you wish to enable things like editing. At a minimum you'll need to implement endpoints for CheckFileInfo and GetFile, which will enable the simplest WOPI action, view. We'll talk about each of those endpoints in a moment.

The overall flow of a WOPI conversation looks like this:

Figure 1. WOPI conversation flow

Host Requirements

As you can see in the diagram, as a WOPI host you need to provide some information about the files you have as well as the file itself. Since WOPI is a REST-based callback interface you provide that information via specific URLs. In addition, you need to provide ways to identify files, users and permissions. Essentially, you're providing a small REST API around your files, which a WOPI application will then use to work with those files. Luckily, this is simpler than it might seem at first. The basic things you need to provide as a WOPI host are as follows:

1. File IDs

The files you're storing must have a unique identifier that you can use to find the file when the WOPI application asks you for it. This ID is passed in URLs, so it should be a URL-safe string.

2. Access tokens

You need to provide access tokens that represent users and their permissions within your system. The WOPI application doesn't know what permissions a user has; as the storer of the file, you, the WOPI host, are the authority on that. Thus, you need to provide a token that the WOPI application will then pass back to you. When you get the token, you need to validate it and respond appropriately if the token is invalid. While not strictly required, the WOPI spec recommends that the token be scoped to a single user and document and expire after a certain period of time. The specific format and recommendations about how WOPI hosts should handle access tokens is covered in [MS-WOPI] section 2.2.2.

3. URLs for file access

WOPI requires that a WOPI host expose at least two specific URLs: one to retrieve information about and manipulate files, and a second to retrieve and potentially update the contents of a file. (There are also some additional optional endpoints for manipulating folders and their contents, but those are required only for certain actions.) The URLs have some requirements around their structure which is covered in detail in [MS-WOPI] section 3.3.5.

File IDs are pretty straightforward; you probably already have them. Access tokens might be a little trickier but they're similarly straightforward to implement if you need to. Providing URLs for file access is probably the requirement most likely to be a minor hurdle, especially if you're not currently using a REST or REST-like architecture to expose your files. Fortunately, WOPI's needs are relatively small, and implementing REST endpoints boils down to exposing some URLs, so it's not that difficult in the end.

Let's talk about the two core URL endpoints that you'll need to expose in order to implement view, the simplest WOPI action.

CheckFileInfo

GetFile

Loading a WOPI Application

In order to actually view one of the files that we've exposed, we need to tell the WOPI application, "Please load the file with this ID using this access token." We do that by loading an action-specific URL on the WOPI application server. For example, a URL to view a Word document might look like this:

http://wopi-app-server.contoso.com/wv/wordviewerframe.aspx?WOPISrc=
http%3A%2F%2Fmy-wopi-host%2Flocal%2Fwopi
%2Ffiles%2F1-Sample%2520Document.docx&access_token=
dc172034-c6f9-4a43-bc3f-d80dd93c1de1

NOTE: Throughout this blog post we wrap long URLs on to more than one line in order to fit them into the viewing area.

We'll talk about how we actually determine what the URL for a given action is in just a moment, but for now let's just examine the query string parameters. You can see that we pass in two query string parameters, WOPISrc and access_token. We've talked about access_token already; it's the token that represents the user requesting the file. WOPISrc, on the other hand, is new. The parameter is the "WOPI source" of the file being loaded. In other words, this parameter is how we tell the WOPI application how to find the file that we want to view. The parameter is URL encoded, so let's decode it so we can see what it looks like:

http://my-wopi-host/local/wopi/files/1-Sample%20Document.docx

Hmmm, that URL looks an awful lot like the CheckFileInfo URL. In fact, it is the CheckFileInfo URL for the file (without the access token, of course). Using that URL, the WOPI application can determine the URLs for GetFile or other calls that it may need to make. Precise specifications for the WOPISrc and access_token parameters can be found in the [MS-WOPI] document section 3.1.5.1.1.2.3.3.

So, to recap, in order to load a WOPI application, we load a URL corresponding to the WOPI action we want to perform, pass the WOPISrc and access_token parameters, and the application calls us back, passing us the file ID and access tokens as needed. We validate the access tokens and respond to the requests made by the WOPI application, and it loads our document. Cool!

There's still one missing piece though. How do we know what the URLs are for a given WOPI action?

WOPI Discovery

As I mentioned, since WOPI is a REST-based interface, the communication between the host and the app is all done via HTTP requests to specific URLs. However, how do you know what the URLs to use are? Simple -- you ask the application server itself! Every WOPI application server exposes a single URL, called the discovery URL, that provides an XML document describing the actions, document types, and URLs it understands. As a WOPI host, you retrieve this XML document and use it to determine the URLs you need to talk to in order to perform actions in addition to what actions are supported by the application server and what file types those actions apply to. We refer to this process as WOPI discovery, and it's meant to be a one-time thing. It's easiest to think of discovery as a configuration step; when you are configuring your WOPI host to talk to a new WOPI application, you'll run discovery. As a WOPI host, you'll retrieve the discovery XML once, process it, then you shouldn't need it again.

The discovery XML looks like this (the URL in urlsrc is shown on 2 lines in order to fit on the page):

<?xml version="1.0" encoding="utf-8"?>
<wopi-discovery>
    <net-zone name="external-https">
        <app name="Word" favIconUrl="https://wopi-app-server.contoso.com/wv/
             resources/1033/FavIcon_Word.ico"
             checkLicense="true">
            <action name="view" ext="doc" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="view" ext="docm" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="view" ext="docx" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="view" ext="dot" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="view" ext="dotm" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="view" ext="dotx" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="view" ext="odt" default="true"
                    urlsrc="https://wopi-app-server.contoso.com/
                    wv/wordviewerframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="edit" ext="docm" requires="locks,cobalt,update"
                    urlsrc="https://wopi-app-server.contoso.com/
                    we/wordeditorframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="edit" ext="docx" requires="locks,cobalt,update"
                    urlsrc="https://wopi-app-server.contoso.com/
                    we/wordeditorframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
            <action name="edit" ext="odt" requires="locks,cobalt,update"
                    urlsrc="https://wopi-app-server.contoso.com/
                    we/wordeditorframe.aspx?
                    <ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>"/>
        </app>
    </net-zone>
</wopi-discovery>

As you can see, this example discovery XML defines an app (Word) that can perform two actions (view and edit) on several different document types, defined by their file extensions. For each of the actions, the urlsrc attribute defines the URL that should be used to invoke the action on a given file. This URL has a number of optional query string parameters that can be included, denoted by angle brackets (< and >). Precise instructions for parsing the urlsrc attribute and replacing the placeholder values, as well as the meaning of each of the placeholder values, is available in [MS-WOPI] section 3.1.5.1.1.2.3.3.

In addition to the optional parameters, you must also append the WOPISrc and access_token query string parameters that we discussed earlier to the URL in order to correctly invoke the WOPI action. Looking at the sample discovery XML above, you'll notice that the URL for the view action on the docx file extension is this:

https://wopi-app-server.contoso.com/wv/wordviewerframe.aspx
?<ui=UI_LLCC&><rs=DC_LLCC&><showpagestats=PERFSTATS&>

In our earlier example, we used this URL to load the viewer:

http://wopi-app-server.contoso.com/wv/wordviewerframe.aspx
?WOPISrc=http%3A%2F%2Fmy-wopi-host%2Flocal
%2Fwopi%2Ffiles%2F1-Sample%2520Document.docx&access_token=
dc172034-c6f9-4a43-bc3f-d80dd93c1de1

You can see that this URL is the one from the discovery XML with the optional parameters from the urlsrc removed and the required WOPISrc and access_token parameters appended.

Once you have performed WOPI discovery, you can invoke any supported action on a file by visiting the URL specified in the urlsrc parameter, assuming you have correctly transformed the URL according to the protocol specifications. When you visit the URL, the WOPI application will in turn call you back via the URL you passed to it in the WOPISrc parameter, at which point you'd respond with information about the file, the file content, etc.

Wrapping the Application URL

As a WOPI host, you would likely prefer to be able to provide your users with a URL that they could visit and see a document opened up in a WOPI application. You could just hand out the URL to the WOPI application itself, but there are a couple of problems with that. First, the URL isn't very friendly-looking; it's a bit unwieldy. Second, it's not a URL for your WOPI host, so it's potentially confusing for users. Most importantly, though, it contains an access token, which is a user-specific and time-sensitive thing. Thus, that URL isn't appropriate to share with multiple users.

There is still a way for you to provide friendly URLs, though. The way you do this is by creating a page within your WOPI host that contains an iframe that points to the WOPI application URL. For example, you could have a page with a URL like this:

http://my-wopi-host/documents/1-Sample%20Document.docx

When loaded, you'd determine the user requesting the page, issue them an access token if needed, then respond with a simple page similar to this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
        "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">

<head>
    <title>My WOPI Host</title>
    <meta content="text/html; charset=utf-8" http-equiv="Content-Type" />

    <!-- Enable IE Standards mode -->
    <meta http-equiv="X-UA-Compatible" content="IE=edge">

    <link rel="shortcut icon" href="/static/icons/favicon.ico" />

    <style type="text/css">
        #waciframe
        {
            width: 100%;
            height: 100%;
            border: none;
            position: absolute;
            top: 0;
            left: 0;
        }
    </style>
</head>
<body style="overflow: hidden;">
    <iframe id="waciframe" src="http://wopi-app-server.contoso.com/
wv/wordviewerframe.aspx?WOPISrc=http%3A%2F%2Fmy-wopi-host%2Flocal
%2Fwopi%2Ffiles%2F1-Sample%2520Document.docx
&access_token=dc172034-c6f9-4a43-bc3f-d80dd93c1de1"></iframe>
</body>
</html>

As you can see, this page is very simple. Its body only contains an iframe that points to the WOPI application URL. Because you can dynamically generate this page content, you can fill in the user's access token as needed, and users will see a URL that points to your WOPI host, not the WOPI application.

Putting It All Together

We've covered an awful lot of ground in this post, and hopefully it's become a little clearer how you can enable some pretty cool scenarios with documents on the web using WOPI and the Office Web Apps. To briefly summarize what we've covered, in order to implement WOPI you need the following things:

1. Provide unique file IDs for your files and access tokens for your users

2. Implement at least the CheckFileInfo and GetFile WOPI REST endpoints

3. Parse discovery XML to determine action URLs

4. Wrap action URLs in a page/URL within your service for a more seamless user experience

I highly recommend reading the [MS-WOPI] documentation if you're interested in learning more or are implementing the interface. That document covers the entirety of the interface in great detail, and is a great reference.

In my next post, I'll walk through a sample WOPI host implementation and we'll see more of WOPI in action.

JavaScript API object model maps updated for attachment support in mail apps!

angelgolfer — Mon, 04 Mar 2013 19:00:00 GMT

In my last post When should I choose to create a mail app versus an add-in for Outlook?, I provided some factors for you to consider if you’re trying to decide whether a mail app or add-in is more appropriate for your Outlook extension scenario. Along with that post are a couple of object model maps to illustrate the supporting JavaScript API for Office. On February 27, we released a major new update to the Office 365 services for business. This update to Office 365 includes a new set of API for mail apps to access mail attachments, and hence the object model maps have been updated on that post. At this point, this new feature is available to mail apps running on Outlook Web App accessing mailboxes on only Exchange Online. This new feature offers a mail app the capability to send a third-party web service an authentication token and attachment identifier, so that the web service can retrieve the attachment from the Exchange Online server. If the user’s mailbox is hosted on Exchange Online, then the user can install and start such a mail app on Outlook Web App that uses this new set of API to access mail attachments.

The following is the set of new APIs that support accessing attachments:

AttachmentDetails object and members
Item.attachments property
Mailbox.ewsUrl property
Mailbox.getCallbackTokenAsync method
AttachmentType enumeration

In the next few weeks, there will be additional content and example elaborating how to use these new objects and members. Stay tuned on the Apps for Office and SharePoint Blog for the latest news!

Working with tracked changes and comments programmatically in Word 2013

Saul Candib — Thu, 10 Jan 2013 20:53:00 GMT

In this blog post, I will describe the changes to the object model for displaying tracked changes and comments from Microsoft Word 2010 to Microsoft Word 2013 and I explain how to work with the new programmability features relating to tracked changes and comments in Word 2013.

APIs for displaying tracked changes and comments in Word 2010

In Word 2010, the View.RevisionsView property helps toggle the display of all tracked changes and comments in the active document by setting the value to one of two possible constants from the WdRevisionsView enumeration: wdRevisionsViewOriginal, and wdRevisionsViewFinal. In Word 2013, this property is replaced by the new RevisionsFilter.View property. RevisionsFilter is a new object added to the object model in Word 2013.

In addition, to toggle display of tracked changes revision marks in Word 2010 you can use the Document.ShowRevisions property, which takes a Boolean. In Word 2013, that property is also hidden, replaced by the new RevisionsFilter.Markup property.

In Word 2010, the Window.ToggleShowAllReviewers method toggles the display of all reviewers’ comments for the specified window. In Word 2013, this method is replaced by the RevisionsFilter.ToggleShowReviewers method. In addition, the View.Reviewers property in Word 2010 is replaced by the RevisonsFilter.Reviewers property.

Also, in Word 2010 the Reviewer.Visible property specifies whether markup from a particular reviewer is displayed. This property remains available in Word 2013, but Word 2013 also adds the RevisionsFilter.Reviewers property, which controls the display of reviewer markup.

In the next section I’ll list all these new objects and members and provide some sample code that shows how to use them.

New APIs for displaying tracked changes and comments and filtering reviewers in Word 2013

A new object, RevisionsFilter, and several new members of that object related to the display of tracked changes and comments, and to filtering the display of changes and comments from specific reviewers, have been added to the Word object model in 2013. You can use the View.RevisionsFilter property to return a RevisionsFilter object.

New members have also been added to the existing Comment object to accommodate the new functionality in Word 2013 that allows users to reply to comments.

RevisionsFilter members

The new members of the RevisionsFilter object are as follows:

The Markup property gets or sets a WdRevisionsMarkup constant that specifies the extent of reviewer markup displayed in the document. In the context of this setting, the word “markup” includes the revisions themselves, revision marks, and reviewer comments.

The possible values of WdRevisionsMarkup are shown in the following list. These values correspond to those in the Display for Review drop-down list in the Tracking group on the Review tab in the Word user interface (UI), as indicated. Figures 1, 2, and 3 show the results of applying the various settings:

wdRevisionsMarkupAll—Displays the final version of the document with all revisions incorporated and all markup visible. Corresponds to All Markup in the UI.
wdRevisionsMarkupSimple—Displays the final version of the document with all revisions incorporated, and with reviewer comments displayed, but with no revision marks (tracked changes) visible. Vertical marks in the left margin indicate lines in which revisions have been incorporated. Corresponds to Simple Markup in the UI.
wdRevisionsMarkupNone—Displays the final version of the document with all revisions incorporated but no markup visible. Corresponds to No Markup in the UI.

The Reviewers property returns a Reviewers object that represents the collection of reviewers of the active document and all other documents that are open or have been opened on the computer.

The View property returns or sets a WdRevisionsView constant that specifies whether Word uses the original version of the document or the final version as the basis for the revisions shown.

Note: When revisions are visible, and when the MarkupMode property value is set to wdBalloonRevisions, the View property value determines which set of changes are shown in balloons.

The ToggleShowAllReviewers method shows or hides all revisions in a document that contains comments and tracked changes.

Figure 1. The result of setting Markup to wdRevisionsMarkupAll

Figure 2. The result of setting Markup to wdRevisionsMarkupSimple

Figure 3. The result of setting Markup to WdRevisionsMarkupNone

The following code shows how to display all markup in the active document. It also hides the markup and comments from the second reviewer in the collection of reviewers.

Public Sub RevisionsFilter_Example()
    Dim wrdRevisionsFilter As RevisionsFilter
    Set wrdRevisionsFilter = ActiveDocument.ActiveWindow.View.RevisionsFilter
    wrdRevisionsFilter.Markup = wdRevisionsMarkupAll
    wrdRevisionsFilter.Reviewers.Item(2).Visible = False
End Sub

Comment members

The new members of the Comment object are as follows.

Member	Description
Ancestor property	Returns the parent Comment object for comments that are replies to existing comments. For new, top-level comments, the property returns null.
Contact property	Returns a CoAuthor object that represents the author of the comment
Done property	Returns or sets a Boolean whose value is true if the comment has been marked as complete in the UI. Users can mark a comment as done by choosing a comment and choosing Mark Comment Done on the context menu.
Replies property	Returns a Comments collection of Comment objects that are children of the specified comment.
DeleteRecursively method	Deletes the specified comment and all associated replies.

The following code shows how to get the count of all the replies to a specific comment.

Public Sub GetReplies()
    Dim myComment As Comment
    Set myComment = ActiveDocument.Comments(1) 
    Debug.Print myComment.Replies.Count    
End Sub

When should I choose to create a mail app versus an add-in for Outlook?

angelgolfer — Mon, 10 Dec 2012 16:55:00 GMT

Some of you may or may not be aware that alongside with the legacy COM-based Office client object models, Office 2013 supports a new apps for Office developer platform. This blog post is intended to help new and existing Office developers understand the main differences between the COM-based object models and the apps for Office platform. In particular, this post focuses on Outlook, suggests why you should consider developing solutions as mail apps, and identifies those exceptional scenarios where add-ins may still be the more appropriate choice.

An introduction to the apps for Office platform

The apps for Office platform includes a JavaScript API for Office and a schema for apps for Office manifests. You can use this platform to extend web services and content into the context of rich and web clients of Office. An app for Office is a webpage that is developed using common web technologies, hosted inside an Office client application (such as Outlook) on-premises or in the cloud. Of the three types of apps for Office, the type that Outlook supports is called mail apps. While you use the legacy APIs—the object model, PIA, and MAPI—to automate Outlook at an application level, you can use the JavaScript API for Office in a mail app to interact at an item level with the content and properties of an email message, meeting request, or appointment. You can publish mail apps in the Office Store or in an internal Exchange catalog. End users and administrators can install mail apps for an Exchange 2013 mailbox, and use mail apps in the Outlook rich client as well as Outlook Web App. As a developer, you can choose to make your mail app available for end users on only the desktop, or also on the tablet or smart phone. You can find more information about the apps for Office platform by starting here: Overview of apps for Office.

Architectural differences between add-in model and apps for Office platform

Add-in model

The Office add-in model offers individual object models for most of the Office rich clients. Each object model is intended to automate the corresponding Office client, and allows an add-in to integrate closely with the behavior of that client. The same add-in can integrate with one or multiple Office applications, such as Outlook, Word, and Excel, by calling into each of the Outlook, Word, and Excel object models. Figure 1 describes a few examples of 1:1 relationships between an Office rich client and its object model.

Figure 1. The legacy Office development architecture is composed of individual client object models.

Apps for Office platform

The apps for Office platform includes an apps for Office schema. Using this schema, each app specifies a manifest that describes the permissions it requests, its requirements for its host applications (for example, a mail app requires the host to support the mailbox capability), its support for the default and any extra locales, display details for one or more form factors, and activation rules for a mail app to be available in the app bar.

In addition to the schema, the apps for Office platform includes the JavaScript API for Office. This API spans across all supporting Office clients and allows apps to move toward a single code base. Rather than automating or extending a particular Office client at the application level, the apps for Office platform allows apps to connect to services and extend them into the context of a document, message, or appointment item in a rich or web client. Figure 2 shows Office applications with their rich and web clients sharing a common app platform.

Figure 2. The apps for Office development architecture is composed of a common platform and individual object models.

One main difference of note is that the object models were designed to integrate tightly with the corresponding Office client applications. However, this tight integration has a side effect of requiring an add-in to run in the same process as the rich client. The reliability and performance of an add-in often affects the perceived performance of the rich client. Unlike client add-ins, an app for Office doesn’t integrate as tightly with the host application, does not share the same process as the rich client, and instead runs in its own isolated runtime environment. This environment offers a privacy and permission model that allows users and IT administrators to monitor their ecosystem of apps and enjoy enhanced security.

Main features available to mail apps

Contextual activation: Mail app activation is contextual, based on the app’s activation rules and current circumstances, including the item that is currently displayed in the Reading Pane or inspector. A mail app is activated and becomes available to end users when such circumstances satisfy the activation rules in the app manifest.

Matching known entities or regular expression: A mail app can specify certain entities (such as a phone number or address) or regular expressions in its activation rules. If a match for entities or regular expressions occurs in the item’s subject or body, the mail app can access the match for further processing.

Roaming settings: A mail app can save data that is specific to Outlook and the user’s Exchange mailbox for access in a subsequent Outlook session.

Accessing item properties: A mail app can access built-in properties of the current item, such as the sender, recipients, and subject of a message, or the location, start, end, organizer, and attendees of a meeting request.

Creating item-level custom properties: A mail app can save item-specific data in the user’s Exchange mailbox for access in a subsequent Outlook session.

Accessing user profile: A mail app can access the display name, email address, and time zone in the user’s profile.

Authentication by identity tokens: A mail app can authenticate a user by using a token that identifies the user’s email account on an Exchange Server.

Using Exchange Web Services: A mail app can perform more complex operations or get further data about an item through Exchange Web Services.

Permissions model and governance: Mail apps support a three-tier permissions model. This model provides the basis for privacy and security for end users of mail apps.

Major objects for mail apps

For mail apps, you can look at the JavaScript API for Office object model in three layers:

In the first layer, there are a few objects shared by all three types of apps for Office: Office, Context, and AsyncResult.
The second layer in the API that is applicable and specific to mail apps includes the Mailbox, Item, and UserProfile objects, which support accessing information about the user and the item currently selected in the user’s mailbox.
The third layer describes the data-level support for mail apps:
1. There are CustomProperties and RoamingSettings that support persisting properties set up by the mail app for the selected item and for the user’s mailbox, respectively.
2. There are the supported item objects, Appointment and Message, that inherit from Item, and the MeetingRequest object that inherits from Message. These objects represent the types of Outlook items that support mail apps: calendar items of appointments and meetings, and message items such as email messages, meeting requests, responses, and cancellations.
3. Then there are the item-level properties (such as Appointment.subject) as well as objects and properties that support certain known Entities objects (for example Contact, MeetingSuggestion, PhoneNumber, and TaskSuggestion).

Figure 3 shows the major objects: Mailbox, Item, UserProfile, Appointment, Message, Entities, and their members.

Figure 3. Major objects and their members used by mail apps in the JavaScript API for Office.

Figure 4 shows all of the objects and enumerations in the JavaScript API for Office that pertain to mail apps.

Figure 4. All objects for mail apps in the JavaScript API for Office.

Figure 5 is a thumbnail of a diagram with all the objects and members that mail apps use. To see the diagram in a larger size, click the thumbnail or open the attached PDF file.

Figure 5. All objects and members used by mail apps in the JavaScript API for Office.

Reasons to create mail apps instead of add-ins for Outlook

The following are common reasons why mail apps are a better choice for developers than add-ins:

You can use existing knowledge of and the benefits of web technologies such as HTML, JavaScript, and CSS. For power users and new developers, XML, HTML, and JavaScript require less significant ramp-up time than COM-based APIs such as the Outlook object model.
You can use a simple web deployment model to update your mail app (including the web services that the app uses) on your web server without any complex installation on the Outlook client. In fact, any updates to the mail app, with the exception of the app manifest, do not require any updating on the Office client. You can update the code or user interface of the mail app conveniently just on the web server. This presents a significant advantage over the administrative overhead involved in updating add-ins.
You can use a common web development platform for mail apps that can roam across the Outlook rich client and Outlook Web App on the desktop, tablet, and smartphone. On the other hand, add-ins use the object model for the Outlook rich client and, hence, can run on only that rich client on a desktop form factor.
You can enjoy rapid turnaround of building and releasing apps via the Office Store.
Because of the three-tier permissions model, users and administrators can appreciate better security and privacy in mail apps than add-ins, which have full access to the content of each account in the user’s profile. This, in turn, encourages user consumption of apps.
Depending on your scenarios, there are features unique to mail apps that you can take advantage of and that are not supported by add-ins:

You can specify a mail app to activate only for certain contexts (for example, Outlook displays the app in the app bar only if the message class of the user-selected appointment is IPM.Appointment.Contoso, or if the body of an email contains a package tracking number or a customer identifier).
You can activate a mail app if the selected message contains some known entities, such as an address, contact, email address, meeting suggestion, or task suggestion.
You can take advantage of authentication by identity tokens and of Exchange Web Services.

Reasons to choose add-ins

The following features are unique to add-ins and may make them a more appropriate choice than mail apps in some circumstances:

You can use add-ins to extend or automate Outlook at an application-level, because the object model and PIA have extensive integration with Outlook features (such as all Outlook item types, user interface, sessions, and rules). At the item-level, add-ins can interact with an item in read or compose mode. With mail apps, you cannot automate Outlook at the application level, and you can extend Outlook’s functionality in the context of only the read-mode of the supported items (messages and appointments) in the user’s mailbox.
You can specify custom business logic for a new item type.
You can modify and add custom commands in the ribbon and Backstage view.
You can display a custom form page or form region.
You can detect events such as sending an item or modifying properties of an item.
You can use add-ins on Outlook 2013 and Exchange Server 2013, as well as earlier versions of Outlook and Exchange. On the other hand, mail apps work with Outlook and Exchange starting in Outlook 2013 and Exchange Server 2013, but not earlier versions.

Conclusion

When you are considering creating a solution for Outlook, first verify whether the supported major features and objects of the apps for Office platform meet your needs. Develop your solution as a mail app, if possible, to take advantage of the platform’s support across Outlook clients over the desktop, tablet, and smartphone form factors. Note that there are still some circumstances where add-ins are more appropriate, and you should prioritize the goals of your solution before making a decision.

Further references

Apps for Office and mail apps

Build apps for Office

Mail apps for Outlook

JavaScript API for Office

Schema reference for apps for Office manifests

Legacy Outlook object model and APIs

Welcome to the Outlook 2013 developer reference

Outlook 2013 MAPI Reference

What's new for Outlook 2013 developers

Welcome to the Outlook 2010 Primary Interop Assembly Reference

What's new for developers in Visio 2013?

Saul Candib — Mon, 29 Oct 2012 22:26:00 GMT

In this post, I'll introduce some of the new features of interest to developers in Visio 2013. Among these features are:

New file format
Robust updates to themes
The change shape feature (that allows you to replace one shape with another while Maintaining shape text)
New shape effects
Improvements to commenting
Coauthoring on SharePoint Server 2013
Customizable image clipping
Relative geometry
Support for Business Connectivity Services (BCS) data
Updates to Visio Services in Microsoft SharePoint Server 2013
Duplicate page feature

At the end of the post, I provide you with some additional resources for both Visio and general Office development.

New file format

Visio 2013 introduces a new file format, based on the Open Packaging Conventions (OPC) standard (ISO 29500, Part 2) and the XML elements from the previous Visio XML file format (.vdx). It is a zipped, XML-based file format similar to the file formats used in other applications.

Because the new file format is supported by both Visio 2013 and Visio Services in Microsoft SharePoint Server 2013, you can save a Visio drawing directly to a SharePoint Server library without having to first publish the file as a Visio Web Drawing (.vdw). Even so, Visio Services can still read and display Visio Web Drawing files.

The new file format includes the following file types (by extension):

.vsdx (Visio drawing)
.vsdm (Visio macro-enabled drawing)
.vssx (Visio stencil)
.vssm (Visio macro-enabled stencil)
.vstx (Visio template)
.vstm (Visio macro-enabled template)

By using existing support for reading and writing to the file format package (such as System.IO.Packaging) and for parsing XML (System.Xml.Linq), you can work with the new file formats programmatically.

Visio 2013 retains the ability to read the old file formats (.vsd, .vss, .vst, .vdx, .vsx, .vtx, .vdw, .vwi). Visio 2013 does not save to the previous Visio XML file format (.vdx). Solutions or tools that consume the previous Visio XML file format (.vdx) files may need to be refactored in order to read the new file format and its schemas.

Visio Services retains the ability to display the Visio Web Drawing (.vdw) format in the browser. It now also renders the new Visio drawing (.vsdx) and Visio macro-enabled drawing (.vsdm) formats.

For more information about the new file format, see the article How to: Manipulate the Visio 2013 file format programmatically.

Themes

Themes have been redesigned in Visio 2013, making use of a greater variety of effects and styles including the integration of Shape Art effects. Users can now decide on an overarching style by applying a theme, personalize the diagram with theme variants, and highlight individual shapes with Quick Styles. ShapeSheet developers can take advantage of these features with new functions and cells in the ShapeSheet.

The user interface for applying theme variants is shown in the following figure.

You can also manipulate themes at the Page, Shape, and Selection object level. New APIs for working with themes include Page.SetTheme method, Page.SetThemeVariant method, Shape.SetQuickStyle method, and the Selection.SetQuickStyle method.

For more information about new VBA objects and members in Visio 2013, see the Visio Automation reference. For more information about the new ShapeSheet cells in Visio 2013, see the article What's new for ShapeSheet developers in Visio 2013.

Change Shape

Visio 2013 includes a shape replacement API that enables you to swap one or more shapes for another shape contained in a stencil, while retaining some of the local values from the original shape, like the shape text shape, shape data, or shape formatting. Shape developers can update the ShapeSheet settings of their custom shapes to specify the Change Shape behavior for their shapes. Among the new APIs for Change Shape are the Shape.ReplaceShape and Selection.ReplaceShape methods and the ReplaceShapesEvent object.

The Change Shape feature lets you easily change a shape (in this case, the green rectangle)…

…to another shape, the green diamond.

For more information about the Change Shape feature, see Eric Schmidt’s blog post, Change shapes in Visio 2013.

Shape effects

New shape effects such as bevel, 3-D rotation, glow, reflection, and sketching have been added to Visio 2013. The ShapeSheet includes new cells for working with these effects. The following figure shows a shape to which effects have been applied.

You can also use Office VBA objects such as TextFrame2, GlowFormat, and ReflectionFormat and their members to apply shape effects.

For more information about the new ShapeSheet cells in Visio 2013, see the article What's new for ShapeSheet developers in Visio 2013.

Commenting

Visio 2013 includes a new commenting framework. Comments can now be associated with a particular shape or page. Visio 2013 includes two new objects, Comments and Comment. New APIs for accessing comments programmatically include the Document.Comments, Page.Comments, Shape.Comments, and Page.ShapeComments properties.

The following images show what comments looked like in Visio 2010 and what they look like in Visio 2013.

Visio Services includes JavaScript APIs to read the comments from a page or shape in a diagram.

Note: You can no longer access comments in the ShapeSheet.

Coauthoring

Visio 2013 includes the ability to co-author diagrams stored on SharePoint or SkyDrive. Developers have access to the Document.AfterDocumentMerge event which provides information about diagram changes due to coauthoring. Solution developers also have the ability to disable coauthoring to suit their custom needs by using the NoCoauth cell on the Document ShapeSheet.

Customizable image clipping

Visio 2013 supports defining a Custom Image Clipping path to crop images to any shape. This extends the capacities of Visio 2010, which supported clipping images in a rectangular way. This functionality is available in the ShapeSheet by using the ClippingPath cell in the Foreign Image Info section.

Relative geometries

In previous versions of Visio, shape geometry was defined by formulas that depended on the height or width of the shape. For example, in Visio 2010 the vertices of many built-in Visio shapes were defined by multiplying the height or width of the shape by a constant. These shapes had Geometry sections that included MoveTo or LineTo rows (for example) with formulas like Width*1 and Height*0.

Visio 2013 now supports relative geometry in the ShapeSheet. Shape developers can now use relative geometries to specify geometries as simple values or formulas, which multiply by the height or width automatically. You can now express Shape vertices by using constants, for instance—you no longer need to express vertices as multiples of the shape width or height. This makes it easier for you to create shapes that have better performance and smaller file sizes. New rows include the RelMoveTo and RelLineTo rows where the X and Y cell values are automatically multiplied by the width or height of the shape (respectively).

Support for Business Connectivity Services (BCS) data

Visio 2013 diagrams can now be connected to external lists on SharePoint Server 2013 servers. An external list is a content source external to SharePoint (for example, a SQL Server table) that has been connected to a SharePoint list by using Microsoft Business Connectivity Services (BCS). Visio Services supports the ability to refresh the Visio diagrams as the data updates.

For more information about what’s new in Visio Services, see the article Visio Services in SharePoint 2013. For more information about Business Connectivity Services (BCS), see Business Connectivity Services in SharePoint 2013.

Improvements in Visio Services

Visio Services in Microsoft SharePoint Server 2013 includes many improvements. As mentioned previously, Visio Services supports the new Visio file format (.vsdx and .vsdm). Visio Services has expanded data refresh and recalculation, including the ability to recalculate formulas across an entire diagram.

For more information about what’s new in Visio Services, see the article Visio Services in SharePoint 2013.

Duplicate page

You can now copy a page and all of its shapes within the same document in Visio 2013. Accordingly, the Page object has a new method, Duplicate, which duplicates the page and returns a new Page object.

Additional resources

Want to learn more about the latest in Office development? Visit the Apps for Office and SharePoint Developer Center and the Apps for Office and SharePoint blog!

What’s new in Access 2013 for developers

S. D. Oliver — Wed, 24 Oct 2012 17:00:00 GMT

Mike Stowe, Programming Writer, Office Developer Documentation team, authored today's post.

Access 2013 features a new type of application model, Access apps, that’s makes it easy to create, customize, and deploy an app to the cloud. This post briefly describes some of the features that make that possible.

Bring Access apps to the cloud with Office 365

If you subscribe to the Office 365 plan includes SharePoint Online, such as Office 365 Small Business Premium or Office 365 Enterprise, you can host your Access 2013 apps in the cloud with no extra setup required. Microsoft will make sure your data is secure, backed-up, and available, so that you can focus on getting things done.

For more information about hosting your Access app in the cloud, see Get started with Access 2013 Web Apps.

Access apps are SharePoint apps

SharePoint 2013 features a new application model, apps for SharePoint. In an on-premises environment, Access apps are hosted on SharePoint 2013. SharePoint 2013 provides the infrastructure and tools to manage, deploy, and maintain your app. Your Access app can be featured in your company’s app catalog, where users can discover and install it in just a few clicks. Best of all, anyone with a web browser and an internet connection can use your app, even if Access isn’t installed on their device.

For information about apps for Office 2013, see Apps for Office and SharePoint in the MSDN online library. Additionally, you can follow the Apps for Office and SharePoint developer blog to keep up on the latest information around apps for Office and SharePoint.

SQL Server back-end

When you create an Access app —whether on-premise or through Office 365—a full-fledged SQL Server database is automatically created to store its data and objects. This means that your app will be faster, more reliable, and work great with large amounts of data. If you’re already familiar with SQL Server you can connect to this database for advanced reporting and analysis with familiar tools such as Excel, Power View, and Crystal Reports. Your users can rest assured that their apps are ready for the future if they ever need to enhance them with advanced integrations or migrations.

For more information about Access apps and SQL Server, see Access 2013 and SQL Server.

Polished user experience

Access apps feature a polished user interface (UI) that’s optimized for the web. When you create a table, Access automatically creates a set of views for you to customize. The default views contain different paradigms for filtering and data entry. They contain some features that you’d have to code by hand in an Access desktop database.

List Details view allows the user to filter the view by using a search box. Datasheet view provides a spreadsheet-like experience for users who prefer to view many records at once. If your app contains related data, Access adds a control to the view that displays the related items, allowing the user to “drill-down” on the details.

For more information about views, see what’s new for Access 2013 developers.

Office 2013 Developer Content Landscape

Luke Nyswonger — Tue, 02 Oct 2012 22:09:00 GMT

Hi, my name is Luke Nyswonger and I lead the developer content team for Office programmability. My team creates developer docs, code samples, and videos for client extensibility—apps for Office, VBA, Open XML, etc. In this version of Office, we made a much larger investment for developers than any other previous releases. As both Brian and Rolando discussed in their posts, our new Office cloud app model complements our existing extensibility model and provides you more choices. Today I’m going to provide an overview of our content landscape, changes we made to the overall experience, our F1 Help story, some pointers to get you started and ways to provide feedback to the team.

Less is definitely more

One goal for this release was to ensure that the user experience on the web was optimized. To that end, we reduced noise in the system and refreshed our content with a modern approach. In short, we not only spent time writing, but also optimized the entire experience so content is discoverable and usable. You can ask my team how tired they were of hearing my mantra “More code, more pics, less text.”

Why make such a change? Here are a few fun facts that helped influence our decision:

Tons of content. There are nearly 900,000 pieces of developer-related content assets in 11 locales that need to be managed and groomed from release to release.
Customer satisfaction. In customer surveys, satisfaction scores indicate that discoverability is a major pain point. In fact, only 54% of developers actually find what they are looking for when searching Office developer content.
Search. Significantly more traffic comes from search, not context-sensitive (F1) Help calls. Most page views are actually links from other Microsoft properties.

We had to embrace the fact that people are consuming information in different ways, on different devices and therefore the style and depth at which we wrote content needed to change. For this release we’ve taken two measurable approaches:

Reduce the footprint. Retiring legacy and non-performing pages, consolidating content. Reduce clutter so you can more-easily find what you are looking for.
Create the right content and make it modern. Skimming instead of reading is a fact on the web. In this release, we’ve optimized content to be more “glanceable” and to provide quick access to the information you need.

Farewell “wall of links”

Writers love to write. We also love to create those dreaded “walls of links”.
We’ve reduced the number of pages that consist solely of links and redesigned our remaining navigation pages to be easier to skim and use to find the information you need. As an example, we reduced the number of navigation pages from 432 to 100 (-77%).

Is that the MSDN Library?

In addition to the redesign of the developer centers, we also overhauled our content model for the library so that it was easier to navigate and use. You’ll notice our new approach to modern content and the use of everyday language. The following screenshot, from the article What’s New for Excel 2013 developers, is a good example of where we are headed with our approach to modern content.

On the left side of this page, you’ll see a new table-of-contents experience. We call this a “scoped view” of the MSDN library. We wanted to mirror this experience with all our navigational pages so the Office developer experience had a consistent look and feel. Take a look at these two examples to understand the difference:

Non-scoped View (Lightweight, Classic, or ScriptFree)
Scoped View

Jakob Nielsen has a famous quote in his book on web usability, “Ultimately, users visit your web site for the content. Everything else is just the backdrop. The design is there to allow people access to the content.” Eloquently put, Jakob! Through our design changes, content layout and approach to how we author the content, we hope that you are finding what you need and that the content and scenarios we are documenting are serving your needs. If not, let us know!

Enough about docs, what about code samples!?

If there is one thing we know, developers love code! It’s consistently the number one request from customers. In this release, we are building more code samples (solutions, examples, and snippets) across the content space.

Get samples online. In MSDN Code Gallery, you can discover new code samples, share your own samples, and request new samples. We have a section dedicated entirely to Office as well as Apps for Office and have begun stocking the shelves to help you accelerate stocking the Office Store!

See samples from within Visual Studio. If you’re using Visual Studio for development, there’s a great new feature available in Visual Studio 2012 that allows you browse samples from the MSDN Code Gallery and download them directly into your environment.

View examples inline with the docs. As always, we’ll continue to provide code examples and snippets within the documentation itself so you can copy/paste until your heart is content.

Who moved my cheese?

In previous versions of our developer documentation, we provided the ability to browse and read documentation offline. Pressing F1 from within the Visual Basic Editor (VBE) could be configured to route directly to the offline content with no need to be connected to the Internet. In addition, you could search and browse the offline content. This comes in handy when you’re bored on the beach and need to find out exactly what’s new for developers in Office 2013. Within the walls of Microsoft, we often refer to this experience as the “airplane scenario.” Investing in this experience has been a perennial debate across the company within every major division and for every product for the past decade.

In Office 2013, we have made some significant architectural changes for the documentation across the product line—this includes end-user Help. Here you can see the differences in the user experience with the 2010 and 2013 Help clients.

As part of the change, we also made the decision that all developer related content would be hosted on MSDN and that F1 calls from VBE would be routed to MSDN. This comes with several advantages – one canonical source of documentation, deep integration with other content on MSDN, in-sync with localized content, rapid bug fixes, always up to date, etc. However, it does have one drawback…yep you guessed it; we don’t support the “airplane scenario” out of the box. That is, when you install Office 2013 and the developer tools, there is no option to install local developer help.

But wait, hold the lemons! For all you coders on an airplane, submarine or behind the firewall, we are going to offer a stand-alone version of the documentation that you can download from MSDN. What’s “stand-alone” you ask? Our Apps for Office and SharePoint Preview SDK is representative of the experience you’ll have with the full Office developer documentation offline. One thing you need to be aware of is that the F1 experience is an online-only experience so even though you have the offline documentation all of your F1 help calls will route to MSDN. Look for the full download of the Office 2013 developer docs in the near future! If you have any feedback about this approach, we would love to hear it.

Speaking of feedback…

Since the first release of the developer documentation at the Customer Preview in July, we have been steadily providing updates, fixes, and new code samples for the documentation. Much of what we update is based on feedback from you. So keep it coming!

Great, so how do you provide feedback?

There are three main ways to provide us feedback on the developer content:

Send us a comment on the topic/article. On every article on MSDN we have a feedback and ratings tool. We review every single piece of feedback that comes in and triage it for upcoming content releases. This is done via our “double-blind” system so the feedback that you provide is anonymous.
Engage us in the community. Another way to give us feedback is to engage us in the community at the support forums, on Facebook and Twitter. Heck, we’re even on Stack Overflow!
Send mail directly to the team. Yes, that’s right! If you feel like you want to reach out with a personal mail please send it directly to docthis@microsoft.com and we’ll review and respond.

Hello, "wall of links"

I couldn’t help myself. So while I have your attention, I’m going to showcase a few of the key resources the team has been working on which should be of tremendous value as you start building solutions for the next version of Office.

Apps for Office

General Office Development

Learning Centers - Office Clients

Conclusion

We are excited about this new release of Office for developers. We’ve packed MSDN with all kinds of goodies to help jumpstart your development and we have much more to come for RTM and beyond. If you have thoughts, suggestions or requests, we definitely want to hear them. With over a billion users and one copy of Office sold every second, the potential market opportunity as a developer couldn’t be any better.

Happy coding!

What's new in Excel 2013 Preview for developers

S. D. Oliver — Thu, 20 Sep 2012 17:57:00 GMT

New features for developers in Excel 2013 Preview

Frank Rice, Senior Programming Writer, Office Developer Documentation team, authored today's post.

This post briefly describes some of the features available to developers in Excel 2013 Preview.

Apps for Office

Of course, the big news for developers and users are apps for Office in Excel that brings the web to Excel. Because this feature is web-based, you can use popular dynamic languages (such as Python, PHP, Perl, and JavaScript) and web development tools (such as Microsoft Visual Studio 2012) for application development. You can create two kinds of apps for Office in Excel, Content apps and Task pane apps. Content apps for Office integrate web-based features as content that can be shown in line with the document. Task pane apps for Office work side-by-side with an Office document. For a great example of an app for Office in Excel 2013, see the the Medal Tracker Template.

You have probably already seen a lot of information about apps for Office and will definitely see much more in the future, so the rest of this post will focus on some of the other Excel 2013 features. For information about apps for Office 2013, see Apps for Office and SharePoint in the MSDN online library. Additionally, you can follow the Apps for Office and SharePoint developer blog to keep up on the latest information around apps for Office and SharePoint.

New worksheet features

Excel 2013 Preview adds about fifty new worksheet functions for compatibility with the Open Document Format (ODF 1.2). For more information about ODF, see http://opendocumentformat.org/. You can also now use web service functions to anonymously access REST Web services. Of special note is the FILTERXML function, which lets you use XPath expressions to filter the XML returned by a WEBSERVICE function call.

Quick Analysis

Quick Analysis, as shown in Figure 1, is a contextual UI tool that enables single-click access to data-analysis features, such as formulas, conditional formatting, Sparklines, tables, charts, and PivotTables. You can enable and disable the display of the new Quick Analysis feature in Excel 2013 Preview programmatically by using the Show and Hide methods of the QuickAnalysis object.

Figure 1. Quick Analysis tool

New data sources

You can connect to many new data sources supported by PowerPivot, including OData feeds, Azure, SharePoint Data Feeds, and other OLE DB providers. The new DataFeedConnection, ModelConnection, TextConnection, and WorksheetDataConnection objects contain data and functionality needed to connect to new data sources.

DataModel object model

A new DataModel object model (an addition to the existing VBA object model) enables you to load and refresh data sources programmatically. This extension to the PowerPivot model introduced in Excel 2010 enables you to integrate additional data sources and the ability to combine data from multiple data sources programmatically.

Create independent PivotTables and PivotCharts

You can decouple PivotCharts from PivotTables in Excel 2013 Preview. PivotCharts and PivotTables based on an OLAP or PowerPivot data source can be decoupled such that you can create a PivotChart independently of any PivotTable and you can navigate through data by using a PivotChart-only experience.

Single document interface

Excel 2013 Preview uses a single-document interface (SDI). SDI means that each workbook will have its own top-level app window and will have its own corresponding ribbon. All existing application-level window methods, events, and properties are unaffected by this change. All existing workbook-level window methods, events, and properties now operate on the top-level window for that workbook. And the list goes on...

Conclusion

I encourage you to download Excel 2013 Preview and experiment with these and more features for developers not discussed here. You can get Microsoft Office 365 ProPlus Preview which includes Excel as well as Word, PowerPoint, Outlook, and other products at the MSDN Evaluation Center.

Additional resources

You can find much more information about many of the features for Excel developers in the article titled What's new for Excel 2013 developers. Additionally, you can find information about the developers features available in other Office products in the article titled What's new for Office 2013 developers.

What's new for developers in the new Project desktop (besides task pane apps)

Jim Corbin — Wed, 12 Sep 2012 16:00:00 GMT

Project Standard 2013 and Project Professional 2013 include many new features for developers, such as new reports, task paths, cache status, and working with SharePoint tasks lists. This article shows VBA examples for new features in Project. You can use the new classes and members in the Project object model with VBA or with Visual Studio 2012 and Tools for Office (VSTO).

This article does not cover task pane apps, which have a JavaScript API and can be developed with HTML5. Task pane apps are another of the major new programmability features in the Office 2013 versions of Project, Word, and Excel. Word, Excel, and Outlook also support content apps and mail apps. For information about apps for Office 2013, see Apps for Office and SharePoint and Task pane apps for Project in the MSDN online library. Additionally, you can follow the Apps for Office and SharePoint developer blog to keep up on the latest information around apps for Office and SharePoint.

Task pane apps and other apps for Office and SharePoint can be sold in the Office Store (see http://officepreview.microsoft.com/store/) for use with both Project Online and on-premises installations. VBA macros and VSTO add-ins cannot be distributed in the Office Store; they are designed for local use with Project Standard and Project Professional. You can distribute VBA macros within a project .MPP file, install them in the Global.MPT file on your machine, or distribute them in the enterprise global template in Project Server 2013. VSTO add-ins can be distributed more securely through ClickOnce deployment, which enables easy updates.

Project has had VBA for decades – well, since Project 4.0 in 1994 – and has had a primary interop assembly (Microsoft.Office.Interop.MSProject.dll ) for VSTO add-ins since Project 2003. The PIA includes essentially the same classes, properties, methods, and events that VBA exposes. You can use the VBA object model to create test macros, and then translate them to a VSTO add-in that uses C# or Visual Basic. VSTO add-ins are much more flexible, robust, secure, and manageable than VBA macros. Project 2013 extends the object model to include Office Art, new reports, and new members of the Application, Project, and Task objects that reflect new or improved features.

New reports

Project 2013 implements most of the Office Art infrastructure that is also used in Word, Excel, and PowerPoint. Project also adds flexible new reports that are directly programmable and use Office Art objects such as Chart, Shape, and ShapeRange. Project adds the Report object and a ReportTable shape type, and enables charts and tables to dynamically use task and resource fields in the active project through the Field List task pane.

Project 2013 includes over 20 new built-in reports such as Project Overview, Task Cost Overview, and Best Practice Analyzer. Each of the new reports contains chart, table, and Office Art shapes. You can create custom reports manually using commands on the REPORT tab of the ribbon, or programmatically with VBA or VSTO.

The following code creates a custom report that contains one Shape object, which is a ReportTable. The number of elements in the SafeArrayOfPjField parameter of the UpdateTableData method specifies the number of columns in the table; fields can be chosen from the 1,338 PjField constants. Figure 1 shows the result.

Sub TestReportTable()
   Dim theReport As Report 
   Dim tableShape As Shape 
   Dim theReportTable As ReportTable 
   Dim reportName As String
     Dim tableName As String
    Dim rows As Integer
    Dim columns As Integer
    Dim left As Integer
    Dim top As Integer
    Dim width As Integer
    Dim height As Integer
 
    reportName = "Table Report" 
    Set theReport = ActiveProject.Reports.Add(reportName) 
    ' Add the table.
    tableName = "Task information" 
    rows = 0 
    columns = 0 
    left = 0 
    top = 30 
    width = 110 
    height = 20 

    ' Project ignores the NumRows and NumColumns parameters when creating a ReportTable. 
     tableShape = theReport.Shapes.AddTable(rows, columns, _
         left, top, width, height) 
    tableShape.Name = tableName 
    tableShape.Select() 
    Set theReportTable = tableShape.Table 

    ' Set fields for the table. 
     Dim fieldArray(1 To 6) As PjField 
    fieldArray(1) = pjTaskName 
    fieldArray(2) = pjTaskStart 
    fieldArray(3) = pjTaskFinish 
    fieldArray(4) = pjTaskPercentComplete 
    fieldArray(5) = pjTaskActualCost 
    fieldArray(6) = pjTaskRemainingCost 

    theReportTable.UpdateTableData(Task:=True, OutlineLevel:=1, _
        SafeArrayOfPjField:=fieldArray)
 End Sub

Figure 1. Creating a custom report that contains a table

Creating a chart on a report is just as easy. The following code example is copied from the Chart Object topic in VBA Help, which creates a default chart and positions the chart title (see Figure 2).

Sub AddSimpleScalarChart() 
    Dim chartReport As Report 
    Dim reportName As String 
   
    ' Add a report. 
    reportName = "Simple scalar chart" 
    Set chartReport = ActiveProject.Reports.Add(reportName) 

    ' Add a chart. 
    Dim chartShape As Shape 

    Set chartShape = ActiveProject.Reports(reportName).Shapes.AddChart() 
    chartShape.Chart.SetElement(msoElementChartTitleCenteredOverlay) 
    chartShape.Chart.ChartTitle.Text = "Sample Chart for the Test1 project" 
End Sub 

When you select the Chart object on the report, you can see the Field List task pane, and manually change the fields, filter, grouping, and sorting (or programmatically change them using the UpdateChartData method).

Figure 2. Creating a default chart on a report

For the built-in reports, you can manually change items on the reports, but you cannot programmatically change the existing items. However, you can copy any of the new reports with the Application.CopyReport method, create a custom report and paste the copied report to it, and then modify any of the elements. For example, the following code copies the Task Cost Overview report and changes the report title (see Figure 3).

Sub CopyCostReport() Dim reportName As String 
    Dim newReportName As String 
    Dim newReportTitle As String 
    Dim myNewReport As Report 
    Dim oShape As Shape 
    Dim msg As String 
    Dim msgBoxTitle As String 
    Dim numShapes As Integer 

    reportName = "Task Cost Overview" ' The built-in report. 
    
    newReportName = "Task Cost Copy" 
    msg = "" 
    numShapes = 0 

    If ActiveProject.Reports.IsPresent(reportName) Then 
        ApplyReport(reportName)    ' Display the report. 
        CopyReport() myNewReport = ActiveProject.Reports.Add(newReportName) 
        PasteSourceFormatting()    ' Paste the copy to the new report. 

        ' List the shapes in the copied report. 
        For Each oShape In myNewReport.Shapes 
            numShapes = numShapes + 1 
            msg = msg & numShapes & ". Shape type: " & CStr(oShape.Type) _
                 & ", '" & oShape.Name & "'" & vbCrLf 

            ' Modify the report title. 
            If oShape.Name = "TextBox 1" Then 
                newReportTitle = "My " & oShape.TextFrame2.TextRange.Text 

                 With oShape.TextFrame2.TextRange 
                    .Text = newReportTitle 
                    .Characters.Font.Fill.ForeColor.RGB = &H60FF10 ' Bluish green. 
                End With 

                oShape.Reflection.Type = msoReflectionType2 
                 oShape.IncrementTop(-10) ' Move title 10 points up. 
                oShape.Select() 
            End If 
        Next oShape 

        msgBoxTitle = "Shapes in report: '" & myNewReport.Name & "'" 
        If numShapes > 0 Then 
            MsgBox(Prompt:=msg, Title:=msgBoxTitle) 
        Else 
            MsgBox(Prompt:="This report contains no shapes.", _
                Title:=msgBoxTitle) 
        End If 
    Else 
        MsgBox(Prompt:="No custom report name: " & reportName, _
            Title:="ApplyReport error", Buttons:=vbExclamation) 
    End If 
End Sub 

The changes the previous code makes in the report are the color and position of the title (in "TextBox 1", which is selected in Figure 3), and adding a reflection effect. You can modify any of the shapes, including table and chart fields, and add the wide variety of Office Art shapes and fancy effects. The macro also displays the name and type of each shape in the collection of Shapes that is in the report; shape types are specified in the MsoShapeType enumeration.

Figure 3. Copying and modifying a built-in report

Task Path formatting

With the Task Path feature in Project 2013, you can dynamically show task predecessors, driving predecessors, successors, and driven successors by colors of tasks in the Gantt chart. In Figure 4, the Driving Predecessors and Driven Successors items are selected in the Task Path drop-down list. When you select T3, the Gantt chart shows that T1 is a driving predecessor task and T4 is a driven successor task. That is, T1 is a predecessor task, where the finish date drives the scheduled start date of T3; and T4 is a successor task of the selected task T3, where the T4 start date is driven by the scheduling of T3.

Figure 4. Using the task path properties to highlight tasks

You can manually select a task or use VBA to select a task, and then use VBA or VSTO to check how another task is related to the selected task. For example, if you are in the Gantt chart view of the project shown in Figure 4, and then run the following statements in the Immediate window of the VBE, the PathDrivenSuccessor statement prints True.

Application.SelectRow Row:=3, RowRelative:=False 
Application.HighlightDrivenSuccessors(True) 
? ActiveProject.Tasks(4).PathDrivenSuccessor

Waiting for a cache job to complete

Project Server 2007 and Project Server 2010 can determine when a server-side queue job is completed or has a problem, by using Project Server Interface (PSI) methods. Project Server 2013 and Project Online extend that capability with the client-side object model (CSOM – not to be confused with the client object model in Project Professional and Project Standard).

With Project Professional 2013, you can programmatically check the Active Cache status when you save, publish, or check in a project to Project Web App. The Active Cache for Project Professional runs on your local machine. The GetCacheStatusForProject property exposes the status of the queue job.

The following code example saves the active project, calls WaitForJob to wait for the queue job to finish successfully, and then publishes the project. The WaitForJob macro periodically checks the job state by calling GetCacheStatusForProject and prints the job status to the Immediate window. If it finds the same status more than ten times in succession, the WaitForJob macro assumes there is a problem and exits. The example uses a Sleep method that can be run in either a 64-bit or 32-bit Project installation.

Option Explicit 

#If Win64 Then 
    Private Declare PtrSafe Sub Sleep Lib "kernel32" _
        (ByVal dwMilliseconds As LongLong) 
#Else 
    Private Declare Sub Sleep Lib "kernel32" (ByVal dwMilliseconds As Long) 
#End If 

' Save and publish the active project; wait for the queue after each operation. 
Sub TestCacheStatus() 
    ' Number of milliseconds to sleep between status messages. 
    Const millisec2Wait = 500 
    Application.FileSave()

    If WaitForJob(PjJobType.pjCacheProjectSave, millisec2Wait) Then 
        Debug.Print("Save completed ...") 
        Application.Publish() 
        
        If WaitForJob(PjJobType.pjCacheProjectPublish, millisec2Wait) Then 
            Debug.Print("Publish completed: " & ActiveProject.Name)
        End If 
    Else 
        Debug.Print("Save job not completed") 
    End If 
End Sub 

' Check the cache job state for a save, publish, or check-in operation. 
Function WaitForJob(job As PjJobType, msWait As Long) As Boolean 
    ' Number of times the same job status is repeated until 
    ' WaitForJob exits with an error. 
    Const repeatedLimit = 10 Dim jobState As Integer 
    Dim previousJobState As Integer 
    Dim bail As Integer 
    Dim jobType As String 

#If Win64 Then 
    Dim millisec As LongLong 
    millisec = CLngLng(msWait) 
#Else 
    Dim millisec As Long 
    millisec = msWait 
#End If 

    WaitForJob = True 

    Select Case job 
        Case PjJobType.pjCacheProjectSave jobType = "Save" 
        Case PjJobType.pjCacheProjectPublish jobType = "Publish" 
        Case PjJobType.pjCacheProjectCheckin jobType = "Checkin" 
        Case Else jobType = "unknown" 
    End Select 

    bail = 0 

    If (jobType = "unknown") Then 
        WaitForJob = False 
    Else 
        Do 
            jobState = Application.GetCacheStatusForProject(ActiveProject.Name, job) 
            Debug.Print(jobType & " job state: " & jobState) 

            ' Bail out if something is wrong. 
            If jobState = previousJobState Then 
                bail = bail + 1     
                If bail > repeatedLimit Then 
                    WaitForJob = False 
                    Exit Do 
            End If 
        
            previousJobState = jobState Sleep(msWait) 
        Loop While Not (jobState = PjCacheJobState.pjCacheJobStateSuccess) 
    End If 
End Function 

Following is an example of output in the Immediate window. For the meaning of the output values, see the PjCacheJobState enumeration in the VBA Object Browser.

Save job state: 4 Save completed 
... 
Publish job state: -1 
Publish job state: 3 
Publish job state: 3 
Publish job state: 4 
Publish completed: WinProj test 1

Working with SharePoint tasks lists

Project Server 2013 and Project Online can import SharePoint tasks list as a project where SharePoint maintains control, or can import a tasks list as a project where Project Server has full control of scheduling and other project management features. You can use Project Professional 2013 to open and update either type of project. When you create a local project in Project Professional 2013, you can save the project to a new SharePoint tasks list – or link the new project with an existing tasks list.

The Project Professional 2013 object model includes new and updated members of the Application object to help work with SharePoint tasks lists:

SynchronizeWithSite is updated to work with SharePoint sites through Project Web App, where projects can be in either the Project Server full control mode or the SharePoint management mode. SynchronizeWithSite can still synchronize a local project with a SharePoint tasks list.
LinkToTaskList links a new project with a SharePoint task list. The method first verifies that the specified SharePoint site and tasks list exists, and then synchronizes the active project with the site by adding manually scheduled tasks and any assigned resources. LinkToTaskList also creates a .MPP file in the Site Assets list. The project file can contain VBA macros. For example, if the original tasks list in http://MySite is named Test Tasks List, use the following command:
```
LinkToTaskList SiteURL:="http://MySite", _
    TaskListName:="Test Tasks List"
```
After you use the LinkToTaskList method, the site contains the .MPP file at the following URL: http://MySite/SiteAssets/Content%20site-Test%20Tasks%20List.mpp. If Project is installed on a machine running Windows Server, you can use Server Manager to install the Desktop Experience feature; otherwise, the .MPP file cannot be created.
AddSiteColumn adds a column to a SharePoint tasks list for a project site, and optionally specifies the column name. The column can be one of the task PjField constants, such as pjTaskBaselineDurationText, where the column does not already exist in the SharePoint tasks list. The field cannot be an enterprise custom field or lookup table or a non-task field such as pjResourceActualCost. The next update of the VBA Help topic for the AddSiteColumn method will include a list of prohibited fields.

For example, create a tasks list in a SharePoint site, create a project in Project Professional, and then use the LinkToTaskList method to import the task list. Set a baseline for the project (use the Set Baseline command on the PROJECT tab of the ribbon), and then change the duration of some tasks.

The following code adds task duration and baseline duration to the list of available columns in the SharePoint task list.

Note After you run the AddDurationColumns macro, you must save the project in Project Professional to synchronize your changes with the SharePoint task list.

Sub AddDurationColumns() 
    Dim success As Boolean 
    Dim columnName As String 
    Dim fieldName As PjField 
    Dim results As String 

    results = "" 
    fieldName = pjTaskBaselineDurationText 
    columnName = "Baseline duration" 
 
    ' If the field name exists in the SharePoint tasks list, or 
    ' fieldName is one of the prohibited fields, the AddSiteColumn 
    ' method returns error 1100. 
    On Error Resume Next 

    success = AddSiteColumn(fieldName, columnName) 

    If success Then 
        results = "Added site column: " & columnName 
    Else 
        results = "Error in AddSiteColumn: " & columnName 
    End If 

    fieldName = pjTaskDurationText 
    columnName = "Current duration" 
    success = AddSiteColumn(fieldName, columnName) 

    If success Then 
        results = results & vbCrLf & "Added site column: " & columnName 
    Else 
        results = results & vbCrLf & "Error in AddSiteColumn: " & columnName 
    End If 
    
    Debug.Print(results)

End Sub 

After you save the project, go to the task list in SharePoint. On the LIST tab, select the Modify View command. On the Settings – Edit View page, select the Baseline duration field and the Current duration field that the macro added. Figure 5 shows the task list with the two new fields.

Figure 5. Adding fields to a synchronized SharePoint task list

Conclusion

The Project object model can be used with VBA or with VSTO. The Project object model includes seven new classes, 292 new members, and a slew of new enumeration constants that support many new features in Project Standard 2013 and Project Professional 2013, including:

Create new reports that can have tables and charts with task and resource fields, can include Office Art features, and can be both manually and programmatically modified.
Manipulate the Task Path properties to dynamically show how predecessor tasks affect scheduling of a selected task, and how the selected task affects scheduling of successor tasks.
Monitor the Active Cache to show the status of saving, publishing, and checking in a project to PWA.
Work with SharePoint tasks lists in four different ways, to help realize the goal of managing and visualizing all of your work in one place.

VBA-based and VSTO-based development can customize and integrate Project with a wider range of solutions than ever before possible.

Additional Resources

For videos and training for Project, see the following:

Module 9, Project Professional 2013 training for developers, on the Office 2013 training for developers page
Register for Project Ignite

The Project team periodically adds new articles to the Project Blog. For more information about new features in Project and Project Online, see the following:

The Project VBA Help topics are located in the MSDN online library. Many of the topics for new members are incomplete in the Project 2013 Preview SDK; the topics will be completed for the RTM publication of the Project 2013 SDK. See Welcome to the Project 2013 VBA developer reference.

For links to the Project 2013 SDK and many other resources, see the Project for developers page on MSDN at http://msdn.microsoft.com/project.

Change shapes in Visio 2013

E. Schmidt — Thu, 23 Aug 2012 18:43:00 GMT

Visio 2013 introduces a "Change Shape" feature that enables you to swap out a selected shape or group of shapes in the drawing with another type of shape. The new shapes can retain the position, connections, formatting, shape text, and/or shape data of the originals.

For example, take a drawing like the following simple flowchart.

With the Change Shape feature, you can change the Process shape labeled "Make a decision" to a Decision shape with a single button press:

Rather than using another shape in the drawing, the Decision shape that replaces the Process is a new instance of the Decision shape from the Decision Master shape. It retains the local formatting values of the original Process shape (that is, values that the user or the program changed after the shape was dropped), including the fill color, the shape text, and the bold applied to the word "decision."

If another shape in the drawing references the original shape in a formula, Visio restores this reference after the operation and updates the reference to point towards the resulting shape. The same goes for hyperlinks: links that target the original shape will be updated to point towards the resulting shape. Connections, callout associations, shape comments, container membership, and list membership are likewise restored.

Note: You can only replace 2D shapes with other 2D shapes (like a Decision shape for a Process shape) and 1D shapes with other 1D shapes (replacing one type of connector with another). You cannot replace a connector with a rectangle, as an example.

For developers, there are two aspects of this feature that are worth examining: first, how to use this feature programmatically using the Visio 2013 APIs; and second, how to build custom shapes that interact predictably with this feature. I will take a look at each of these aspects in turn.

Before I go any further, however, I should clarify some terminology. First, I will call the shape that is being removed from the drawing (and replaced by another) the "original shape." The Master shape that is being used to replace the shape on the drawing is called the "replacement shape." Finally, the shape that remains on the drawing page after the operation has completed is called the "resulting shape."

Using the Change Shape APIs

The Visio 2013 object model includes two new APIs that implement the Change Shape feature: Selection.ReplaceShape and the Shape.ReplaceShape methods.

Using Shape.ReplaceShape, the procedure described previously could have been written as a simple VBA macro, as shown in the following code sample.

Sub ChangeToDecisionShape()
    Dim vsoPage As Visio.Page
    Dim vsoShapes As Visio.Shapes
    Dim vsoStencil As Visio.Document
    Dim vsoMaster As Visio.Master
    Dim vsoOriginalShape As Visio.Shape
    ' Get a reference to the currently active page in Visio.
    Set vsoPage = Application.ActivePage
    Set vsoShapes = vsoPage.Shapes
    ' Get a reference to the Master to use as the replacement shape.
    Set vsoStencil = Application.Documents("BASFLO_U.VSSX")
    Set vsoMaster = vsoStencil.Masters("Decision")
    ' Iterate over every shape on the page to find the shape
    ' to replace by testing the text of each shape.
    For Each vsoOriginalShape In vsoShapes
        If (vsoOriginalShape.Text = "Make a decision") Then
           
           'Replace the shape using the default behavior.
            vsoOriginalShape.ReplaceShape vsoMaster, _
                VisReplaceFlags.visReplaceShapeDefault
        End If
    Next vsoOriginalShape
End Sub

In the previous code sample, the Shape.ReplaceShape method is called on the original shape. The method takes a Master object as a required argument, which represents the replacement shape. Although not used in the code sample, the method returns a Shape object that represents the resulting shape.

The ReplaceShapes method has an optional parameter, ReplaceFlags, which must be a constant from the VisReplaceFlags enumeration. Passing in an argument for the ReplaceFlags parameter allows you to control the values of the resulting shape more finely. For example, you could pass in the visReplaceShapeLockText flag (2), which would assure that the original shape's text is overwritten by the text of the replacement shape.

The Selection.ReplaceShape method behaviors similarly to Shape.ReplaceShape, with a couple of differences. All shapes contained by the selection are changed to instances of the replacement shape and the return type from the method is an array of shapes.

If you call the Selection.ReplaceShape method and some of the selected shapes cannot be replaced (have a LockReplace cell value of '1' - see the section that follows), the method will replace only the shapes in the selection that can be replaced. The method then returns an array that contains only the resulting shapes from successful shape replacement.

Using the ShapeSheet to specify Change Shape behaviors

Visio 2013 includes several new ShapeSheet cells for working with the Change Shape feature: the LockReplace cell, the PageLockReplace cell, the
DocLockReplace cell, the ReplaceLockText cell, the ReplaceLockFormat cell, the ReplaceLockShapeData cell, and the ReplaceCopyCells cell.

The LockReplace cell is simple in that it determines whether a shape or Master shape can be used in a change shape operation. If the cell is set to 1 (true), the shape cannot be replaced or be used as a replacement shape. If you select a shape on the drawing page that has its LockReplace cell set to true, the Change Shape button in the Editing group on the Home tab is disabled.

The PageLockReplace and DocLockReplace cells behave similarly to LockReplace: when set to 1 (true), shape replacement operations are disabled. When disabled, the Change Shape button is dimmed when the page (PageLockReplace) or document (DocLockReplace) is active.

The following cells affect the output - the resulting shape - of a Change Shape operation. Only the values of the replacement shape, the Master shape being used to replace the shape(s) in the drawing, are used:

The ReplaceLockText cell determines whether the text contained in the replacement shape overwrites the text of the shape being replaced. If this cell is set to 1 (true), any text contained by the replacement shape is copied to the resulting shape in the drawing.
The ReplaceLockFormat cell determines whether the formatting values - fill formatting, line formatting, quick style, theme properties, gradients, bevels, reflection, soft edges, shadow, etc. - of the replacement shape overwrite the values o the original shape. If this cell is set to 1 (true), the formatting values of the replacement shape are copied to the resulting shape in the drawing.
The ReplaceLockShapeData cell determines whether the shape data contained in a replacement shape overwrites all of the shape data of the original shape. If this cell is set to 1 (true), all rows and values of the shape data section of the replacement shape are copied onto the resulting shape. Any local values from the original shape are discarded.

The ReplaceCopyCells cell is a little more complicated than the other cells. The ReplaceCopyCells value of the replacement shape indicates a list of other ShapeSheet cells that are copied from the original shape to the resulting shape. The cell must contain a DEPENDSON function call where each argument in the function is a reference to another ShapeSheet cell.

Here's an example of how its used: A Master shape has its ReplaceLockFormat cell set to 1 and tis ReplaceCopyCells cell set to DEPENDSON(FillForegnd). If used as the replacement shape in a Change Shape operation, the resulting shape will take on al the formatting values of the replacement shape except the fill color (the value set in the FillForegnd cell).

Office Developer Blog

Introducing WOPI

Fundamentals

Host Requirements

CheckFileInfo

GetFile

Loading a WOPI Application

WOPI Discovery

Wrapping the Application URL

Putting It All Together

JavaScript API object model maps updated for attachment support in mail apps!

Working with tracked changes and comments programmatically in Word 2013

APIs for displaying tracked changes and comments in Word 2010

New APIs for displaying tracked changes and comments and filtering reviewers in Word 2013

RevisionsFilter members

Comment members

When should I choose to create a mail app versus an add-in for Outlook?

Contents:

An introduction to the apps for Office platform

Architectural differences between add-in model and apps for Office platform

Add-in model

Apps for Office platform

Main features available to mail apps

Major objects for mail apps

Reasons to create mail apps instead of add-ins for Outlook

Reasons to choose add-ins

Conclusion

Further references

Apps for Office and mail apps

Legacy Outlook object model and APIs

What's new for developers in Visio 2013?

New file format

Themes

Change Shape

Shape effects

Commenting

Coauthoring

Customizable image clipping

Relative geometries

Support for Business Connectivity Services (BCS) data

Improvements in Visio Services

Duplicate page

Additional resources

What’s new in Access 2013 for developers

Bring Access apps to the cloud with Office 365

Access apps are SharePoint apps

SQL Server back-end

Polished user experience

Office 2013 Developer Content Landscape

Less is definitely more

Farewell “wall of links”

Is that the MSDN Library?

Enough about docs, what about code samples!?

Who moved my cheese?

Speaking of feedback…

Hello, "wall of links"

Conclusion

What's new in Excel 2013 Preview for developers

New features for developers in Excel 2013 Preview

Apps for Office

New worksheet features

Quick Analysis

New data sources

DataModel object model

Create independent PivotTables and PivotCharts

Single document interface

Conclusion

Additional resources

What's new for developers in the new Project desktop (besides task pane apps)

New reports

Task Path formatting

Waiting for a cache job to complete

Working with SharePoint tasks lists

Conclusion

Additional Resources

Change shapes in Visio 2013

Using the Change Shape APIs

Using the ShapeSheet to specify Change Shape behaviors