loopback-connector-sharepoint

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:
``sh
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.

`json
{
"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
`typescript
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.

$3

- 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.
`js
{ownerId: {
type: Number,
sharepoint: {
columnName: 'Users',
dataType: 'User',
expandsTo: 'owner'
}
}
}
`
This will reproduce
`typescript
ownerId = 1;
owner = {
'id': 1,
'value': 'Jamil Falconi',
'title': 'Jamil Falconi',
'email': 'jamil.falconi@test.com',
'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.
`js
reviewersIds: {
type: Array,
sharepoint: {
columnName: 'People',
dataType: 'User',
expandsTo: 'reviewers'
}
},
`
This will reproduce
`typescript
reviewersIds = [10,12];
reviewers = [{
'id': 10,
'value': 'Jamil Omar Falconí Aguirre',
'title': 'Jamil Omar Falconí Aguirre',
'email': 'jamilomar@test.com',
'sip': 'jamilomar@test.com',
'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': 'jamil.falconi@test.com',
'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.
`js
{ referenceId: {
type: Number,
sharepoint: {columnName: 'Simple Lookup', dataType: 'Lookup', expandsTo: 'lookupField'}
}
}
`
This will reproduce
`typescript
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.
`js
multipleReferenceIds: {
type: Array,
sharepoint: {columnName: 'Multiple Lookup', dataType: 'Lookup', expandsTo: 'multiLookupField'}
},
`
This will reproduce
`typescript
multipleReferenceIds = [1];
multiLookupField = [{ {'lookupId': 1, 'lookupValue': '1', 'isSecretFieldValue': false}]
`
- MultiChoice Field: It creates an array of choice values.
`js
{type: {
type: Array,
sharepoint: {columnName: 'MultiChoice', dataType: 'MultiChoice'}
}
}
`
This will reproduce
`typescript
type = ['one', 'two'];
`
- Url Field: It creates a url field.
`js
{ picture: {
type: Object,
sharepoint: {columnName: 'Picture', dataType: 'Url'}
},
}
`
This will reproduce
`typescript
picture = {
url: 'http://localhost.com/img.jpg',
description: 'This is a picture'
};
`
- DateTime Field: It creates a datetime field.
`js
{ created: {
type: Date,
sharepoint: {columnName: 'Created', dataType: 'DateTime'}
},
}
`
This will reproduce
`typescript
created = Date.now();
`
- Guid Field: It creates a guid field.
`js
{ created: {
type: String,
sharepoint: {columnName: 'GUID', dataType: 'Guid'}
},
}
`
This will reproduce
`typescript
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:
`ts
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.