Nocturnal Pumpkin Maelstrom

    node-sp-alm
    TypeScript icon, indicating that this package has built-in type declarations

    1.3.0 • Public • Published

    SharePoint solution ALM actions

    NPM

    This project is created for automating the deployment process of SharePoint solution packages to the App Catalog. This module uses the new ALM APIs that are available on SharePoint Online tenants.

    More information about the Application Lifecycle Management (API) can be found here: https://docs.microsoft.com/en-us/sharepoint/dev/apis/alm-api-for-spfx-add-ins

    Installation

    Run the following command to install the node-sp-alm:

    $ npm install node-sp-alm --save-exact
    

    Usage

    Once you installed this dependency to your project. You can make use of the following provides sample to add and deploy the solution package:

    const sppkg = require('node-sp-alm');
    const fs = require('fs');
    const path = require('path');
     
    const fileName = "solution-package.sppkg";
     
    const spAlm = new sppkg.ALM({
      "username": "your-username",
      "password": "your-password",
      "tenant": "your-tenant-name (ex.: contoso)",
      "verbose": true
    });
     
    // Retrieve the solution package
    const fileContent = fs.readFileSync(path.join(__dirname, `./${fileName}`));
    // First add the SharePoint package
    const appData = await spAlm.add(fileName, fileContent);
    console.log('Solution package added');
    // Deploy the SharePoint package based on the package ID
    await spAlm.deploy(appData.UniqueId, skipFeatureDeployment)
    console.log('Solution package deployed');

    Available actions

    Currently the following actions are supported:

    Action: list

    List returns the available apps.

    spAlm.list()
    
    // OR 
    
    spAlm.list(false)
    

    Arguments:

    1. Use the tenant app catalog or site-collection app catalog (not required - default: true -> uses the tenant app catalog)

    Action: appDetails

    Returns information about the provided solution package ID.

    spAlm.appDetails("00000000-0000-0000-0000-000000000000");
    
    // OR
    
    spAlm.appDetails("00000000-0000-0000-0000-000000000000", false);
    

    Arguments:

    1. Package ID
    2. Use the tenant app catalog or site-collection app catalog (not required - default: true -> uses the tenant app catalog)

    Action: add

    Adds the provided solution package to the app catalog.

    spAlm.add(fileName, fileContent);
    
    // OR 
    
    spAlm.add(fileName, fileContent, true, false);
    

    Arguments:

    1. File name
    2. File contents (Buffer)
    3. Overwrite file in app catalog (not required - default: true)
    4. Use the tenant app catalog or site-collection app catalog (not required - default: true -> uses the tenant app catalog)

    Action: deploy

    Deploys the previously added solution package.

    deploy.deploy(pkgId, true)
    
    // OR
    
    deploy.deploy(pkgId, true, false)
    

    Arguments:

    1. Package ID
    2. Skip feature deployment
    3. Use the tenant app catalog or site-collection app catalog (not required - default: true -> uses the tenant app catalog)

    More information about the skipFeatureDeployment option can be found here: Tenant-Scoped solution deployment for SharePoint Framework solutions.

    Action: retract

    Retracts the solution package.

    spAlm.retract(pkgId)
    
    // OR
    
    spAlm.retract(pkgId, false)
    

    Arguments:

    1. Package ID
    2. Use the tenant app catalog or site-collection app catalog (not required - default: true -> uses the tenant app catalog)

    Action: remove

    Removed the solution package.

    spAlm.remove(pkgId)
    
    // OR
    
    spAlm.remove(pkgId, false)
    

    Arguments:

    1. Package ID
    2. Use the tenant app catalog or site-collection app catalog (not required - default: true -> uses the tenant app catalog)

    Action: install

    Installs the solution package to the site.

    spAlm.install(pkgId)
    

    Arguments:

    1. Package ID

    Action: uninstall

    Uninstalls the solution package from the site.

    spAlm.uninstall(pkgId)
    

    Arguments:

    1. Package ID

    Action: upgrade

    Upgrades the solution package on the site.

    spAlm.upgrade(pkgId)
    

    Arguments:

    1. Package ID

    Action: getCatalogSites

    Retrieve all available app catalog sites.

    spAlm.getCatalogSites()
    

    This returns the following object:

    {
      'odata.metadata': string;
      value: [{
        'odata.type': string;
        'odata.id': string;
        'odata.editLink': string;
        AbsoluteUrl: string;
        SiteID: string;
      }]
    }
    

    Arguments / options

    The following arguments / options can be passed for deploying the package.

    username (required)

    Type: String Default: ""

    Sets the username to be used for the deployment.

    password (required)

    Type: String Default: ""

    Sets the password to be used for the deployment.

    tenant (optional)

    Type: String Default: ""

    Sets the tenant name to be used for the deployment. Example: https://<tenant>.sharepoint.com

    Important: You have to specify this property or the absoluteUrl property

    site (optional)

    Type: String Default: ""

    Specify the relative path to the app catalog site. Example: "sites/catalog"

    absoluteUrl (optional)

    Type: String Default: ""

    Sets the absoluteUrl to the app catalog site that needs to be used for the deployment. Example: https://tenant.sharepoint.com/sites/catalog.

    Important: You have to specify this property or the combination tenant and site property.

    filename (optional)

    Type: Boolean Default: false

    Specify if you want to show the console logs.

    Where can this be used?

    This dependency can for example be used in your SharePoint Framework release process. Here is a sample gulp task that you can add to your SPFx project:

    const sppkg = require('node-sp-alm');
    const through = require('through2');
     
    const environmentInfo = {
      "username": "",
      "password": "",
      "tenant": ""
    }
     
    build.task('add-deploy-sppkg', {
      execute: (config) => {
        environmentInfo.username = config.args['username'] || environmentInfo.username;
        environmentInfo.password = config.args['password'] || environmentInfo.password;
        environmentInfo.tenant = config.args['tenant'] || environmentInfo.tenant;
     
        return new Promise((resolve, reject) => {
          // Retrieve the package solution file
          const pkgFile = require('./config/package-solution.json');
          // Get the solution name from the package file
          const solutionFile = pkgFile.paths.zippedPackage;
          const fileLocation = `./sharepoint/${solutionFile}`;
          // Retrieve the file name, this will be used for uploading the solution package to the app catalog
          const fileName = solutionFile.split('/').pop();
          // Retrieve the skip feature deployment setting from the package solution config file
          const skipFeatureDeployment = pkgFile.solution.skipFeatureDeployment ? pkgFile.solution.skipFeatureDeployment : false;
     
          const spAlm = new sppkg.ALM({
            "username": environmentInfo.username,
            "password": environmentInfo.password,
            "tenant": environmentInfo.tenant,
            "verbose": true
          });
     
          // Get the solution file and pass it to the ALM module
          return gulp.src(fileLocation).pipe(through.obj((file, enc, cb) => {
            spAlm.add(fileName, file.contents).then(data => {
              build.log('Solution package added');
              // Deploy the SharePoint package based on the package ID
              spAlm.deploy(data.UniqueId, skipFeatureDeployment).then(data => {
                build.log('Solution package deployed');
                cb(null, file);
              });
            });
          })).on('finish', resolve);
        });
      }
    });

    Once this task is in place, you can run it with: gulp add-deploy-sppkg or gulp add-deploy-sppkg --username "your-username" --password "your-password" --tenant "your-tenant".

    More information about using arguments in SPFx gulp tasks can be found here: Passing arguments with custom Gulp tasks for SharePoint Framework projects.

    Output of the task:

    Gulp task output

    Install

    npm i node-sp-alm

    DownloadsWeekly Downloads

    22

    Version

    1.3.0

    License

    MIT

    Unpacked Size

    155 kB

    Total Files

    71

    Last publish

    Collaborators

    • eliostruyf