Wednesday 23 May 2018

Updating your SPFx web part/extension – the nuclear approach

SNAGHTML2356ad3One situation that Office 365 and SharePoint developers will encounter more and more is the need to upgrade an existing SharePoint Framework (SPFx) project to a later version of the framework. SPFx gets updated fairly regularly, and as more and more development moves over to this approach, you’ll find that when you go back to enhance or maintain an existing solution, more frequently it’s SPFx code that you’re going back to. When you do, you have a decision – should you upgrade the SPFx version of the web part/extension while you’re making your code changes? Of course, you don’t have to (and maybe there hasn’t even been a new version of SPFx since your original release). But maybe you want to take advantage of some newer SPFx features – or maybe you just want to stay current and benefit from some possible performance or developer enhancements.

The pains of upgrading a project

Unfortunately, updating an SPFx application is often not as easy as it should be – you’ll often run into build errors when you run a gulp serve or gulp bundle until you’ve got everything straight. Most of the guidance you’ll see advises you to use ‘npm outdated’ to identify packages with newer versions, and then updating them individually (with npm install [package]@[version]) – indeed the SPFx docs have a useful page on this approach at Update SharePoint Framework packages. I recommend always trying this process first. However, I find that sometimes you need some extra steps too. I upgraded a project yesterday and ended up using a slightly different process to get to a working build, so I thought that would be a good topic to briefly discuss.

One issue you can hit with the npm outdated/npm install [package]@[version] approach is if there are new or removed packages which make up the new SPFx version you are moving to. In this case, simply updating your existing packages isn’t enough.

The nuclear approach – a recipe

Sometimes the right thing to do is to be a bit more drastic. You could certainly create an entirely new SPFx application and merge your code into that – but that’s too drastic. It’s a lot of work, and I’ve yet to see a case where it’s actually necessary. The process below is somewhere in between – it’s based on creating a new SPFx project on the latest version, merging the package.json files to ensure you end up with all the right packages at the expected versions and then rebuilding the node_modules folder based on that. I’d use it when:

  • Updating existing packages using npm outdated/npm install@version doesn’t work (still getting build errors)
  • I was confident the previous build is in source control, including a package-lock.json file (so I could revert everything back if needed)

The process would be:

  • Install the latest Yeoman generator version
  • Create a new temporary SPFx app (web part or extension, to match the application you’re updating)
  • Merge the package.json from the temporary app into yours
    • The aim is to have all packages needed – all the SPFx packages for the new framework version, AND any other packages you have previously installed for this web part/extension
  • Remove any package-lock.json or npm-shrinkwrap.json files from local directory (but do not remove from source control - you still might need to go back to a previous build)
  • Delete everything from node_modules
  • Run npm install
  • Make any tweaks to tsconfig.json if needed - newer SPFx versions sometimes need a change here too
    • Build errors should point you to the solution for these. When running an upgrade to SPFx 1.4.1 recently, I needed to add an entry in my “lib” section for “es2015” – but look for build errors for the specific tweak you need
  • Run gulp clean (to delete previous build outputs)

    At this point, you should have a working build again when you run gulp bundle or gulp serve. If you do, and you’re comfortable everything is working, you should:

    • Commit to source control
      • Ensure your package-lock.json file is included – this represents the node_modules tree for this build, and you need it to recreate the build (since you won’t be checking-in the node_modules folder itself)
    • Continue making the code changes you actually came here to do :)

      Other notes

      • Extra care needs to be taken for on-prem SPFx projects. The npm repository holds latest versions of packages, but remember that when you’re on-prem you’re frozen at a certain version of SPFx packages (not what the npm repository holds as the latest version). So, your package.json file needs to reflect the appropriate versions for your on-prem build.

      Good luck!

        Thursday 10 May 2018

        Licensing for push notifications in PowerApps/Flow

        If you’re doing more with PowerApps and Flow in Office 365, sooner or later you might hit an interesting question if you want to use a premium connector – just who needs the P1 or P2 license? Premium connectors require extra licensing to what comes with Office 365 E1, E3 and even E5, and the licensing requirements can vary depending on the connector and how it is used – meaning costs can vary too. The one I’m focusing on here is push notifications – let’s say you’re building a PowerApp or using a Flow, and you want to send a notification to a mobile device when something happens (i.e. an alert on the device, rather than an e-mail or SMS). In this case, you’ll most likely find your way to the PowerApps push notification action (a premium connector). Whilst there is also a Flow push notification, that one can only send to the Flow owner – but frequently, you want to send the notification to some kind of approver or recipient, not the person who created the Flow. So, the PowerApps Notification is probably what you need – but don’t be fooled by the name. This thing isn’t constrained to use with in a PowerApp (e.g. a button click) - it can also be used within a Flow (e.g. when the Flow gets to a certain stage). Here’s what it looks like there:

        PowerApps notification - in picker


        Who needs the license?

        So the question you get to when you need to notify many people is “who exactly needs a P1/P2 license?”

        • Is it just the user/sender? (which in this case, would be the user who the Flow runs as)?
        • Is it every recipient?
        • Is everyone who could be a recipient?

        It’s an interesting one and I couldn’t find the answer in the documentation. We had the situation come up in some work for a client, so I reached out to a friendly contact in Microsoft (thanks Dan!), and he did some digging internally to find out.

        The answer

        In fact, it depends on how your Flow is triggered – since it can be done by a user action, or indirectly through an event:


        Who needs the license

        License type required

        Manually Any user of the app which triggered the Flow (e.g. your PowerApp, Flow button or other app)
        • Flow is triggered by PowerApp –> PowerApps P1
        • Flow is triggered by Flow button –> Flow P1
        By an event (e.g. new item in a SharePoint list, new file in OneDrive etc.) Just the Flow author
        • P2 (Flow) – * but see my caveat below

        It’s worth being aware that these P1 and P2 additive licenses come in both PowerApps and Flow flavors – but PowerApps licenses always include Flow capabilities. PowerApps licenses are correspondingly more expensive since you unlock the whole, um, power of PowerApps too. Broadly the idea is that:

        • Users creating “basic” PowerApps (e.g. canvas apps) need a P1 license - currently $7 per user per month for PowerApps P1
        • Users creating “advanced” PowerApps (e.g. model-driven apps, business process flows, entities in CDS etc) need a P2 license (currently $40 per user per month for PowerApps P1

        For many PowerApps, that will mean the P1 license is sufficient though (in my view).

          Also note that if you’ll only use Flow and never PowerApps, maybe you just need Flow P1/P2 licenses. These are much cheaper than PowerApps P1/P2 licenses (currently $5 per user per month for Flow P1, $15 per user per month for Flow P2).

          * By the way, with reference to my table above, my understanding is that if you have a PowerApp which adds a SharePoint list item (or file to OneDrive etc.), then a PowerApps license is required for the user – not just a Flow license. After all, the event is really being triggered by the PowerApp – rather than it being a purely indirect thing, from a manually added list item/file for example.

          If you need to know up-to-date pricing, see the PowerApps plans pricing and Flow plans pricing pages. Another good resource (along with licensing examples) is the PowerApps licensing overview page – this has some great info, but it just didn’t have the detail I needed around premium connectors and recipients.

          Other scenarios

          Maybe you want to use the PowerApps push notification purely within PowerApps (i.e. not in Flow). In this case, there are similar considerations:

          • Makers of the app which has the Push Notifications connection need a PowerApps P1 or P2 license (as you’d expect)
          • Users of the app need a PowerApps P1 or P2 license (also as you’d expect, since this is a premium connector remember)

          But there’s an interesting possibility if it’s a different PowerApp which receives the notification (in the PowerApps world, it’s possible for one app to send the notification and another to be receive it). In this case:

          • Users of the recipient app do NOT need a PowerApps P1/P2 license – their Office 365 license is sufficient
            • (This is because this app does not use the Push Notifications connection)

          So, that’s definitely a trick which might be helpful, so long as the implementation details are OK with your requirements (i.e. you are able to split your app in this way).


          There are definitely a few complexities around licensing of PowerApps and Flow, and as you build more solutions with them there are more scenarios to consider – in fact, . I’m really not trying to be the man to answer all your licensing questions here though :) You’ll need to contact Microsoft if the above links don’t have the detailed information you need, as they’ll give a better answer than I ever could. However, I thought some folks might run into the same questions that I did, and I figured some of this info needs more prominence.

          Have fun building your solutions!