loopback-connector-sharepoint

LoopBack is a highly-extensible, open-source Node.js framework that enables you to create dynamic end-to-end REST APIs with little or no coding. It also enables you to access data from major relational databases, MongoDB, SOAP and REST APIs.

loopback-connector-sharepoint is the Microsoft SharePoint connector module for loopback-datasource-juggler.

Basic usage

Installation

Install the module using the command below in your projects root directory:

npm i loopback-connector-sharepoint

Configuration

Below is the sample datasource configuration file:

• siteUrl(string): SharePoint site url.
• authConfig(object): Object containing authentication credentials for SharePoint. See node-sp-auth and node-sp-auth-config documentation for different authentication strategies.
• debug: when true, prints debugging information (such as CAML queries) to console.

{
  "name": "sample-datasource",
  "connector": "sharepoint",
  "authConfig": {
    "username": "admin",
    "password": "secret",
    "online": true
  },
  "siteUrl": "https://sample.sharepoint.com/sites/my-site"
}

NOTE: Defining Models

SharePoint LB connector provides options for mapping between SharePoint lists and columns and Loopback models and their properties. These options are set in the LB4 decorators inside sharepoint element.

list - Name of SharePoint list to store model instances. If not specified then model class name is used. columnName - Name (InternalName) of SharePoint column to store model's property. If not specified then property name is used.

Example: user.model.ts

import {Entity, property, model} from '@loopback/repository';
@model({
  settings: {
    sharepoint: {
      list: 'Users',
    },
  },
})

export class User extends Entity {
  @property({
    type: 'number',
    id: true,
    sharepoint: {
      columnName: 'ID',
    },
  })
  id?: number;

  @property({
    type: 'string',
    required: true,
    sharepoint: {
      columnName: 'Title',
    },
  })
  title: string;

  @property({
    type: 'string',
    sharepoint: {
      columnName: 'FirstName',
    },
  })
  firstName: string;

  @property({
    type: 'string',
    sharepoint: {
      columnName: 'LastName',
    },
  })
  lastName: string;

  @property({
    type: 'string',
    sharepoint: {
      columnName: 'Email',
    },
  })
  email: string;

  @property({
    type: 'number',
    sharepoint: {
      columnName: 'Age',
    },
  })
  age: number;

}

Notes: All SharePoint lists contain default columns: ID, GUID, Title, etc.. These columns are present in all lists and cannot be removed.
You can map your model's properties to these columns. For identity properties {id: true} you have two options: map them to ID SP column, which is auto-generated integer, or to GUID SP column which is a 35-character UUID. When mapping to GUID, you can set id value to your own generated GUID, SharePoint won't override it.

Field Types

• User Field: Allows to map the user id to a numeric(id) value, also if the option expandsTo=(newProperty) is provided, it will create a new read-only object with the user's information.

  {ownerId: {
     type: Number,
     sharepoint: {
       columnName: 'Users',
       dataType: 'User',
       expandsTo: 'owner'
     }
   }
  }

This will reproduce

  ownerId = 1;
  owner =  {
          'id': 1,
          'value': 'Jamil Falconi',
          'title': 'Jamil Falconi',
          'email': '[email protected]',
          'sip': '',
          'picture': '',
          'department': ''
        }

For mapping a list of users into a numeric(id)'s array, the column type must be Array. Also if the option expandsTo=(newProperty) is provided, it will create a new read-only array with the users' information.

  reviewersIds: {
         type: Array,
         sharepoint: {
           columnName: 'People',
           dataType: 'User',
           expandsTo: 'reviewers'
         }
       },

This will reproduce

  reviewersIds = [10,12];
  reviewers =   [{
          'id': 10,
          'value': 'Jamil Omar Falconí Aguirre',
          'title': 'Jamil Omar Falconí Aguirre',
          'email': '[email protected]',
          'sip': '[email protected]',
          'picture': 'https://jamilfalconi-my.sharepoint.com:443/User%20Photos/Profile%20Pictures/jamilomar_jamilfalconi_onmicrosoft_com_MThumb.jpg',
          'department': ''
        },
        {
          'id': 12,
          'value': 'Jamil Falconi',
          'title': 'Jamil Falconi',
          'email': '[email protected]',
          'sip': '',
          'picture': '',
          'department': ''
        }]

• Lookpup Field: Allows to map the lookup id to a numeric(id) value, also if the option expandsTo=(newProperty) is provided, it will create a new read-only object with the lookup's information.

  { referenceId: {
         type: Number,
         sharepoint: {columnName: 'Simple Lookup', dataType: 'Lookup', expandsTo: 'lookupField'}
       }
  }

This will reproduce

  referenceId = 1;
  lookupField =  {'lookupId': 1, 'lookupValue': '1', 'isSecretFieldValue': false}

For mapping a list of Lookup fields into a numeric(id)'s array, the column type must be Array. Also if the option expandsTo=(newProperty) is provided, it will create a new read-only array with the Lookups' information.

  multipleReferenceIds: {
         type: Array,
         sharepoint: {columnName: 'Multiple Lookup', dataType: 'Lookup', expandsTo: 'multiLookupField'}
       },

This will reproduce

  multipleReferenceIds = [1];
  multiLookupField =   [{ {'lookupId': 1, 'lookupValue': '1', 'isSecretFieldValue': false}]

• MultiChoice Field: It creates an array of choice values.

  {type: {
         type: Array,
         sharepoint: {columnName: 'MultiChoice', dataType: 'MultiChoice'}
       }
   }

This will reproduce

  type = ['one', 'two'];

• Url Field: It creates a url field.

  { picture: {
         type: Object,
         sharepoint: {columnName: 'Picture', dataType: 'Url'}
       },
   }

This will reproduce

  picture = {
      url: 'http://localhost.com/img.jpg',
      description: 'This is a picture'
      };

• DateTime Field: It creates a datetime field.

  { created: {
         type: Date,
         sharepoint: {columnName: 'Created', dataType: 'DateTime'}
       },
   }

This will reproduce

  created = Date.now();

• Guid Field: It creates a guid field.

  { created: {
         type: String,
         sharepoint: {columnName: 'GUID', dataType: 'Guid'}
       },
   }

This will reproduce

  const guid = '4d10b1fb-727d-4fb9-a6e8-8f1fa43bd677';

DataMappers

This functionality allows you to map information for user and lookup fields. For using this functionality , use the property mapTo to send an object with the new name of the properties and the current properties, for example:

 ownerIdWithMapper: {
         type: Number,
         sharepoint: {
           columnName: 'Owner',
           dataType: 'User',
           expandsTo: 'ownerWithMapper',
           mapTo: {
             id: 'id', // maps id to id
             username: 'title' // maps title to username

           }
         }
       },

Debugging

loopback-connector-connector uses debug utility. To print debugging information you can set environment variable DEBUG=loopback-sharepoint-connector or DEBUG=*. You can also set {debug: true} in the datasource configuration.

Running the tests

• execute npm install for installing all the dependencies.
• execute npm test to run all the tests.