Organisation Assets Library REST API

SharePoint Online provides a functionality called ‘Organisational Assets Library’ that based on the documentation allows the organisation to store assets like images or photos in easily accessible place. There is a possibility to configure one or more Document Libraries to play a role of the ‘Organisational Assets Library’. The only restriction is that all the libraries need to exist in the same site.

You can manage your organisational assets libraries using Powershell or CSOM – more information in the docs .

Note: to be able to work with Organisational Assets Libraries, first it’s required to enable Tenant CDN.

REST API

However, recently I had requirement to obtain the information about those from SPFx WebPart, so my first steps where to find out how to get those information with REST calls.

To work with the web service, these endpoints need to be used:

    • /_api/Microsoft.Online.SharePoint.TenantManagement.Office365Tenant/SetOrgAssetsLib
    • /_api/Microsoft.Online.SharePoint.TenantManagement.Office365Tenant/GetOrgAssets
    • /_api/Microsoft.Online.SharePoint.TenantManagement.Office365Tenant/AddToOrgAssetsLibAndCdn
    • /_api/Microsoft.Online.SharePoint.TenantManagement.Office365Tenant/RemoveFromOrgAssets

Based on this information I have created a OrgAssets service class that helps work with the endpoints:


Types used by the service:

Note: it might take couple of seconds to view the changes applied after the execution of the request.

Hope it’s going o be useful for you!

Office 365: Taxonomy fields on newly created site

Site creation

Office 365 provides great and really fast way to create a new modern site collection (do you remember how long it took to provision a classic site?). It helps a lot to boost users experience as they can see almost immediate results.

However, in most organizations there is a requirement to execute provisioning of additional assets based on ‘site designes’ or ‘pnp templates’. Recently, I have faced a situation when wanted to apply PnP provisioning template to a newly created site that contained content types with taxonomy fields.

SP Taxonomy fields

Just as a quick reminder, to use taxonomy fields it is required to add 2 special fields to a list/content type. These are:

  • TaxCatchAll
  • TaxCatchAllLabel

Which are lookup fields and point to the TaxonomyHiddenList. You can find deep explanation of those roles in a fantastic article of Andrew Connel Managed Metadata: In Depth Look into the Taxonomy Parts.

In fact, these fields are not created immediately after the sites creation, but are added later. Most probably by a timer job, as they are available on the site more or less after 5-6 minutes after site creation. But why do we have to wait that time to get what we really need?

Taxonomy hidden fields provisioning

After trying few other times to force O365 to provision those fields for me, I have decided – OK, they are not there, so let’s create them. However, to execute provisioning of those fields – we need one prerequisite. As we have already said, these are lookup columns and point to taxonomy hidden list, so we have to be sure that it exists before the provisioning.

We can easily ensure it by activating the taxonomy site scope feature:

After that, we need to get it’s Id and pass it as a parameter to our provisioning template as a parameter. After we can execute the provisioning of required fields:

Here is the content of the provisioning template:

Thanks to this approach, you won’t need to wait till O365 will provision required fields to deploy your stuff. Enjoy!

SP2019 : Upload ClientSidePages

PnP ClientSidePages

PnP Provisioning engine provides a great functionality that allows to create Client Side Pages (modern pages) in PnP Templates. It supports storing in the XML structure the configured page containing web parts and assigned metadata.

The example presented below creates a page containing a two columns with web parts: Text and People.

SharePoint 2019

However, there is a challenge to use this approach when working wish SharePoint 2019 as the Client Side Pages unfortunately are not supported. It can be checked in the implementation of the ClientSidePages handler – the code is not available in on premises build: GitHub: ClientSidePages handler

Recently, I had a task to automate upload of few pages to SharePoint 2019 environment. In case I was not able to use PnP templates – I have decided to use Add-PnPFile:

Add-PnPFile -Path <> -Folder “SitePages”

Below, I present the content of the ClientSidePage that can be uploaded to SitePages library. The page contains 2 webparts – Text and Twitter.

In the content, you can also find the example – how to assign the metadata directly in the file.

I hope the ClientSidePages handler will be supported in SharePoint on premises environment soon, but you can always use the presented approach as a workaround.

Themes REST API

Office 365 provides more and more extension points available as REST services. Recently, I was working with the control that allows to manage the themes. The official documentation presents 3 endpoints that allow to list, add and delete theme (https://docs.microsoft.com/en-us/sharepoint/dev/declarative-customization/site-theming/sharepoint-site-theming-rest-api), the endpoints are:

  • siteURL/_api/thememanager/AddTenantTheme

Method allows to add tenant theme. As an argument, it accepts JSON with 2 properties: theme name and palette specifies the theme’s colors.

  • siteURL/_api/thememanager/DeleteTenantTheme

Method allows to delete theme. As an argument, it accepts the theme name.

  • siteURL/_api/thememanager/GetTenantThemingOptions

Method lists all available themes and returns them in the form of ThemingOptions object.

Additional methods

Below I present two additional endpoints that are not officialy announced in the docs (you have to consider using theme on your production environment), but can really useful to bring more possibilities to your solutions:

  • siteURL/_api/thememanager/ApplyTheme

Method allows to apply theme to the site.

  • siteURL/_api/thememanager/UpdateTenantTheme

Method allows to update the existing theme defition.

 

[2019-01-15]: I have created a PR to update the official docs.

SPFx usage

I have created a service class that allows to work with O365 themes that can be used in SPFx projects.

Coming soon

In the next post, I will share some thoughts about forcing immediate inheritance of the themes in the connected sites. Stay tuned!

Work with JSON data in PowerShell

Introduction

JSON is a well known, flexible format that allows to easily store the information. PowerShell provides a great cmdlets that helps working with JSON formatted data.

Let’s consider the sample JSON structure, containing information about the colors:

ConvertFrom-Json

The cmdlet allows easily to convert JSON data into the PowerShell custom object

ConvertTo-Json

The same way, the cmdlet allows to convert custom PowerShell object to JSON format.

This approach provides a great flexibility to quickly import and save the data that can be used within PowerShell scripts. It is getting more tricky when the JSON structure or PowerShell scripts logic is getting more and more complex. In addition, it might be also challenging to someone who is not aware of the data structure to start working on the .ps1 files.

The ideal situation would be to bring some kind of strong typing and intellisense to the PowerShell experience. We can use VS Code which is capable of resolving object structure, after loading it into memory.

20190101_VScode0

Now, we know the structure of the initialized object that we are working with and it solves partially the problem, but still when the complexity of the logic grows or we create custom functions that use argument names different than the loaded object name, we loose the syntax highlighting.

20190101_VScode1

PowerShell class for the rescue

To improve the development experience, we can create custom PowerShell classes, which will help us to get strongly typed objects in both the development and runtime scenarios. Let’s create simple classes that are going to represent the JSON data structure:

Now, we can use the Color class, as a parameter type for the Get-ColorDetails function. Thanks to that, we regain the syntax highlighting in VS Code.

20190101_VScode2

This approach will ensure that the Colors class will be initialized correctly. Moreover, we do not have to remove some additional information stored in the JSON like e.g. $schema.

VS Code Profile file

To fully leverage the described approach, we need to load the definition of the model into the ‘PowerShell Integrated Console’ every time we open the project. To automate the task and provide the same experience every time, let’s create a VS Code profile file, which is going to load the class definitions.

In the ‘PowerShell Integrated Console’, execute:

notepad $profile

Or create it if doesn’t exist:

New-Item $profile -type File

In the notepad, execute the model script (ColorsModel.ps1), to ensure that our class definition has been loaded:

if (Test-Path './ColorsModel.ps1') {
. ./ColorsModel.ps1
}

Save the file and restart the ‘Powershell Integrated Console’.  Now you can leverage syntax highlighting and strongly typed objects inside your PowerShell functions.

The full sample can be found in my github:
https://github.com/siata13/powershell-json-model

 

Ready, Set, Go!

Hi, I’m Piotr – passionate developer, working on a daily routine with Microsoft technologies: SharePoint/Office365/Azure/PowerShell. In private life, I am a fanatic runner.

In this blog, you will find the content related to SharePoint from all the angles.

I am really excited that you are here. Sharing is caring!