Actions Reference
Use this page to choose an Alert Relay action and check its main inputs and outputs. Follow the linked action guide for examples, paging instructions, and troubleshooting.
Choose an action
| Action | Choose it when you need |
|---|---|
| Get Item or File Changes as Alert HTML | A suggested subject and ready-to-use HTML for an alert email. |
| Get Detailed Item or File Changes | Structured previous and current field values for flow logic or an agent response. |
| Get Item or File Version History | Several historical versions, selected field values over time, or an inclusive version range. |
| Parse SharePoint Version Information | A decoded SharePoint trigger token or a non-billable decision about whether a visible version should be processed. |
Get Item or File Changes as Alert HTML
This action compares the current SharePoint item, file, or page with an earlier version and generates a suggested subject and formatted HTML. Use it when the next step will send an email or use HTML content.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
Site URL (siteUrl) |
String | Yes | The SharePoint site containing the item, file, or page. Select a site or enter its full URL. |
List or Library (listId) |
String | Yes | The exact list or library title, or its GUID. Select Site URL first to populate the picker. |
Item ID (itemId) |
Integer | Yes | The numeric SharePoint list item ID. For a document, do not use its file identifier. |
Compare From (triggerWindowStartToken) |
String | No | The earlier comparison point. Use a SharePoint trigger-window token, raw change token, version label, ISO 8601 date, or ISO 8601 date and time. Blank uses the oldest eligible retained version. |
Include Minor Versions (includeMinorVersions) |
Boolean | No | Includes minor or draft versions. Defaults to false. The connection must be allowed to see the requested versions. |
Include Unchanged Fields (includeUnchangedFields) |
Boolean | No | Includes unchanged fields in the generated HTML. Defaults to true. |
Date Format (dateFormat) |
String | No | The format for readable dates. Defaults to yyyy-MM-dd. |
Time Format (timeFormat) |
String | No | The format for readable times. Defaults to HH:mm:ss. |
Timezone (timezone) |
String | No | The timezone for readable date and time values. Defaults to UTC. |
For most flows started by a SharePoint change trigger, use Trigger Window Start Token as Compare From.
Outputs
| Output | Type | Description |
|---|---|---|
HTML Body (htmlBody) |
String | Ready-to-use HTML describing the item or file and its returned field changes. |
Generated Alert Subject (subject) |
String | A suggested subject using added-item or changed-item wording as appropriate. |
Item or File Name (itemTitle) |
String | The SharePoint item title or file name. |
Item or File URL (itemUrl) |
String | A direct link to the SharePoint item, file, or page. |
Is New Item (isNewItem) |
Boolean | true when the result should be presented as a newly added item or file. |
Success (success) |
Boolean | true when the action completed successfully. |
Message (message) |
String | A user-facing explanation of the result. |
Display User Notice (shouldDisplayUserNotice) |
Boolean | true when the returned trial, subscription, or usage notice should be shown. |
User Notice Code (userNoticeCode) |
String | A stable code for handling a notice. Omitted when there is no notice. |
User Notice Severity (userNoticeSeverity) |
String | information, warning, or critical. Omitted when there is no notice. |
User Notice (userNotice) |
String | Notice text to show the user. Omitted when there is no notice. |
User Notice Call to Action (userNoticeCallToAction) |
String | The recommended next step, including the Alert Relay website and support email. Omitted when there is no notice. |
Error (error) |
String | Technical error details when the action does not succeed. |
See Get Item or File Changes as Alert HTML for the complete action guide.
Get Detailed Item or File Changes
This action compares the current SharePoint item, file, or page with an earlier version and returns structured field-level changes. Use it for conditions, loops, custom messages, approvals, reports, or Copilot Studio answers.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
Site URL (siteUrl) |
String | Yes | The SharePoint site containing the item, file, or page. Select a site or enter its full URL. |
List or Library (listId) |
String | Yes | The exact list or library title, or its GUID. Select Site URL first to populate the picker. |
Item ID (itemId) |
Integer | Yes | The numeric SharePoint list item ID. For a document, do not use its file identifier. |
Compare From (triggerWindowStartToken) |
String | No | The earlier comparison point. Use a SharePoint trigger-window token, raw change token, version label, ISO 8601 date, or ISO 8601 date and time. Blank uses the oldest eligible retained version. |
Include Minor Versions (includeMinorVersions) |
Boolean | No | Includes minor or draft versions. Defaults to false. The connection must be allowed to see the requested versions. |
Include Unchanged Fields (includeUnchangedFields) |
Boolean | No | Includes supported fields that did not change. Defaults to true. Set it to false to return changed fields only. |
Date Format (dateFormat) |
String | No | The format for readable dates. Defaults to yyyy-MM-dd. |
Time Format (timeFormat) |
String | No | The format for readable times. Defaults to HH:mm:ss. |
Timezone (timezone) |
String | No | The timezone for readable date and time values. Defaults to UTC. |
Outputs
| Output | Type | Description |
|---|---|---|
Changed Fields (changedFields) |
Array | One entry for each returned SharePoint field. |
Has Comparison Baseline (hasComparisonBaseline) |
Boolean | true when Alert Relay resolved a distinct earlier version. |
Is Baseline First Version (isBaselineFirstVersion) |
Boolean | true when the comparison baseline is the first version recorded for the item or file. |
Is New Item (isNewItem) |
Boolean | true when the result should be presented as a newly added item or file. This is separate from Is Baseline First Version. |
Current Version Label (currentVersionLabel) |
String | The current SharePoint version label, such as 5.0. |
Previous Version Label (previousVersionLabel) |
String | The version label actually used as the comparison baseline. |
Item or File Name (itemTitle) |
String | The SharePoint item title or file name. |
Item or File URL (itemUrl) |
String | A direct link to the SharePoint item, file, or page. |
Modified Date (modifiedDate) |
Date and time | The latest modification date and time. |
Modified By (modifiedBy) |
String | The display name of the person who last modified the item or file. |
Success (success) |
Boolean | true when the action completed successfully. |
Message (message) |
String | A user-facing explanation of the result. |
Display User Notice (shouldDisplayUserNotice) |
Boolean | true when the returned trial, subscription, or usage notice should be shown. |
User Notice Code (userNoticeCode) |
String | A stable code for handling a notice. Omitted when there is no notice. |
User Notice Severity (userNoticeSeverity) |
String | information, warning, or critical. Omitted when there is no notice. |
User Notice (userNotice) |
String | Notice text to show the user. Omitted when there is no notice. |
User Notice Call to Action (userNoticeCallToAction) |
String | The recommended next step, including the Alert Relay website and support email. Omitted when there is no notice. |
Error (error) |
String | Technical error details when the action does not succeed. |
Changed Fields entries
| Field output | Type | Description |
|---|---|---|
Field Internal Name (internalName) |
String | The stable SharePoint internal name. Use it for flow logic. |
Field Name (displayName) |
String | The user-facing SharePoint field name. Use it in messages and reports. |
Column Value Has Changed (hasChanged) |
Boolean | true when the value changed between the baseline and current version. |
Previous Column Value (Text) (previousAsString) |
String | The previous value formatted as readable text. |
Current Column Value (Text) (currentAsString) |
String | The current value formatted as readable text. |
Previous Column Value (Detailed) (previous) |
Any supported value | The previous value as text, number, Boolean, object, array, or null, depending on the SharePoint field type. |
Current Column Value (Detailed) (current) |
Any supported value | The current value as text, number, Boolean, object, array, or null, depending on the SharePoint field type. |
See Get Detailed Item or File Changes for examples using Changed Fields.
Get Item or File Version History
This action returns a bounded, pageable history of a SharePoint item, file, or page, newest first. Use it to inspect selected field values across several versions or within an inclusive version, token, or date range.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
Site URL (siteUrl) |
String | Yes | The SharePoint site containing the item, file, or page. |
List or Library (listId) |
String | Yes | The SharePoint list or library. Select it while editing the action so its columns can become dynamic content. |
Item ID (itemId) |
Integer | Yes | The numeric SharePoint list item ID. For a document, do not use its file identifier. |
Maximum Usage Units (maximumUsageUnits) |
Integer | Yes | The maximum usage units the request may consume, from 1 to 50. Defaults to 1. This is a spending boundary, not a version limit. |
Maximum Versions (maximumVersions) |
Integer | No | The maximum complete version rows to return across all pages. Defaults to 20. |
Fields to Return (fieldsToReturn) |
Array | No | Up to 100 SharePoint columns to return in every version. Blank returns all supported columns. Custom values must be internal names or GUIDs. |
Compare From (fromVersion) |
String | No | The inclusive older boundary. Accepts a version label, trigger-window token, raw change token, ISO 8601 date, or ISO 8601 date and time. Blank means no older boundary. |
Compare To (toVersion) |
String | No | The inclusive newer boundary. Accepts a version label, trigger-window token, raw change token, ISO 8601 date, or ISO 8601 date and time. Blank means no newer boundary. |
Paging Token (continuationToken) |
String | No | The protected token from an earlier response when retrieving the next page manually. Use it exactly as returned. |
Include Minor Versions (includeMinorVersions) |
Boolean | No | Includes minor or draft versions. Defaults to false. The connection must be allowed to see them. |
Date Format (dateFormat) |
String | No | The format for readable dates. Defaults to yyyy-MM-dd. |
Time Format (timeFormat) |
String | No | The format for readable times. Defaults to HH:mm:ss. |
Timezone (timezone) |
String | No | The timezone for readable values and date-only boundaries. Defaults to UTC. |
The new Power Automate designer can initially show Fields to Return as a text box. Select the site and list, save or publish the flow, close it, and reopen it to load the column picker.
Each physical response contains no more than 100 versions. Enable Power Automate pagination and set its threshold when the action should collect more than one page automatically.
Outputs
| Output | Type | Description |
|---|---|---|
Versions (value) |
Array | Complete version rows, returned newest first. Power Automate combines this array across automatic pages. |
Success (success) |
Boolean | true when the request completed successfully. |
Message (message) |
String | A user-facing explanation of the result. |
Item ID (itemId) |
Integer | The requested SharePoint item ID. |
Item Title (itemTitle) |
String | The SharePoint item title or file name. |
Versions Returned (versionsReturned) |
Integer | Complete versions returned by the current physical request. |
Page Number (pageNumber) |
Integer | The current physical page number. |
Versions Returned Total (versionsReturnedTotal) |
Integer | Complete versions returned across the logical paging session so far. |
Fields Returned (fieldsReturned) |
Integer | SharePoint fields included in each version row. |
Usage Units Charged (usageUnitsCharged) |
Integer | Usage units charged for the current physical request. |
Cumulative Usage Units Charged (cumulativeUsageUnitsCharged) |
Integer | Total usage units charged across the logical paging session so far. |
Usage Unit Limit (usageUnitLimit) |
Integer | The caller's Maximum Usage Units boundary. |
Has More (hasMore) |
Boolean | Whether more matching history exists beyond this physical response. |
Can Continue (canContinue) |
Boolean | Whether another page can be retrieved within the protected limits and remaining usage budget. |
Paging Token (continuationToken) |
String | Protected token for manually requesting the next page. |
Next Link (nextLink) |
String | Continuation link used by Power Automate automatic pagination. Do not construct or edit it. |
Paging Token Expires At (continuationExpiresAt) |
Date and time | UTC time after which the paging token cannot be used. |
Truncation Reason (truncationReason) |
String | Why the response stopped before returning every matching version. |
From Version Resolution (fromVersionResolution) |
String | How the older boundary resolved: NotSpecified, Exact, ClampedInward, or NoOverlap. |
To Version Resolution (toVersionResolution) |
String | How the newer boundary resolved: NotSpecified, Exact, ClampedInward, or NoOverlap. |
Resolved From Version Label (resolvedFromVersionLabel) |
String | The actual inclusive older version after range resolution. |
Resolved To Version Label (resolvedToVersionLabel) |
String | The actual inclusive newer version after range resolution. |
History Changed During Paging (historyChangedDuringPaging) |
Boolean | true when an expected unreturned version became unavailable and paging moved inward. |
Error Code (errorCode) |
String | A stable reason when the request cannot return the requested result. |
Minimum Usage Units Required (minimumUsageUnitsRequired) |
Integer | The minimum budget required when the first complete matching version cannot fit within the selected limit. |
Display User Notice (shouldDisplayUserNotice) |
Boolean | true when the returned trial, subscription, or usage notice should be shown. |
User Notice Code (userNoticeCode) |
String | A stable code for handling a notice. Omitted when there is no notice. |
User Notice Severity (userNoticeSeverity) |
String | information, warning, or critical. Omitted when there is no notice. |
User Notice (userNotice) |
String | Notice text to show the user. Omitted when there is no notice. |
User Notice Call to Action (userNoticeCallToAction) |
String | The recommended next step, including the Alert Relay website and support email. Omitted when there is no notice. |
Version row outputs
| Output | Type | Description |
|---|---|---|
Version Label (versionLabel) |
String | The SharePoint version label, such as 4.0 or 4.1. |
Version Date (versionDate) |
Date and time | When SharePoint created the version. |
Version By (versionBy) |
String | The person who created the version. |
Is Minor Version (isMinorVersion) |
Boolean | Whether the row is a minor or draft version. |
Is First Version (isFirstVersion) |
Boolean or blank | Whether SharePoint confirms this is the item's first version. |
Is Oldest Available (isOldestAvailable) |
Boolean | Whether this is the oldest version currently available to the connection. |
Changed Field Count (changedFieldCount) |
Integer or blank | The number of returned fields changed from the preceding available version. |
Changed Fields (changedFields) |
Object | A change indicator for every returned SharePoint field. |
Version History Information (versionHistoryInfo) |
Object | Cumulative usage information and page-final continuation status preserved on version rows during automatic pagination. |
Each selected SharePoint field also becomes dynamic content on the version row. Complex fields can provide both a detailed value and a readable Text value.
See Get Item or File Version History for field selection, paging, limits, ranges, and examples.
Parse SharePoint Version Information
This non-billable action decodes a SharePoint trigger token. When supplied with version metadata, it can also decide whether a visible major or minor version should continue to a detailed Alert Relay action.
Inputs
| Input | Type | Required | Description |
|---|---|---|---|
Compare From (compareFrom) |
String | Yes | The SharePoint trigger's Trigger Window Start Token or a raw SharePoint change token. This input does not accept a version label or date. |
Version Number (versionNumber) |
String | No | A SharePoint version label such as 0.1, 1.0, or 1.5. Used to identify minor and first-version states. |
Modified Date (modifiedDate) |
Date and time | No | The visible SharePoint Modified value. Used with the token timestamp to decide whether a new visible version was detected. |
Include Minor Versions (includeMinorVersions) |
Boolean | No | Whether minor or draft versions should be processed. Defaults to false. Use the same setting in the detailed action that follows. |
Timezone (timezone) |
String | No | The timezone for local token and modified times. Blank returns UTC values without local values. |
Outputs
| Output | Type | Description |
|---|---|---|
Success (success) |
Boolean | true when the supplied token and version information were parsed successfully. |
Message (message) |
String | A user-facing explanation of the result or preflight decision. |
Token Date Time UTC (tokenDateTimeUTC) |
Date and time | The timestamp contained in Compare From, expressed in UTC. |
Token Date Time Local (tokenDateTimeLocal) |
Date and time or blank | The token timestamp in the selected timezone. Blank when no timezone is supplied. |
Decoded Token (decodedToken) |
String | The raw SharePoint change token after decoding. |
Is Base64 Token (isBase64Token) |
Boolean | true when the supplied token was Base64 encoded. |
Sequence (sequence) |
Integer | The SharePoint change sequence value contained in the token. |
List GUID (listGuid) |
GUID | The list or library GUID contained in the token. |
Token Version (tokenVersion) |
Integer | The SharePoint token version number. |
Token Type (tokenType) |
Integer | The SharePoint token type number. |
Is New Version Detected (isNewVersionDetected) |
Boolean or blank | true to continue, false to skip, or blank when there was not enough metadata to decide. |
Is Minor Version (isMinorVersion) |
Boolean or blank | Whether Version Number identifies a minor or draft version. |
Is First Minor Version (isFirstMinorVersion) |
Boolean or blank | true for the first minor version, normally 0.1. |
Is First Major Version (isFirstMajorVersion) |
Boolean or blank | true for the first major version, normally 1.0. |
Modified Date UTC (modifiedDateUtc) |
Date and time or blank | The supplied Modified Date normalized to UTC. |
Modified Date Local (modifiedDateLocal) |
Date and time or blank | The supplied Modified Date in the selected timezone. |
Error (error) |
String | Error details when parsing does not succeed. |
This action does not return trial, subscription, or usage notices and does not perform an additional entitlement read.
See Parse SharePoint Version Information for the three-state decision and example flow pattern.
Shared comparison rules
- For the two change actions, blank Compare From uses the oldest eligible retained version rather than the immediately preceding version.
- For Version History, Compare From and Compare To are inclusive older and newer boundaries. Blank means that boundary is not specified.
- Minor version labels require Include Minor Versions to be
true. - Date-only comparison values use midnight in the selected Timezone, or UTC when no timezone is selected.
- A SharePoint trigger window can cover several edits. It does not always represent only the immediately preceding item version.
See Choose a Comparison Baseline for full token, version, date, blank-value, and range-resolution behaviour.
Using actions in Copilot Studio
Add Alert Relay actions to an agent as tools:
- Use Get Detailed Item or File Changes for one before-and-after explanation.
- Use Get Item or File Version History for several versions or a historical range.
- Use Get Item or File Changes as Alert HTML when a process specifically needs generated notification HTML.
- Use Parse SharePoint Version Information in a controlled topic or flow rather than for a general user question.
The connection identity determines which SharePoint content the tool can access. Configure fixed site and list values for a scoped agent, and require the agent to ask for missing item or boundary information instead of inventing identifiers.
See Use Alert Relay in Copilot Studio for setup, authentication, input configuration, and testing.