@euc-development/shp-migrations

Info

This package was created for EUC Development team and it contains all required resources to manage migrations on SharePoint sites with Nuxt front-end framework.

Installation

npm i @euc-development/migrations

Setup

Initial Setup

First you need to initialize the package. Create a Nuxt plugin and insert the following lines:

import { init } from "@euc-development/shp-migrations"

export default ({ $axios }, inject) => {
	init($axios);
}

Don't forget to import the plugin in the config.

Create Migration Script

In package.json file add the following line to scripts:

"create:migration": "node ./migrations.js --create"

Next create a migrations.js file in the root of the project and insert the following code:

const createMigration = require("@euc-development/shp-migrations/dist/modules/create-migration-script");

createMigration();

Now you can create migration files with the following command:

npm run create:migration -- --name=MigrationName

If successful, a new JS file should be created in the migrations folder of the project:

import { List } from "@euc-development/shp-migrations";
import { ListColumnAttributeTypes } from "@euc-development/shp-migrations";

export default class MigrationName {
	static createdAt = 20220706094629

	async up() {

	}

	async down() {

	}
}

The up method is called when migrating, the down method is called when rollbacking. To use the migration, you will need to import it in the index.js file located in the migrations folder.

export default [
	require("~/migrations/20220706094629_MigrationName").default,
]

This index.js file is later imported in the Nuxt page file described in the next section.

Migrations Page

This page is needed to interact with the migrations (migrate or rollback them). Feel free to create a page anywhere in your project and insert the following code. Notice that the migration classes are imported from the "~/migrations/index" file and pushed to the component as prop. To reach this page easily, feel free to create a navigation item in your application's menu.

<template>
  <migrations-component
    :migration-classes-original="migrationClasses"
    :translate="$t"
    :notify="$toast"
    :queries="$q"
    migrations-list-title="Migrations"
  />
</template>

<script>
import migrationClasses from "~/migrations/index";
import migrationsComponent from "@euc-development/shp-migrations/components/migrations/migrations";

export default {
  components: {
    migrationsComponent,
  },

  data() {
    return {
      migrationClasses: migrationClasses,
    };
  },
};
</script>

<style lang="scss" scoped></style>

If you open the page, you should see two tables:

• already migrated migrations
• not migrated migrations

Also you have 4 buttons available:

• Migrate - migrate the next migration in line
• Migrate All - migrate all migrations
• Rollback - rollback the previous migration in line
• Rollback All - rollback all migrations

Locales

For the locales to work, you need to properly import them from the package and export it from the main locale file`

import { migrationsEnLocales } from "@euc-development/shp-migrations";

export default {
	$vuetify: en,

	...migrationsEnLocales,
	...generic,

	nav,
	iam,

	.....

Available Classes

In the migrations, you can use the following classes to create and update lists. You can import them directly from the package index.js file:

import { ClassName } from "@euc-development/shp-migrations";

List Class

Attributes

attrs

Contains attributes of the list, if loaded. See fetchAttributes method.

Methods

Constructor

Creates a class instance with default parameters.

• listTitle
• lisBaseTemplate - Optionally, list template can be set to library (see ListAttributeTypes class)

constructor(listTitle, lisBaseTemplate = ListAttributeTypes.LIST_TEMPLATE_LIST)

create

Create a new list

• options

Returns attributs of the list (also accessible via attrs parameter)

async create(options = {})

const { description = "" } = options;

fetchAttributes

Fecthes information about the list

• options

Returns attributs of the list (also accessible via attrs parameter)

async fetchAttributes(options = {})

const { select = "" } = options;

change

Changes the provided attributes of the list

• attributes - Exmaple attributes: Title

async change(attributes)

remove

Removes the list.

async remove()

column

Returns ListColumn instance of the specified column of the list.

• colTitle

column(colTitle)

view

Returns ListView instance of the specified view of the list.

• listViewTitle - if not set, SharePoint default is used (All Items)

view(listViewTitle = undefined)

permissions

Return ListPermissions instance of the permissions of the list.

permissions()

ListColumn Class

Methods

constructor

Initializes the object with default options.

• listTitle
• colTitle
• listViewTitle

constructor(listTitle, colTitle, listViewTitle = undefined)

create

Creates new column and adds it to the default view

• type - column type, see ListAttributeTypes class
• options - https://docs.microsoft.com/en-us/previous-versions/office/sharepoint-visio/jj246815(v=office.15)

Returns attributes of created clumn.

async create(type, options = {})

const {
	required = false,
	unique = false,
	defaultValue = undefined,
} = options;

createLookup

Creates new lookup column and adds it to the default view.

• lookupListId - ID of list to lookup
• lookupFieldName - Title of field to display
• options - https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-rest-reference/dn600182(v=office.15)?redirectedfrom=MSDN#fieldlookup-and-fielduser-resources.
  • AllowMultipleValues - Multiple users/groups (Boolean)

Returns attributes of created clumn.

async createLookup(lookupListId, lookupFieldName, options = {})

remove

Removes column from list.

async remove()

change

Changes attributes of column

• attributes - Possible values depend on column type. https://docs.microsoft.com/en-us/previous-versions/office/developer/sharepoint-rest-reference/dn600182(v=office.15)?redirectedfrom=MSDN#fieldlookup-and-fielduser-resources
  • Description - (String)
  • DefaultValue - (type based on field type)
  • EnforceUniqueValues - (Boolean)
  • Required - (Boolean)
  • MaxLength - - Text (Int32)
  • RichText - - Multi-line text (Boolean)
  • MaximumValue - - Number (Double)
  • MinimumValue - - Number (Double)
  • DisplayFormat - - DateTime (Int32), DateOnly = 0, DateTime = 1.
  • FriendlyDisplayFormat - - DateTime (Int32), Unspecified = 0, Disabled (standard absolute) = 1, Relative (standard friendly relative) = 2.
  • AllowMultipleValues - - User/group (Boolean)
  • SelectionMode - - User/group (Int32), PeopleOnly = 0, PeopleAndGroups = 1
  • SelectionGroup - - User/group (Int32), All Users = 0 (default) or specific group ID needs to be provided

async change(attributes = {})

ListPermissions Class

constructor

• listTitle

constructor(listTitle)

breakInheritance

Breaks role inharitance of the list

• options
  • copyRoleAssignments (Boolean) - Specifies whether to copy the role assignments from the parent or not. If the value is false, the collection of role assignments must contain only 1 role assignment containing the current user after the operation.
  • clearSubscopes (Boolean) - clearsubscopes parameter is true, the role assignments for all child objects will be cleared and those objects will inherit role assignments from the current object after this call. If the clearsubscopes parameter is false, the role assignments for all child objects which do not inherit role assignments from their parent must remain unchanged.

async breakInheritance(options = {})

const {
	copyRoleAssignments = false,
	clearSubscopes = true,
} = options;

resetInheritance

Resets role inheritance for the list

async resetInheritance()

add

Adds a permission to a user or group on a list, which doesn't inherit permissions (breakInheritance is needed first).

• principalId - ID of user or group
• roleDefinitionId - ID of role definition (permission)

async add(principalId, roleDefinitionId)

remove

Removes a permission from a user or group on a list, which doesn't inherit permissions (breakInheritance is needed first).

• principalId - ID of user or group
• roleDefinitionId - ID of role definition (permission). If not provided, all permissions of given principal is removed

async remove(principalId, roleDefinitionId = null)

removeCurrentUserPermissions

Removes all permissions of current user (who is running the migration). This is needed in cases when inheritance is broken, as SharePoint automatically grants current user Full Control permissions.

async removeCurrentUserPermissions()

ListView Class

Methods

constructor

• listTitle
• viewTitle - if not specified, the default All Items view is initialized

addColumn

Adds a column to a list view

• colTitle

Returns the instance of the ListView (this)

async addColumn(colTitle)

moveColumnTo

Moves a column to the specified index in a list view

• colTitle
• index - Index where to move the column (0 is lowest)

Returns the instance of the ListView (this)

async moveColumnTo(colTitle, index)

removeColumn

Removes the specified column from the view

• colTitle

Returns the instance of the ListView (this)

async removeColumn(colTitle)

CurrentUser Class

Attributes

attrs

Contains attributs of current user if fetched, see fetchAttributes method.

Methods

fetchAttributes

Fecthes attributes of current user and returns it.

• options

Returns attributs of current user (also available via attrs attribute)

async fetchAttributes(options = {})

const { select = "" } = options;

RoleDefinitions Class

Attributes

value

Contains role definitions if fetched (see fetch method).

Methods

fetch

Fetches all role definitions of the site and returns them (also available via value attribute)

• options

Returns all role definitions.

async fetch(options = {})

const { select = "" } = options;

get

Returns all role definitions (fetch is needed first).

get()

getByTitle

• title

Returns the role definition by title (fetch is needed first)

getByTitle(title)

SiteGroups Class

Attributes

value

Contains user groups if fetched (see fetch method).

Methods

fetch

Fetches all user groups of the site and returns them (also available via value attribute)

• options

Returns all user groups.

async fetch(options = {})

const { select = "" } = options;

get

Returns all user groups (fetch is needed first).

get()

getByTitle

• title

Returns the user group by title (fetch is needed first)

getByTitle(title)

ListAttributeTypes Object

Contains constant variables, which can be used as helpers in the migrations.