sp-devops

    1.4.0 • Public • Published

    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 --deploy

    Sample Run [--setup]

    Sample Run --setup

    Sample Run [--accesstoken]

    Sample Run --setup

    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
        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
        Request Permission for Sharepoint App
      • Click on Trust It button to grant the Sharepoint App the required permissions

        Figure: Grant Permission to Sharepoint App
        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

    Install

    npm i sp-devops

    DownloadsWeekly Downloads

    13

    Version

    1.4.0

    License

    GPL-2.0+

    Unpacked Size

    72.4 kB

    Total Files

    10

    Last publish

    Collaborators

    • joyblanks