Ethel Docs

These runners are related to working with Microsoft SharePoint.

The runners documented here are:

Other related runners:

All of these runners have been used in production, but most have been rewritten to provide better support for migrating metadata and other elements so the status has been reset to developed

SharePoint connection

The connection object for all SharePoint runners changes depending on the SharePoint version and the organisation hosting the server. Look at the examples below for different configuration combinations.

Attribute	Data type	Description
spHost	string	The SharePoint host name.
clientId	string	The ID for the Entra client configuration.
clientCertificate.thumbprint	string	The thumbprint used to idenitify the certificate.
certPath	string	The path to the certificate file.
tenantId	string	The tenant ID for the host connection.
username	string	The username for an NTLM connection.
password	string	The password for an NTLM connection.
useNTLM	boolean	Whether to attempt an NTLM connection. Defaults to `false`.

Example SharePoint online connection object:

{
  "clientId": "5c2d4774-bc67-4e1d-b9c1-3b56e82c1b1f",
  "clientCertificate": {
    "thumbprint": "A33177147C1CB4D1D1A63CAF8B5A9E38CA36DAE8",
  },
  "certPath": "D:\\certs\\ethel-piggles.sharepoint.com.pk.txt",
  "spHost": "https://nerks.sharepoint.com",
  "tenantId": "83fc94bd-cff5-40f5-91ef-04bc08b68f32",
}

Example NTLM connection object:

{
  "username": "NERKS/fred.nerk",
  "password": "nerk",
  "spHost": "https://nerks.sharepoint.com",
  "useNTLM": true
}

SPListItemExtractor

Developed

This runner will extract information from SharePoint. It will not extract any files from SharePoint. To extract files from SharePoint to upload to other systems use the SharePointStaging runner.

Configuration options

Option	Data type	Default	Description
addSummary	boolean	`false`	Whether to add a summary for each extractRoot, adds load so only use when needed
batchConfig	number \| BatchConfig, mandatory	none	See batches
cancelCheckNumber	number	`50`	How often, in tasks raised, to check if the extract should be cancelled
connection	LookupDetails, mandatory	none	The name and key to the lookup with the SharePoint connection details.
extractRoot	(string \| SPExtractRoot)[], mandatory	none	If exporting the full list to another system you can use the list URL, otherwise use the SPExtractRoot object
filters	string \| string[]	['extractItem.type=ne\|File']	The extract items to be ignored or included. See Ignoring extract items for more information.
hashName	string, mandatory	none	The lookup name for the extract hash
quarantinedLookupName	string	`quarantinedSPListItemExtractor`	Name value for the quarantine lookup

Message attributes

It populates the following attributes in the new tasks it creates:

item metadata for the item extracted
quarantine quarantine lookup for the item

SharePointStaging

Production

This runner will copy files from SharePoint to the specified storage location

Configuration options

Option	Data type	Default	Description
allVersions	boolean	`false`	Whether to extract the latest version or all versions
connection	LookupDetails, mandatory	none	The name and key to the lookup with the SharePoint connection details.
extractItem	string	`extractItem`	The message attribute containing the extracted item
extractRoot	string	`extractRoot`	The message attribute with the configuration used for the extract item
stagingProvider	any, mandatory	none	The configuration details for the storage provider

Message attributes

Option	Data type	Description
extractItem	SPListItem, mandatory	The object extracted from the SharePoint API
extractRoot	SPExtractRoot, mandatory	The configuration used for the extract item

Message attribute names can be changed in the configuration options.

It populates the following attributes in the new tasks it creates:

sourceFile metadata for the item extracted

SPListItemLoader

Developed

This runner will create the SharePoint item using the loadItem message attribute

Configuration options

Option	Data type	Default	Description
addFields	boolean	`false`	Whether to add fields to the list if they are missing
addFullItem	boolean	`false`	Whether the loadedItem is the ServerRelativeURL or the full object
addHash	boolean	`true`	Whether to add the extractHash lookup
connection	LookupDetails, mandatory	none	The name and key to the lookup with the SharePoint connection details.
handleExisting	string	error	This runner supports three options: `complete` - complete the task and add the hash `error` - throw an error `overwrite` - overwrite the existing file with the newly extracted file
loadItem	string	loadItem	The message attribute that contains the SPLoadItem object
loadedItemLabel	string	OTCSLoadedItem	The label to use for the loaded item in the message

Message attributes

Option	Data type	Description
extractHash	Lookup	The extract hash object
loadItem	SPLoadItem, mandatory	The information used by the loader to create the item.

Message attribute names can be changed in the configuration options.

It populates the following attributes in the new tasks it creates:

sourceFile an array of versions that were staged

The SPLoadItem and SPLoadVersion class definitions:

export class SPLoadVersion {
  order: number;
  created?: string;
  modified?: string;
  filename?: string;
  sourceFile: string | StagedFile;

  constructor(values?: any) {
    Object.assign(this, values);
  }
}

export class SPLoadItem {
  skip = false;
  type: 'Folder' | 'File' | 'ListItem';
  name: string;
  title: string;
  listPath: string;
  fields: { [name: string]: any } = {};
  versions?: SPLoadVersion[];

  constructor(values?: any) {
    Object.assign(this, values);
  }
}

FSToSPTransformer

Developed

This runner transforms file system extractor messages to the SPLoadItem format

Configuration options

Option	Data type	Default	Description
extractItem	string	`extractItem`	The message attribute containing the extracted item
loadRoot	string \| SPLoadRoot, mandatory	none	Either the target SharePoint list URL or the SPLoadRoot object, if a target subfolder is used
sourceFile	string	`sourceFile`	The message attribute with the extracted file information

Message attributes

Option	Data type	Description
extractItem	FSExtractItem, mandatory	The file system object
sourceFile	string \| SourceFile	The extracted file information

Message attribute names can be changed in the configuration options.

It populates the following attributes in the new tasks it creates:

loadItem an array of versions that were staged

OTCSToSPTransformer

Developed

This runner transforms OTCS extractor messages to the SPLoadItem format

Configuration options

Option	Data type	Default	Description
extractItem	string	`extractItem`	The message attribute containing the extracted item
metadataMapping	{ [csAttId: string]: string }	none	key-value pairs with CS attribute id as the key and the SP field title as the value
sourceFile	string	`sourceFile`	The message attribute with the extracted file information
targetList	string \| SPList, mandatory	none	Either the target SharePoint list URL or the SPList object, if a target subfolder is used

Message attributes

Option	Data type	Description
extractItem	CSNode, mandatory	The Content Server object
sourceFile	SourceFile[]	The extracted file information

Message attribute names can be changed in the configuration options.

It populates the following attributes in the new tasks it creates:

loadItem an array of versions that were staged

SPToSPTransformer

Developed

This runner transforms SharePoint extract items to the SPLoadItem format

Configuration options

Option	Data type	Default	Description
extractFields	string	`extractFields`	The message attribute containing the extracted field definitions
extractItem	string	`extractItem`	The message attribute containing the extracted item
extractRoot	string	`extractRoot`	The message attribute with the initial extractor config
extractValues	string	`extractValues`	The message attribute containing the extracted field values
handleMetadataError	string	`error`	Whether to throw an error or log a warning if there is an error in mapping the metadata. Use `warning` to log the error
loadRoot	SPLoadRoot	none	Only required if load details are not in the extract config, either the target SharePoint list URL or the SPLoadRoot object, if a target subfolder is used
sourceFile	string	`sourceFile`	The message attribute with the extracted file information

Message attributes

Option	Data type	Description
extractFields	SPField[]	The extracted SharePoint field definitions
extractItem	SPListItem, mandatory	The SharePoint list item object
extractRoot	SPExtractRoot, mandatory	The configuration used for the extract item
extractValues	{ [EntityPropertyName: string]: any }	The extracted SharePoint field values
sourceFile	SourceFile[]	The extracted file information

Message attribute names can be changed in the configuration options.

It populates the following attributes in the new tasks it creates:

loadItem the SharePoint item to be created