Tutorial: build a modern SharePoint App (timesheets app example)

Building an app using Site Designs, Site Scripts, PowerAutomate, SPFx, and Teams

Our old timesheets app was a custom .NET/SQL Server application that was starting to show its age. We decided this would be a perfect candidate for a modern SharePoint app! It would give us a great platform to start from, saving a lot of time. And it would be highly integrated and work seamlessly with Microsoft Teams, giving our consulting team a fast and easy way to submit their timesheets.

It has to be fully modern!

For this, we wanted to leverage the newest features from Microsoft. We also wanted to make the deployment flexible, but programmatic.

Here is the general role of each tool in the solution:

• SharePoint Online as the base platform for data structure/storage
• SharePoint Site Design which are new site templates, allowing us to deploy the app on demand
• SharePoint Site Script, one or more of which can be added to a site design, to automate actions on a site
• PowerAutomate to provide approval and unlock functionality for admins
• SPFx as the webpart development framework (with ReactJS)
• Microsoft Teams as the front-end delivery mechanism for consultants

Let’s get started!

First, make sure you have a suitable SharePoint Online development environment, including either SharePoint Management Powershell or the M365 CLI tool. View our tutorial on how to see up the best modern SharePoint development environment.

Second, go to our github repo to find the scripts.

Site Script JSON File

The site script file automates a series of actions when it’s deployed. When we deploy, we’ll connect it to a Site Design. When we use the Site Design on either a new or existing site, all the scripts will run. You may run a script on an existing site to update it – it will ignore any actions which are already complete (i.e. if a list already exists, it will update it with any changes or ignore it if there are none).

Here is Microsoft’s JSON schema documentation. We won’t go through it all, just a few examples to get the idea.

Here is the JSON structure of a site script:

{
    "$schema": "https://developer.microsoft.com/json-schemas/sp/site-design-script-actions.schema.json",
    "actions": [
        // one or more actions to perform on run
    ],
    "bindata": {},
    "version": 1
}

One of the most common things you would do with a site script is create a custom list on your SharePoint site. Let’s look at how this is done. Inside the “actions” array, we want to start our list of actions.

    "actions": [
        {
            "verb": "createSPList",
            "listName": "Accounts",
            "templateType": 100,
            "subactions": [
                {
                    "verb": "setDescription",
                    "description": "Account List"
                },
                {
                    "verb": "deleteSPField",
                    "displayName": "Title"
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Text",
                    "displayName": "Company Name",
                    "isRequired": true,
                    "addToDefaultView": true,
                    "enforceUnique": true,
                    "internalName": "CompanyName"
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Text",
                    "displayName": "Company Website",
                    "internalName": "CompanyWebsite",
                    "isRequired": false,
                    "addToDefaultView": true
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Text",
                    "displayName": "Company Phone",
                    "internalName": "CompanyPhone",
                    "isRequired": false,
                    "addToDefaultView": true
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Text",
                    "displayName": "Country",
                    "isRequired": false,
                    "addToDefaultView": true
                },
                {
                    "verb": "addSPField",
                    "fieldType": "User",
                    "displayName": "Owner",
                    "isRequired": false,
                    "addToDefaultView": true
                },
                {
                    "verb": "addSPField",
                    "fieldType": "Note",
                    "displayName": "Notes",
                    "isRequired": false,
                    "addToDefaultView": true
                },
                {
                    "verb": "addSPView",
                    "name": "Accounts",
                    "viewFields": [
                        "CompanyName",
                        "CompanyWebsite",
                        "CompanyPhone",
                        "Country",
                        "Owner",
                        "Notes"
                    ],
                    "query": "",
                    "rowLimit": 100,
                    "isPaged": true,
                    "makeDefault": true
                }
            ]
        }
    ]

Let’s review the above. Our first (and only) action in this script is to create a new list, based on the default (ID 100) list template, titled “Accounts”. In the subactions you can see the list of columns we are creating and some of the arguments we can pass, such as whether to add it to the default view. We can also create views.

The above is just an example of what can be done. You can create custom views, add custom XML so you can have more complex data types like lookup columns, and more. And lists are just one example of what you can do with a SharePoint site script.

Review the documentation and our sample code to see more examples and review all your options as a developer.

Adding our Site Script to a Site Design

A Site Design is a Modern SharePoint site template. One or more Site Scripts are assigned to a Site Design. These scripts automate certain processes as seen above in our list of “actions”.

Let’s create a Site Design and add our Site Script to it. First, make sure you are connected to a development tenant in your M365 CLI or SharePoint PowerShell management.

M365 CLI

m365 login

Powershell

Connect-SPOService -Url https://{your tenant}-admin.sharepoint.com -Credential {your dev account}

Create Site Script

M365 CLI

m365 spo sitescript add -t {your site script name} -d {your site script description} -c { your site script JSON }

Powershell

Add-SPOSiteScript -Title {your site script name} -Description {your site script description} -Content { your site script JSON }

IMPORTANT: Do not point to your JSON file or try to save it to an environment variable as that was not working. Instead, open a single quotation, paste your entire script into the terminal, and close the quotation.

Get Site Script

Note the GUID of your site script:

M365 CLI

m365 spo sitescript get

Powershell

Get-SPOSiteScript

Create Site Design

Now we want to create a Site Design to add our script to. The Site Design will be a user-selectable option when we create our site.

M365 CLI

m365 spo sitedesign add -t { site design title } -d { site design description } -w { sitetype (CommunicationSite or TeamSite) } -s { comma separated list of scripts }

Powershell

Add-SPOSiteDesign`
-Title { site design name }
-WebTemplate { (CommunicationSite or TeamSite) }
-SiteScripts { comma separated list of script ids }
-Description { site design description }
`

Paste your Site Script ID from the previous step accordingly.

Using your Site Design

Your Site Design is now ready to use! Create the site type you applied it to (i.e. Team Site or Communication Site), and you should now see your new Site Design in the list of Organizational Templates. Once you select it, your list will automatically be created just like you designed it in your JSON script.

You can also apply it to an existing site. If you have an existing site of the right type, click the settings and choose Site Designs. Then you can apply the template and your script will run on the existing site.

You can re-use the Site Design as much as you like.

Next Post

Coming Soon -> Automating timesheet approvals using Microsoft PowerAutomate.