Summary
Creates a new form.
Add-Form
-EntryReturns a form object.
Parameters
Parameter | Type | Required? | Notes |
|---|---|---|---|
Entry | Form Object | Yes |
Examples
Create a new form
$ErrorActionPreference = 'Stop'
# Create a form object with required fields
$form = @{
Name = "My Form"
Category = "General"
FormTypeId = 1
Sections = @(
@{
Heading = "Section 1"
Fields = @(
@{
DataTypeId = 1
Label = "My Basic Text Field"
IsRequired = $false
IsVisible = $true
Position = 1
},
@{
DataTypeId = 2
Label = "My Rich Text Field"
IsRequired = $false
IsVisible = $true
Position = 2
},
@{
DataTypeId = 3
Label = "My Whole Number Field"
IsRequired = $false
IsVisible = $true
Position = 3
},
@{
DataTypeId = 4
Label = "My Decimal Number Field"
IsRequired = $false
IsVisible = $true
Position = 4
},
@{
DataTypeId = 5
Label = "My Yes or No Field"
IsRequired = $false
IsVisible = $true
Position = 5
},
@{
DataTypeId = 6
Label = "My Date and Time Field"
IsRequired = $false
IsVisible = $true
Position = 6
},
@{
DataTypeId = 7
Label = "My Date Only Field"
IsRequired = $false
IsVisible = $true
Position = 7
},
@{
DataTypeId = 8
Label = "My Single Choice Field"
IsRequired = $false
IsVisible = $true
Position = 8
DefaultValue = "Choice 1`nChoice 2`nChoice 3"
},
@{
DataTypeId = 9
Label = "My Multiple Choice Field"
IsRequired = $false
IsVisible = $true
Position = 9
DefaultValue = "Item A`nItem B`nItem C"
},
@{
DataTypeId = 10
Label = "My Contacts Reference Field"
IsRequired = $false
IsVisible = $true
Position = 10
ReferenceObject = @{ ObjectId = 7 }
}
)
}
)
}
# Add-Form may report a serialization error. The form gets created, but the system chokes on
# returning the data back, so we need to work around that.
function Test-IsKnownODataNullSourceError {
param([Parameter(Mandatory)] [object]$ErrorRecord)
# Unwrap AggregateException if present
$ex = $ErrorRecord.Exception
if ($ex -is [System.AggregateException] -and $ex.InnerExceptions.Count -gt 0) {
$ex = $ex.InnerExceptions[0]
}
# Walk inner exceptions and look for the specific serialization error message
while ($null -ne $ex) {
if ($ex.Message -match "Value cannot be null\.\s*\(Parameter 'source'\)") {
return $true
}
$ex = $ex.InnerException
}
return $false
}
try {
Add-Form -Entry $form -ErrorAction Stop | Out-Null
}
catch {
if (Test-IsKnownODataNullSourceError $_) {
# Clear the error so it doesn't remain in $Error
$global:Error.RemoveAt(0) 2>$null
}
else {
throw
}
}
# Verify the form exists
$formsResult = Get-Forms -Filter "Name eq 'My Form' and Category eq 'General'" -Top 1
$createdForm = $formsResult.Collection | Select-Object -First 1
if ($null -eq $createdForm) {
Write-Error "Encountered an error while creating the form"
exit 1
}
# Now fetch the fully-expanded form using `Get-Form`
$fullForm = Get-Form -Id $createdForm.FormId
Write-Output "Created form '$($fullForm.Name)' (#$($fullForm.FormId), # of sections: $($fullForm.NumberOfSections), # of fields: $($fullForm.NumberOfFields))"
Write-Output ""
Write-Output "JSON Results:"
Write-Output ($fullForm | ConvertTo-Json -Depth 10)Execution results:
Created form 'My Form' (#99, # of sections: 1, # of fields: 10)
JSON Results:
{
"FormId": 99,
"FormTypeId": 1,
"FormType": null,
"FormTypeName": "Tasks",
"Name": "My Form",
"Category": "General",
"Description": null,
"IsAvailableOnPortal": false,
"NumberOfSections": 1,
"NumberOfFields": 10,
"CreatedByFullName": "Max Miller",
"CreatedById": "510e109b-6ff5-4442-9670-cd5e3cd82a7a",
"CreatedOn": "2026-01-21T13:07:18.6211605+00:00",
"CreatedBy": null,
"LastUpdatedByFullName": "Max Miller",
"LastUpdatedById": "510e109b-6ff5-4442-9670-cd5e3cd82a7a",
"LastUpdatedOn": "2026-01-21T13:07:18.6211605+00:00",
"LastUpdatedBy": null,
"Sections": [
{
"SectionId": 120,
"FormId": 99,
"Heading": "Section 1",
"Position": 0,
"Guid": 1148648158110,
"Fields": [
{
"FieldId": 475,
"SectionId": 120,
"DataTypeId": 1,
"DataTypeName": "Basic Text",
"Label": "My Basic Text Field",
"IsRequired": false,
"IsVisible": true,
"Position": 1,
"Guid": 4167049853533,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 476,
"SectionId": 120,
"DataTypeId": 2,
"DataTypeName": "Rich Text",
"Label": "My Rich Text Field",
"IsRequired": false,
"IsVisible": true,
"Position": 2,
"Guid": 6798658424189,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 477,
"SectionId": 120,
"DataTypeId": 3,
"DataTypeName": "Whole Number",
"Label": "My Whole Number Field",
"IsRequired": false,
"IsVisible": true,
"Position": 3,
"Guid": 5168576493377,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 478,
"SectionId": 120,
"DataTypeId": 4,
"DataTypeName": "Decimal Number",
"Label": "My Decimal Number Field",
"IsRequired": false,
"IsVisible": true,
"Position": 4,
"Guid": 9276055131768,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 479,
"SectionId": 120,
"DataTypeId": 5,
"DataTypeName": "Yes or No Choice",
"Label": "My Yes or No Field",
"IsRequired": false,
"IsVisible": true,
"Position": 5,
"Guid": 6772880977176,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 480,
"SectionId": 120,
"DataTypeId": 6,
"DataTypeName": "Date Only",
"Label": "My Date and Time Field",
"IsRequired": false,
"IsVisible": true,
"Position": 6,
"Guid": 287848767297,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 481,
"SectionId": 120,
"DataTypeId": 7,
"DataTypeName": "Date and Time",
"Label": "My Date Only Field",
"IsRequired": false,
"IsVisible": true,
"Position": 7,
"Guid": 7568294219059,
"DefaultValue": null,
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 482,
"SectionId": 120,
"DataTypeId": 8,
"DataTypeName": "Single Choice",
"Label": "My Single Choice Field",
"IsRequired": false,
"IsVisible": true,
"Position": 8,
"Guid": 5957387833874,
"DefaultValue": "Choice 1\nChoice 2\nChoice 3",
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 483,
"SectionId": 120,
"DataTypeId": 9,
"DataTypeName": "Multiple Choice",
"Label": "My Multiple Choice Field",
"IsRequired": false,
"IsVisible": true,
"Position": 9,
"Guid": 9747052228830,
"DefaultValue": "Item A\nItem B\nItem C",
"ReferenceObject": null,
"ConditionGroups": [],
"AppliedProperties": []
},
{
"FieldId": 484,
"SectionId": 120,
"DataTypeId": 10,
"DataTypeName": "Reference",
"Label": "My Contacts Reference Field",
"IsRequired": false,
"IsVisible": true,
"Position": 10,
"Guid": 1617698717842,
"DefaultValue": null,
"ReferenceObject": {
"FieldReferenceObjectId": 66,
"FieldId": 484,
"ObjectId": 7,
"Object": null,
"KeyType": "Int32",
"DisplayFormat": "%Val%",
"IsSystemObject": true,
"Name": "Contact",
"DefaultValues": []
},
"ConditionGroups": [],
"AppliedProperties": []
}
]
}
]
}