Significant productivity enhancer: Debugging and Developing O365 Add-Ins using Firebug Lite

In this article I will show you how to add a web based console capability Firebug Lite to your Office Add-Ins. This is particularly helpful when debugging Client Side applications.

Introduction

Firebug is a Firefox plugin and was one of the original developer tools of actual use and power. It has since been superseded by all the powerful work the Chrome Dev team have put into Chrome developer tools, but I still like it (old habits die hard).

Firebug Lite is a browser agnostic JavaScript version of this and provides a subset of functionality, directly in the browser.

This is especially helpful in the case of Client based Add-Ins. Client based Add-Ins use an embedded Internet Explorer experience and the Developer Tools are unavailable. There are ways to debug Add-Ins through Visual Studio, but seeing as I have no intention of writing a line of C#, that does not help me.

Firebug Lite

Adding Firebug Lite to your Office Add-in could not be simpler. Add the following to your application (be warned there are some issues with using it in conjunction with AngularJS).

The Firebug Lite console itself is 300px tall so ideally you need to make your Add-In 450px tall to be able to see it working

    <script type="text/javascript" src="https://getfirebug.com/firebug-lite.js">
        {
            overrideConsole: false,
            startInNewWindow: true,
            startOpened: true,
            enableTrace: true
        }
    </script>

That’s it. !

The JSON parameters are optional and not necessary if you are working in Outlook or OWA. They are necessary in the Word/Excel/PowerPoint clients though as the F12 key have an assigned function. These extra parameters open the Firebug Lite client in a new browser window. Still works, just not embedded directly inside of the Add-In.

From the documentation (Feb 2016 – Firebug 1.4 is live)

1.3. What’s Not in Lite?

Some features are not included in Firebug Lite 1.3, but due the new core that supports code sharing from Firebug, are likely to be included in the Firebug Lite 1.4 version:

  • Live editing for all panels
  • Layout Side Panel
  • Context menu options
  • Tooltips (to show colors and images)
  • Search feature

Other features though are too dependent in browser internals and will not be supported (at least in a near future*), such as:

  • Javascript debugger / Javascript profiler
  • Net panel / HTTP and XHR monitor
  • Access to restricted URI resources
  • Highlight HTML changes

*Discussions about remote debugging indicates that should be possible to support JavaScript debugging in browsers like Google Chrome and Opera in the future.

Looking at the Add-In

I used the basic example from napacloudapp and a stripped out the HTML on the front page – this gave me the ability to still run the Office.initialize in the app.js (necessary to deploy an Office Add-In). Initializing this Office object also gives me programmatic context to the rest of the “host”, be in Outlook or Excel.

f12

Having a console inside of the Add-In gives us a significant amount of flexibility for testing and seeing what is going on. To activate it – focus on the Add-In and hit F12. If you are outside of the Add-In in the browser this will trigger the normal browser developer tools.

In the browser:

f1

In the Outlook client

f2

In Excel

f3

Developing Add-Ins using Firebug Lite?

Oh Yes! Let’s be honest – we are all lazy and would rather not have to go back and forth deploying Add-Ins to test our code – with Firebug Lite now we can start to write the code which will ultimately be deployed as part of our applications. For example:

Got to the Office JavaScript API model page – https://msdn.microsoft.com/en-us/library/office/fp160953.aspx and open the API model on ZoomIt

f4

We can start to see the semblance of the document model for adding data to an excel cell. Let’s see if those objects exist – I can see from the ZoomIt that we can go:

  • Office
  • context
  • document

In the Firebug Lite console (in Excel) type out Office.context.document – and we can see an object exists

f5

type in any old crap and you get just that 🙂

f6

In this manner, not only can we start to test that our code works, we can also do it without having to keep redeploying the Add-In. Once we are comfortable with the code, we can move it to the real code base – this is a real productivity enhancer, especially when you are just getting into Office Add-In JavaScript development.

Building your first Excel Add-In example without deploying anything

Looking at the Build your own first Excel Add-In page we can use some of their code directly inside of the Firebug Lite console.

Click on the enlarge box in the console top right

f7

Then the Up Arrow bottom right – this will give us a pop-up window with a console we can actually read and use

f9

Copy the code from the Excel.run part of the code from the Excel page example and paste it into the right hand Firebug Lite pane

f10

and “Run” (or use CTRL-Enter)

f11

How freaking cool is that !!!!!!!! And we never had to deploy an Add-In to test that out.

Conclusion

Adding Firebug Lite to your Add-Ins during development will be an enormous time saver for you. It will allow you to initially develop you code without having to go through repeated deployments. It will also allow you to debug your code (more on that in later articles) by manipulating your JavaScript functions once they are actually deployed.

In another life I have been using Firebug Lite embedded inside of XULRunner browser, running inside of Eclipse (don’t ask) and it is very cool – more to come on that soon

 

Advertisements

O365Token GitHub project – Authenticating Office Add-Ins to Azure AD using only JavaScript (No C#)

In this article I will discuss the first iteration of the new GitHub project I created for the O365Token generation. The project is a generic code sample which can be added to your Azure AD websites and ultimately used to create a secure sample Add-In. We will look at how to take the sample code in the GitHub repository and deploy it to your environment.

Introduction

In the previous article I showed an alternate method for creating an authorization token from within the Outlook client. After receiving encouragement from Simon Jaeger I decided to continue and make this into something to hopefully collaborate on with others.

Github O365Token

The repository is hosted here – https://github.com/markyroden/o365Token – clone it to wherever you want (I use Webstorm IDE) and follow these steps:

  1. Using the instructions posted here, create your Azure AD site and make the redirect URL match the sample/index.html path.
    e.g. https://yoursite.azurewebsites.net/sample/index.html
  2. Modify the following token parameters in app.js to match your application
    • clientid
    • resource
  3. Run

 

How it works

In this version of the token generation I combined a number of aspects of the code and streamlined them to work as one file. There only 3 files (not including CSS) involved in this O365Token sample.

o1

  • Index.html
    • The place holder for the Add-In
  • Home.js
    • Determines if the code has been opened in an Add-In or as a popup token generator
  • App.js
    • If the page opens as an Add-In it causes the pop-up token generation window
    • If the page has been opened in the add-in it acts as the recipient of the token generated in the popup

Combining code

To simplify deployment and maintenance over time I decided it was easier to write the token generation code into the add-in itself. This also helps to reduce the number of changes necessary

Index.html

Index.html is really just the placeholder for the sample code – all that happens is that it ends up displaying the token once it is generated.

Home.js

We are using the same /index.html as the Add-In and the popup token generation window as well. The Home.js file determines if index.html has been opened as an Add-In and if so, calls the app.getToken code. If index.html has been opened in the browser the app.returnToken is called.

o2

App.js

App.js has three functions:

  • app.getToken
    • Called when index.html as been opened in the Add-in
  • app.returnToken
    • Called when index.html has been opened in the popup
  • app.tokenCallback
    • Called from the app.return once a Token has been generated. This is where your actual Add-In code would live in the future.

o3

For the Future

I have a feeling that this ought to be an Angular module. I can see a lot of Add-In code being written as an Angular app and as such it would make sense to include the app.requestToken and app.getToken as something which can be hooked easily into any other angular app.

 

 

 

 

How the example O365 Authorized CORS application works.

In this article we will look into how the example provided on the Microsoft HowTo site works and then discuss some practical implementations thereof.

Introduction

In the previous article (https://xomino365.com/2016/02/01/using-azure-ad-to-allow-authorized-cors-access-to-o365-data/) we looked at how to create an Azure AD application and securely access O365 data from within another web domain. The Microsoft How to site provides and example application on how to get data from your One Drive. But in this case we are going to look at how to get data from a SharePoint site collection.

The basic site

The site does have a good working example, you can copy and paste the code. What I wanted to show here was the end result and how it works. I modified mine slightly to pull data from a SharePoint list rather than OneDrive but it all works.

Starting at the site root (which is anonymously accessible), we click the Get Token button.

a13

The application then makes a request to the Azure authentication pages


aa2

Combining the values added to the example application we get the following values added to the Query_String of the address. These values must coincide with the values in the application manifest.

client_id=xxxxxxxx-xxxx-xxxx-xxxx-dca7fd30e1cb
redirect_uri=https://xomino365.azurewebsites.net/o365/demo.html
resource=https://xomino.sharepoint.com
response_type=token

If the user is not signed in then they are asked to do soaa1

Once successful authentication has been achieved the login end point returns the user to the “redirect_uri” and tacks the OAuth token onto the end of the returned URL

aa3

The application also sets a cookie – this is the Authentication cookie which says that you are logged into O365 – but that is very different from the Authorization (OAuth) token which is currently in the URL. You will also note if you look carefully that there is an expiry time in the Query_String parameters (3599) so assuming this is in second and not minutes – the OAuth token is only good for 60 minutes….

The example application waits for the response and if it find an access_token in the URL it parses it, and then moves it into the OAuth Token field

aa4

In this example the Endpoint is a hard coded URL which represents the Root folder of the root site in my O365 site. It is an out of the box REST URL.

https://xomino.sharepoint.com/_api/web/lists/getByTitle(@TargetLibrary)/RootFolder/files?@TargetLibrary=’Documents’

If we pull that up in a new tab we get the following

aa5

The reason I am getting this is because I have not actually authenticated with xomino.sharepoint.com at this time – I have logged into Azure AD. This is really interesting because if I run the example right now it will work – AzureAD has given me enough permission to make the request but not to go directly to the site. I say interesting, but it is actually slightly annoying from a developers perspective. Every time a user moves around O365 they have to go through the Single Sign on process – which is very cool, in that it works, but not the ideal user experience.

If I open https://xomino.sharepoint.com in a new tab – I get the cycle login screen and my SharePoint sites open automagically – SSO works. When I go back to the REST endpoint again now I get an authorized page.

aa6

The only reason I even bring this up is to show that Authorization is not the same as authentication. The Access_Token actually grants us permission to retrieve data and interact with the SharePoint site, even though technically we are not logged into it (yet). Pretty smart to be honest!

But this is XML – old school ATOM service. – we want new school JSON and the example app obliges.

Getting JSON Data

When the demo site realizes there is an access_token in the URL it hides the GET TOKEN button and shows the Make CORS Request button.

Clicking the Make CORS request button creates a very specific AJAX request – let’s look at the code directly.

  var xhr = new XMLHttpRequest();
  xhr.open("GET", getEndpointUrl());
  xhr.setRequestHeader("authorization", "Bearer " + token);
  xhr.setRequestHeader("accept", "application/json");
  xhr.send();

In this case the token is the very long access_token from the URL and the getEndpointUrl() is the xomino.sharepoint value in the EndpointURL field.

Once the AJAX call is made you can see what happens in the transfer using the browser developer tools (in this case firebug). The Accept Header is what will cause the O365 server to respond with JSON and not ATOM XML.

The Request Headers

This is what is going out to the O365 servers – as you can see the Accept Header and the Authorization header have been set.

aa7

The Response Headers 

The critical thing to note here is that the Access-Control-Allow-Origin Header = “*” this allows the xomino365.azurewebsites.net domain to successfully request data from the xomino.sharepoint.com domain.

aa8

The response itself

The response is a JSON data object

aa9

making it more readable we can see the object is an array of “results” within d. Each item within the array represents the verbose detail of each file within the site collection.

aa10

Conclusion

 

In this article we have looked in some detail at how the Microsoft HowTo website example works and how the authorization/authentication mechanisms play with the AJAX requests to retrieve data from one domain into another.

In a future article we will look closer at what happens when we start to play with these requests and try and break the system…

 

Using Azure AD to allow Authorized CORS Access to O365 data

In this article I will show how to to create an Authenticated way to access O365 data from an Azure website. This method creates the necessary CORS headers to allow cross domain AJAX data traffic.

This whole article is based on the following site Create JavaScript web apps using CORS to access Office 365 APIs. I wrote this article because it was not at all clear to me from the Microsoft posting how everything fit together and I had to go through it a number of times to figure it out.

The article and screenshots are accurate as of 31 Jan 2016 and may change over time.

Setting up Azure AD as your O365 directory

For a more in depth description of how to use Azure AD as your directory for O365 check out this excellent support article. This is also a very helpful link – What is Azure AD Directory? it will help you describe how to assign your Azure AD to your MS Cloud account.

Once you have the Azure AD directory set up you can manage it though the Azure portal. In there you can find your directory by scrolling to the bottom on the left and selecting Active Directory.

a1

 

Adding a new application

Select Application at the top of the screen and select Add at the bottom

a2

Add an application my organization is using

a3

Give it a name

a4

Give it a sign in URL and and APP ID URI (“The App ID URI is a unique identifier for Azure AD to identify your app“)

a5

For the sake of this demo the above values are arbitrary and make more sense in context of the overall configuration.

a6

woo!

Select Configure at the top and look at what was created

App configuration

The configuration section shows all the information you need, and you application needs to be able to access O365 data from your application. This does NOT have to be an azure hosted application. I am just using Azure for the sake of convenience.

The name and Sign-on URL are carried over – the Sign in URL is actually merely for convenience, you don’t need to use it as far as I can tell.

a7

The Client ID – this is the single most important piece of this puzzle – this key holds the application together. You send it as part of the request for Authorization token. With it O365 determines the what who why when for security.

a8

In the Single Sign on section below we see the App ID and the Reply URL (which is the Login page URL)

a9

We are going to change the reply URL to be the App ID for convenience. Don’t forget to save!

a10

We have to give the demo.html application access permissions inside of O365

Adding permissions to applications

Selecting Add Application brings up all the applications being managed by Azure AD directory.

a11

We are going to change permissions to access SharePoint online. Select and continue..

Select the delegation permissions. In this case I blanket added all permissions just for the sake of not having to explain everything. You probably want to make sure that you understand what permissions you are exactly giving the user. Remember once you create the authorization, users can write their own JavaScript and do not have to do what you want them to, they can do what you authorize them to do.

a12

and don’t forget to save…..remember this, otherwise you will waste time wondering why you are an idiot….

Changing the manifest

The manifest file is available at the bottom of the screen – selecting the link will download the text file.

a15

Looking at the manifest we see the true textual representation of the configuration. The important part here is to allow the application to allow the OAuth token to be returned to the user so it can then be used for further data requests. If you do not make the following change the example application (see below) will return the following…

error=unsupported_response_type&error_description=AADSTS70005:+response_type+’token’+is+not+enabled+for+the+application
Trace+ID:+f4354ef3-de41-4909-a829-0811b0bc0407
Correlation+ID:+93f60ed1-f703-4b5d-b0fb-bebc94192f3b
Timestamp:+2016-01-31+03:36:57Z”

To correct fo this issue, change the following line to true

“oauth2AllowImplicitFlow”: true,

Save the manifest and upload it again.

Creating an application

Following the methodology from the previous article, I created an Azure HTMl5 app with source control integration and loaded the example files up to the demo.html page.

The demo Application

The end product looks like this.

a16

Click the button to get the OAuth Tokena17

The Token is returned as part of the URLa18

Clicking the CORS Request button collects data from the default site collection on the https://xomino.sharepoint.com O365 account.

We do not need to make this a 2 step process though, in later article we will show how to create the results in the form of an angular ui-grid

a19

Conclusion

It is a little convoluted to create and set up an “Application your company is working on” and make it use O365 Authorization and Authentication. But once you go through it the first time it becomes relatively east to remember.

We were able to request O365 data on https://xomino.sharepoint.com from a site not in the same web domain, https://xomino365.azurewebsites.net

This is the first example and I will be writing more about how it all fits together in the future.

 

 

 

 

 

 

 

 

 

 

First look at the Microsoft Graph API

Last week Microsoft announced the new https://graph.microsoft.io/ as the final name and endpoint(s) for what they were previously refering to as the “Unified API”. The idea is that for anything related to Office 365 within your organization, you should be able to get permitted information from the graph through REST APIs. This opens the world of O365 to integration into any other platform.

I started to play with it and here’s a quick overview of what I found – lots to play with!

Authorization

Go to https://graph.microsoft.io/ and click Try the API and Sign in

g1

You will be asked to Accept permission to give the API explorer access to everything that is “you” in O365 – this is no different from going into google developer area and giving it permission to read your email.

g2

For more information on Graph authorization check out the document – more to come on that in later articles me thinks.

This is not the same as how you would have a user grant permission in your app – but works for the example.

The API resource

https://graph.microsoft.io/docs/overview/overview

Having looked through some of the documentation I tried a few examples

https://graph.microsoft.com/v1.0/me/messages

g3

If you Expand the sections yo can see “your email”

g4

Or just as simple you can see some information about my files in One Drive

https://graph.microsoft.com/v1.0/me/drive/root/children

g5

Conclusion

There is an enormous amount of information about “you” and other users in O365 – just waiting to be explored….

g6

Two ways to remove a Napa developed Office Add-in

In this article I will show the two methods available for removing a Napa developers plugin from your mail file.

Introduction

As I was developing some Add-ins using Napa I unwittingly deleted them from my dev site not thinking about the consequences – well then I had to deal with them…..

Deleting a development Add-in

So let’s say we created a new Add-in and you delete it from the Napa interface

j2

and then you realize it is still attached to your mail (doh)

j1

you need to manage you own Add-ins

Managing your own Add-ins

Top right – Gear > Manage Add-ins

j3

j4

Select the one to remove and click on the (-) icon above the grid

j5

And there you have it – pretty simple.

j6

Now here’s the “Better” way of doing it

DON’T delete it from the front page of the napa interface

Within the napa developer IDE for the project, right under the Run Project icon there is a “Retract App” icon – use that instead

j7

So then Jeff still exists in your development IDE but not inside your email. Much more elegant.

Conclusion

In this article we have seen two methods for removing a Napa developed add-in from your email client(s)

 

Creating your first custom Outlook Add-in

In this article we will look at how to modify the sample Add-in app and make it do something other than the sample app.

Introduction

In the previous articles we have looked at how to create a sample app, how it works and how to make it contextual. In this article we will make the sample Add-In actually link to something useful.

Bluemix Websockets chat

A while ago I created a sample websockets chat demo – https://xominosocket.mybluemix.net/. It is hosted on IBM’s Bluemix PaaS cloud and uses Socket.io ontop of a node.js server. The back end application runs an in-memory data cache using Redis.

None of which is anything in the slightest to do with Microsoft! Which is the main reason I picked it (the fact that I am lazy and it was just sitting out there as a great example already has nothing to do with it….)

Modifying the sample app

In this article we are going to make a few simple changes to the sample app Home.html which will make the Bluemix Chat demo appear contextually within a email.

Admittedly this is a bit of a hack but hey – it is just a demo.

  • I removed App.js, App.css, Home.js and Home.css – don’t need them
  • I removed the contents of the Body of Home.html and replaced it with an iframe pointing at the websockets demo.
  • I added a little styling to make it seamless
    and ran it

n9

 

n10

As far as the user is aware – we now have a websockets chat application embedded within their Outlook email. The Websockets chat is fully functional within the context of the email.

n11

Marky’s Use Cases #1: Helpdesk support Add-in

So there is an application for this Add-in technology. A “Contact the Helpdesk” link within a business email which would facilitate pulling up a web chat session with a helpdesk representative. The context of the email from whence it was created could be passed to the helpdesk and they would then be able to assist the user.

How cool is that 🙂

Conclusion

In this article we have seen how to insert a completely non-Office application, contextually within an email which only contains the word websockets.