Fields

Configure SharePoint fields (columns) in a web or list.


Access

Access the Fields API using the fields property of Web or List.

Examples

up(engineer) {
// Add field to web
engineer.web.fields.add('MyField');

// Add field to list
engineer.web.lists.getByTitle('My List').fields.add('MyField');
}

Methods

getById(id)

Get a field by its ID or GUID. We highly recommend using the getByTitle method for any custom fields created by Engineer, as the field ID may change from environment to environment.

Parameters

id
The ID or GUID of the field to be retrieved (String, required)

Returns

Field

Examples

up(engineer) {
// Update the "Title" field
engineer.web.fields.getById('fa564e0f-0c70-4ab9-b863-0177e6ddd247').update({
Description: 'This is a title',
});
}

getByTitle(title)

Get a field by its internal name or title.

Parameters

title
The internal name of the field, or the title (display name) of the field (String, required)

Returns

Field

Examples

up(engineer) {
// Update field
engineer.web.fields.getByTitle('MyField').update({
Description: 'This is a description',
});
}

add(options|title)

Add a new field to the target Web or List.

Parameters

options
New field configuration (Object, required)
title
If a String is provided instead of options, a new field with this title will be created with default configuration (String, override)

Properties of options

Type
The field type; possible values are "Boolean", "Calculated", "Choice", "Currency", "DateTime", "Geolocation", "Lookup", "MultiChoice", "MultiLineText", "Number", "Text" (default), "Url", or "User" (String, optional)
Title
A title for the new field (String, required)
Description
A description for the new field (String, optional)
Group
A group name for the new field (String, optional)
*
See Microsoft’s Field resource documentation for a listing of all possible properties that can be passed to the REST API

Examples

up(engineer) {
// Add simple Text field
engineer.web.fields.add('NewSimpleTextField');

// Add Boolean Field
engineer.web.fields.add({
Type: 'Boolean',
Title: 'NewBooleanField',
DefaultValue: '0',
});

// Add Choice field
engineer.web.fields.add({
Type: 'Choice',
Title: 'NewChoiceField',
Choices: [
'One',
'Two',
'Three',
],
});

// Add Currency field
engineer.web.fields.add({
Type: 'Currency',
Title: 'NewCurrencyField',
CurrencyLocaleId: 1033,
});

// Add DateTime field
engineer.web.fields.add({
Type: 'DateTime',
Title: 'NewDateTimeField',
DisplayFormat: 1,
DateTimeCalendarType: 1,
FriendlyDisplayFormat: 0,
});

// Add MultiChoice field
engineer.web.fields.add({
Type: 'MultiChoice',
Title: 'NewMultiChoiceField',
Choices: [
'One',
'Two',
'Three',
],
});

// Add MultiLineText field
engineer.web.fields.add({
Type: 'MultiLineText',
Title: 'NewMultiLineTextField',
NumberOfLines: 8,
RichText: true,
AllowHyperlink: true,
RestrictedMode: false,
AppendOnly: false,
});

// Add Number field
engineer.web.fields.add({
Type: 'Number',
Title: 'NewNumberField',
MinimumValue: 0,
MaximumValue: 100,
});

// Add Text field
engineer.web.fields.add({
Type: 'Text',
Title: 'NewTextField',
MaxLength: 255,
});

// Add Url field
engineer.web.fields.add({
Type: 'Url',
Title: 'NewUrlField',
DisplayFormat: 1,
});

// Add User field
engineer.web.fields.add({
Type: 'User',
Title: 'NewUserField',
SelectionGroup: 8,
SelectionMode: 0,
});

// Add Calculated field
engineer.web.fields.add({
Type: 'Calculated',
Title: 'NewCalculatedField',
Formula: '=[NewNumberField]+10',
OutputType: 'Number',
});
}

addXml(xml)

Add a new field from XML schema to the target Web or List.

Parameters

xml
The XML field definition schema for the new field; see Microsoft’s field definition documentation for more information on building fields from an XML schema (String, required)

Examples

up(engineer) {
// Add Lookup field
engineer.web.fields.addXml(`
<Field
Type="Lookup"
Name="NewLookupField"
StaticName="NewLookupField"
DisplayName="New Lookup Field"
Description="A new Lookup field"
Group="My Group"
List="Lists/Pages"
ShowField="Title"
Required="FALSE"
SourceID="http://schemas.microsoft.com/sharepoint/v3">
</Field>
`
);

// Add HTML field
engineer.web.fields.addXml(`
<Field
Type="HTML"
Name="NewHTMLField"
StaticName="NewHTMLField"
DisplayName="New HTML Field"
Description="A new HTML field"
Group="My Group"
RichText="TRUE"
RichTextMode="FullHtml"
Required="FALSE"
SourceID="http://schemas.microsoft.com/sharepoint/v3">
</Field>
`
);

// Add Image field
engineer.web.fields.addXml(`
<Field
Type="Image"
Name="NewImageField"
StaticName="NewImageField"
DisplayName="New Image Field"
Description="A new Image field"
Group="My Group"
RichText="TRUE"
RichTextMode="FullHtml"
Required="FALSE"
SourceID="http://schemas.microsoft.com/sharepoint/v3">
</Field>
`
);

// Add Link field
engineer.web.fields.addXml(`
<Field
Type="Link"
Name="NewLinkField"
StaticName="NewLinkField"
DisplayName="New Link Field"
Description="A new Link field"
Group="My Group"
RichText="TRUE"
RichTextMode="ThemeHtml"
Required="FALSE"
SourceID="http://schemas.microsoft.com/sharepoint/v3">
</Field>
`
);

// Add SummaryLinks field
engineer.web.fields.addXml(`
<Field
Type="SummaryLinks"
Name="NewSummaryLinksField"
StaticName="NewSummaryLinksField"
DisplayName="New SummaryLinks Field"
Description="A new SummaryLinks field"
Group="My Group"
RichText="TRUE"
RichTextMode="FullHtml"
Required="FALSE"
SourceID="http://schemas.microsoft.com/sharepoint/v3">
</Field>
`
);
}

Managed Metadata/Taxonomy Fields

Want to add a managed metadata/taxonomy field? Check out our test migration on GitHub.