**Alert Relay Documentation**

Guidance for building Alert Relay flows, choosing the right action, and understanding SharePoint version-history comparisons.

# Get Detailed Item Changes

Use `Get Detailed Item Changes` when you want structured change data between two versions of a SharePoint list item, document, or site page.

This action is useful when the flow needs to inspect previous and current values, not just detect that an item was modified.

## When to use this action

Use `Get Detailed Item Changes` when you want to:

- inspect changed columns individually
- branch on specific change scenarios
- build your own email or Teams message
- create custom approvals or business rules
- reuse the same change data in multiple later steps

## Inputs

- **Site URL** (`siteUrl`): string. The SharePoint site that contains the list or library.
- **List or Library** (`listId`): string. The SharePoint list or library that contains the item. You can select it from the dropdown, enter the exact list title, or enter the list GUID.
- **Item ID** (`itemId`): integer. The SharePoint item `ID`, usually from the trigger.
- **Compare From** (`triggerWindowStartToken`): string. For most trigger-based flows, use `TriggerWindowStartToken`. If left blank, Alert Relay compares the current item against the first version in the item's version history.
- **Include Minor Versions** (`includeMinorVersions`): boolean. Includes draft or minor versions in the comparison instead of using major versions only. Defaults to `false`.
- **Include Unchanged Fields** (`includeUnchangedFields`): boolean. Includes unchanged fields in the response as well as changed fields. Defaults to `true`.
- **Date Format** (`dateFormat`): string. Controls how dates are displayed in the output. Defaults to `yyyy-MM-dd`.
- **Time Format** (`timeFormat`): string. Controls how times are displayed in the output. Defaults to `HH:mm:ss`.
- **Timezone** (`timezone`): string. Controls which timezone Alert Relay uses when displaying date and time values. Defaults to `UTC`.

## Outputs

- **Success** (`success`): boolean. `true` if the action completed successfully.
- **Message** (`message`): string. A human-readable message describing the result.
- **Changed Fields** (`changedFields`): array. Field-by-field comparison results.
- **Has Comparison Baseline** (`hasComparisonBaseline`): boolean. `true` if Alert Relay found a distinct earlier version to compare against.
- **Is Baseline First Version** (`isBaselineFirstVersion`): boolean. `true` if the baseline version used for comparison is the first version in the item's version history.
- **Current Version Label** (`currentVersionLabel`): string. The version label of the current item version, such as `5.0`.
- **Previous Version Label** (`previousVersionLabel`): string. The version label used as the comparison baseline.
- **Item Title** (`itemTitle`): string. The title of the SharePoint item, or the file name where appropriate.
- **Item URL** (`itemUrl`): string. A link back to the SharePoint item.
- **Modified Date** (`modifiedDate`): date-time. The modified date of the current item version.
- **Modified By** (`modifiedBy`): string. The display name of the user who last modified the item.
- **Error** (`error`): string. Error details when the action fails.

## Understanding Changed Fields

**Changed Fields** (`changedFields`) is an array designed for Power Automate actions such as:

- `Apply to each`
- `Filter array`
- `Select`
- conditions

Each entry includes:

- **Field Internal Name** (`internalName`): string. The internal SharePoint field name.
- **Field Name** (`displayName`): string. The user-friendly SharePoint field name.
- **Previous Column Value (Detailed)** (`previous`): dynamic. The previous field value in its raw form.
- **Current Column Value (Detailed)** (`current`): dynamic. The current field value in its raw form.
- **Column Value Has Changed** (`hasChanged`): boolean. `true` if the field value changed between the current version and the comparison baseline.
- **Previous Column Value (Text)** (`previousAsString`): string. The previous field value formatted as display text.
- **Current Column Value (Text)** (`currentAsString`): string. The current field value formatted as display text.

## Recommended usage pattern

For the cleanest flows:

1. call `Get Detailed Item Changes`
2. set `Include Unchanged Fields` to `false` if you only want changed fields
3. use `Filter array` only if you need extra filtering beyond that, such as a specific field or subset of changes
4. loop over the result if you need per-column logic
5. use the formatted string values for user-facing messages
6. use the raw values only when your flow logic needs them

## Formatted values vs raw values

In many cases, **Previous Column Value (Text)** (`previousAsString`) and **Current Column Value (Text)** (`currentAsString`) are the easiest values to use in messages because they are already prepared for display.

Use **Previous Column Value (Detailed)** (`previous`) and **Current Column Value (Detailed)** (`current`) when:
- you need to inspect a structured value
- you need to compare raw data in a condition
- you are building more advanced flow logic

## Example scenarios

### Send an alert only when a specific field changes

Power Automate can already tell you whether a field changed.

The stronger use case for Alert Relay is when you need to know how the field changed between versions.

Use `Filter array` or an `Apply to each` loop to find a field where:

- **Field Name** (`displayName`) or **Field Internal Name** (`internalName`) matches the target field
- **Column Value Has Changed** (`hasChanged`) is `true`
- the previous and current values match the target change scenario

For example:
- **Status** changed from `Draft` to `Approved`
- **Priority** changed from `Normal` to `High`
- **Assigned To** changed from one person to another

### Send a manager email with a custom summary

Use:
- **Item Title** (`itemTitle`)
- **Modified By** (`modifiedBy`)
- **Modified Date** (`modifiedDate`)
- selected **Changed Fields** (`changedFields`)

Then build your own custom message.

This is especially useful when the message needs to mention the actual before-and-after values rather than just saying that the item changed.

### Trigger different downstream actions for different changes

Alert Relay is especially useful when your flow needs to react to specific version-history-based changes, not just to the fact that an item was modified.

For example:
- if **Field Name** (`displayName`) is `Status` and **Previous Column Value (Text)** (`previousAsString`) is `Draft` while **Current Column Value (Text)** (`currentAsString`) is `Approved`, notify the publishing team
- if **Field Name** (`displayName`) is `Assigned To` and the assignee changed from one person to another, notify the new assignee
- if **Field Name** (`displayName`) is `Priority` and the value changed from `Normal` to `High`, create an escalation task
- if **Field Name** (`displayName`) is `Due Date` and the due date moved out, notify stakeholders about the schedule change

## Notes on unchanged fields

If `Include Unchanged Fields` is `true`, the action can return a fuller list of fields.

If you only want a tighter response, set it to `false`.