sp-devops

sp-devops is a command line utility to manage devops for Microsoft Sharepoint Online for modern Front-End projects.

Introduction

sp-devops is a command line utility to manage devops for Microsoft Sharepoint Online for modern Front-End projects.

There are very few custom sites built on modern Front-End frameworks on Sharepoint Online 365. Its a big hassle to manage the deployment which is completely manual. To address this problem I have created this library and is being used in a project of mine

Checkout ng-sharepoint (https://github.com/joyblanks/ng-sharepoint), a sample project written in Angular and is managed by sp-devops to deploy to sharepoint and its databases/lists are being created by it.

Installation

As a dev dependency in your project

$ npm i -D sp-devops # npm install sp-devops --save-dev 

As a global tool

$ npm i -g sp-devops

Highlights

Deployment:

$ sp-devops --deploy

Setup (create DBs, Sites, Populate, etc.):

$ sp-devops --setup

Get a Authorization Bearer Access token to use in REST API's

$ sp-devops --accesstoken

Usage

In your package.json add a script

scripts: {
  "sp-ng-build-deploy": "npm run build --prod && sp-devops --deploy",
  "sp-ng-create-lists": "sp-devops --setup --SP_SPEC_LIST=./<path-to>/<spec.json>",
  "sp-get-access-token": "sp-devops --accesstoken"
}

Then from terminal run (This will deploy the site in a sharepoint folder)

$ npm run sp-ng-build-deploy

You can also setup all your lists/databases from here. Please note the script tries to drop the databases and then recreates them in order to setup. You can pre-populate the lists as well by providing data in a specification file.

$ npm run sp-ng-create-lists

Get a Authorization Bearer Access token to use in REST API's in POSTMAN or in fetch API's useful for standalone testing

$ npm run sp-get-access-token

Command-Line-Args and Environment-Variables

[NOTE]*: Do not put property accesstoken, deploy and setup in .env files

ENV | CLI property	Description	Usage
deploy*	Deploys the distribution to a Sharepoint folder	--deploy
setup*	Create Lists/Sites, Preload data etc.	--setup
accesstoken*	Get an Authorization Bearer accessToken.	--accesstoken
SP_SITE-URL	Your Sharepoint Site Domain	--SP_SITE-URL=https://[$tenant].sharepoint.com
SP_SUBSITE	If y_u are working on a SubSite	--SP_SUBSITE=Sub1/Sub2
SP_APP-CLIENT_ID	Sharepoint App Client ID	--SP_APP_CLIENT_ID=aaaaaaa-zzzz-1234-wxyz
SP_APP-CLIENT_SECRET	Sharepoint App Client Secret	--SP_APP_CLIENT-SECRET=0000000000
SP_ACCESS_TOKEN	Sharepoint Authorization Bearer Token	--SP_ACCESS_TOKEN=Bearer [accessToken]
SP_DIST_FOLDER	Path Local Distribution folder (Source)	--SP_DIST_FOLDER=../bin/src
SP_REMOTE_FOLDER	Path to Remote Folder in Sharepoint (Destination)	--SP_REMOTE_FOLDER=SiteAssets/App
SP_LOG_LEVEL	Logging level of the Application	--SP_LOG_LEVEL=debug
SP_SPEC_LIST	Path to a JSON specification file which contains configuration to create lists and if data needs to be pre-polulated after creation	--SP_SPEC_LIST=./configs/create-list.json

Sample Run [--deloy]

Sample Run [--setup]

Sample Run [--accesstoken]

Setup and Configuration

• Setup a Sharepoint App to run sp-devops

  • Visit /_layouts/15/appregnew.aspx and generate your App Client Id and Client Secret. Provide details as shown in the diagram below and click create.

    Figure: Create Sharepoint App

  • Copy the Client ID and Secret to later use this library.

  • Visit /_layouts/15/appinv.aspx and enter your App Client Id that you have just created and click Lookup.

  • Enter the Permission Request XML on the last field and click Create.

    <AppPermissionRequests AllowAppOnlyPolicy="true">
      <AppPermissionRequest Scope="http://sharepoint/content/sitecollection" Right="Manage" />
      <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web" Right="Manage" />
      <AppPermissionRequest Scope="http://sharepoint/content/sitecollection/web/list" Right="FullControl" />
    </AppPermissionRequests>

    Figure: Request Permission for Sharepoint App

  • Click on Trust It button to grant the Sharepoint App the required permissions

    Figure: Grant Permission to Sharepoint App

    NOTE: **For a remote folder in the above diagram in dropdown needs to be granted access, so the files can behave properly, even though they will be uploaded but will be downloaded and not executed on the browser. In the above Site Assets folder is given access to deploy the contents.

• If you do not have authorization to create an App, you can ask your Sharepoint admin to generate an Authorization Bearer 'AccessToken' token and share with you which you can also use to fire this library.

• Create a .env file in your project and specify these values

  # -------------------------------------------- Common --------------------------------------------# 
   
  # Your Sharepoint Site Domain 
  SP_SITE_URL=https://${tenant}.sharepoint.com
   
  # If you are deploying to a subsite (Uncomment SP_SUBSITE) 
  # SP_SUBSITE=mysubsite 
   
  # Create a Sharepoint App  
  # then get details from /_layouts/15/AppRegNew.aspx (generate App ClientId and ClientSecret here) 
  # and trust your app from /_layouts/15/appinv.aspx (Give permissions and Trust app here) 
   
  # Sharepoint APP's CLIENT_ID & CLEINT_SECRET 
  SP_APP_CLIENT_ID=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  SP_APP_CLIENT_SECRET=********************************
   
  # Access Token from other sources (If you dont have Sharepoint APP's CLIENT_ID & CLEINT_SECRET) 
  # SP_ACCESS_TOKEN=Bearer <ACCESS_TOKEN> 
   
  # Logging level Allowed = [info, debug, warn, error] 
  SP_LOG_LEVEL=info
   
  # ------------------------------------------ Deployment ------------------------------------------# 
  # Sharepoint-Remote-Folder: where the code-base is to be uploaded 
  # Make sure it is a dedicated folder all files/folders are deleted before uploading 
  SP_REMOTE_FOLDER=SiteAssets
   
  # Path to your local distribution folder location 
  SP_DIST_FOLDER=dist
   
  # --------------------------------------------- Setups ---------------------------------------------# 
  # Path to spec file for creating Lists, Sites, Populate data, etc. 
  #SP_SPEC_LIST=./sharepoint-list-spec.json 
  #SP_SPEC_SITE=./sharepoint-site-spec.json 

• In your package.json add a script and run (Refer #Usage)

  scripts: {
    "sp-ng-build-deploy": "npm run build --prod && sp-devops --deploy"
  }

• For Setup (like creating DBs and Sites/Subsites) [Look under ./assets/samples in this repository]

  • you need to pass a JSON file to create your lists or to pre-populate data

    {
      "config": [
        {
          "name": "SampleList",
          "addToView": true,
          "addToQuickLaunch": true,
          "dropIfExists": false,
          "columns": [
            { "__metadata": { "type": "SP.Field" }, "FieldTypeKind": 3, "Title": "Message"  },
            { "__metadata": { "type": "SP.Field" }, "FieldTypeKind": 20, "Title": "AssignedTo" },
            {
              "__metadata": { "type": "SP.FieldChoice" }, "FieldTypeKind": 6, "Title": "Status",
              "Choices": {
                "__metadata": { "type": "Collection(Edm.String)" },
                "results": [
                  "Created", "Assigned", "In-Progress", "Completed", "Archived", "On-Hold", "Cancelled"
                ]
              }
            }
          ]
        },
        {
          "name": "ConfigList",
          "addToView": false,
          "addToQuickLaunch": true,
          "dropIfExists": true,
          "columns": [
            { "__metadata": { "type": "SP.Field" }, "FieldTypeKind": 3, "Title": "JSON" },
            { "__metadata": { "type": "SP.Field" }, "FieldTypeKind": 3, "Title": "Description" }
          ],
          "items": [
            {
              "Title": "App",
              "JSON": "{\"pageSize\": 10, \"theme\": \"light\"}",
              "Description": "Config for App (light theme)"
            },
            {
              "Title": "Dark-App",
              "JSON": "{\"pageSize\": 10, \"theme\": \"dark\"}",
              "Description": "Config for App (dark theme)"
            }
          ]
        }
      ]
    }

  • In you package.json add a script and run (Refer #Usage)

    scripts: {
      "sp-ng-create-lists": "sp-devops --setup --sp-spec-list=./<path-to>/<spec.json>"
    }

• All items in CLI/ENV options can be triggered. [NOTE]: CLI options overrides the ENV vars.

  npm run sp-ng-create-lists -- --SP_SUBSITE=inside/more_inside

---

Please feel free to log Pull requests, issues, bugs and improvement ideas

Author: Joy Biswas @joyblanks