Sunday, December 10, 2017

Application lifecycle (ALM) APIs for SharePoint Framework solutions and SharePoint add-ins

Thank you, Microsoft, for finally publishing APIs which we can now use to manage the application lifecycle for ours SharePoint Framework solutions and SharePoint add-ins.

Until the end of November 2017 it was very tricky to manage the application lifecycle for SharePoint solutions, since some of the possibilities available weren't supported by Microsoft. If you've worked with SharePoint web services to reach your goals, you know how vulnerable a system becomes to changes caused by Microsoft. But now… it is past!!!

In this blog post I'll present and explain you the new ALM APIs.

At the end of the day it is just about executing REST calls


It doesn't matter if you use CSOM or PnP PowerShell for working with the new APIs, because they all are just using REST behind the scenes. These are the benefits of working with CSOM or PnP PowerShell:

  • you don't need to take care of inconvenient things like passing the REQUESTDIGEST while executing the calls.
  • you don't need to remember the REST APIs or build complex strings/code.

APIs' scope


The new APIs were designed to act in different scopes:

Site level operations: These APIs will execute requests against the site collection which you requested client context for.

App catalog operations: These APIs will execute requests against the app catalog. Independent from the generated client context.

APIs' overview


Site level operations:
Description API
Get available apps _api/web/tenantappcatalog/availableApps
Get available app by id _api/web/tenantappcatalog/availableApps/GetById("")
Install available app _api/web/tenantappcatalog/availableApps/GetById("")/Install
Update available app _api/web/tenantappcatalog/availableApps/GetById("")/Upgrade
Uninstall available app _api/web/tenantappcatalog/availableApps/GetById("")/Uninstall

App catalog operations:
Description API
Add app to app catalog _api/web/tenantappcatalog/Add
Deploy available app _api/web/tenantappcatalog/availableApps/GetById("")/Deploy
Retract available app _api/web/tenantappcatalog/availableApps/GetById("")/Retract
Remove available app _api/web/tenantappcatalog/availableApps/GetById("")/Remove

APIs for site level operations in test


Instead of directly working with REST calls, I'll demonstrate the new APIs using PnP PowerShell.

Get available apps:


Returns all apps which are available for your site collection.

Get-PnPApp | Format-Table


Get available app by id:


If the app is available, it returns the searched app.

Get-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811 | Format-Table


Install available app:


Installs an app to the current site collection. If the app requires admin permission to install, the API will automatically handle the approval process.

Install-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811

After running the API, you can see in the site contents of your site collection that the app is getting installed.


Update available app:


If a new app version is available, it updates the app on the current site collection.


Running the API below will update the app from the version 1.0.0.0 to the version 1.0.0.1.

Update-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811

After running the API, you can see in the site contents of your site collection that the app is getting updated.


Uninstall available app:


Uninstalls an app from the current site collection. It completely removes the app from the site collection, without moving it before to the recycle bin folder. So wonderful!!!

Uninstall-PnPApp -Identity 19109eba-5efd-4e1e-a48e-eadf87f6d811


APIs for app catalog operations in test


Instead of directly working with REST calls, I'll demonstrate the new APIs using PnP PowerShell.

Add app to app catalog:


Uploads an app file to app catalog. Using the REST API you can work with binary data and pass the parameter override. At time of this written, the PnP method Add-PnPApp works with a file path and automatically set the override parameter to false. If the file already exists in the app catalog and the override parameter is set to false, you'll get an exception.

Add-PnPApp -Path C:\search-web-part\search-web-part.sppkg | Format-Table


This API returns the app unique ID which is not the product ID. The unique app ID is stored in the hidden field UniqueId of the list Apps for SharePoint. The picture below shows the new uploaded app. Notice that the file is still no deployed.



Deploy available app:


Deploys and trusts an available app. It is possible to set the parameter SkipFeatureDeployment. Although the PnP method is called Publish, it does the right job J

Publish-PnPApp -Identity 38740267-e8a5-4179-9725-fc5155d19447


After running this API, the app is available in the "add an app" page for installation.


Retract available app:


Retracts the available app without removing it from the app catalog. Although the PnP method is called Unpublish, it does the right job J

Unpublish-PnPApp -Identity 33aad64c-fe65-4f39-b873-5349632957fe


After running this API, the specified app is no longer available for installation.


Remove available app:


Removes an available app from the app catalog. Notice that installed apps will not be uninstalled, but as far as I know, client side web parts will no longer work.

Remove-PnPApp -Identity 33aad64c-fe65-4f39-b873-5349632957fe


Summary


We finally have stable and supported APIs for managing the application lifecycle of SharePoint solutions. Processes have become faster and are easier to automate. Many thanks to everyone involved in developing these APIs.

2 comments:

  1. Hi,

    Nice post.

    Have you done any testing using 'Unpublish-PnPApp' with tenant scoped SPFx web parts? From my testing if I run 'Remove-PnPApp' then the web part is removed from the app catalog and users can't add this web part anymore and all instances of this web part are still on the page but hidden.

    If I run 'Unpublish-PnPApp' the app catalog settings are updated but all web part instances are still available and users can still add new instances of this web part.

    Cheers,

    Ray

    ReplyDelete
  2. Hello Ray,

    thanks for your comment and your valuable tests!

    I tested again the API with tenant scoped SPFx web parts and experienced the same behavior as you. The web part instances don't get removed from the pages' content. After running Remove-PnPApp, I ran Add-PnPApp than Publish-PnPApp and the web parts were back to the pages.

    I like Remove-PnPApp's behavior since data aren’t getting lost. In my opinion, Unpublish-PnPApp should stop the possibility of adding new instances of retracted web parts.

    Cheers,

    Jarbas

    ReplyDelete