Use a list add action to create a new item in a configured SharePoint list, or to add-or-update an item when a matching record already exists. It is suitable for handing a structured service result to a team that works from a list.

Configure the site connection and both QA and production lists before creating the action. Treat the list schema as an integration contract: changing a column name or type without reviewing the action can break the service.

Choose between adding and adding-or-updating

Choose Add a new item when every completion should become a distinct list item. Choose Add or update when the service should maintain one item for a known business key, such as a case reference.

flowchart TD
  A[Validated service values] --> B{Write mode}
  B -- Add new item --> C[Create a list item]
  B -- Add or update --> D[Run matching list lookup]
  D -- Match --> E[Update existing item]
  D -- No match --> C

Add-or-update requires a separate list lookup action that finds the existing item. Put the lookup before the list add action, use the lookup’s Action ID in Site Lookup Action, and test both match and no-match routes. Without a reliable unique key, add-or-update can overwrite the wrong item.

Configure the destination

1. Select the configured SharePoint site connection.
2. Choose the intended List to work with in the QA environment.
3. Choose the corresponding List to work with in the Production environment.
4. Confirm the lists have matching business columns and data types.
5. Add the column mapping.

Keep QA and production separate. Test data must never be written to the operational list, and a QA success does not prove that the production list permissions and columns are correct.

Map columns to service values

For each value, select the QA and production column names, enter the Column value, and choose the corresponding Column data type. The visible Column name is useful for maintainers; use it to describe the business purpose of the mapping.

Values can use Liquid. Keep formatting and transformation explicit: use an Assign action first when the list needs a computed value. For each mapping, confirm that blank optional answers, long text and choice values remain valid for the target column.

Use Indexed columns only where the list owner has designed and approved indexes. Indexes can improve queries, but they are not a substitute for an effective business key or sensible list design.

Order the actions safely

Place a list lookup before an add-or-update action. Place any Assign actions that prepare values before the list write. Put a redirect last, after the list operation and any required confirmation work.

Choose a trigger after the page has validated if the mapped values come from that page. For a final operational hand-off, the service-completion trigger may be more appropriate. Avoid a page-load trigger for a write action unless repeated visits are deliberately safe; a return to the page could create duplicate items.

Test the operational outcome

In QA, check the list item itself rather than stopping at a successful journey. Confirm the correct columns, values, types, link shape and destination. Test a missing optional value, a duplicate key, an edited journey and the add-or-update match/no-match cases.

Agree with the list owner how errors are monitored and resolved. A failed write should lead to a defined operational process, not an invisible gap between the service and the team receiving the work.

Test checklist

• QA and production use the intended, separate list destinations.
• Each mapped column exists and has the expected data type in both environments.
• Liquid values and optional fields produce valid list values.
• Add a new item and add-or-update are chosen for the correct business need.
• Add-or-update has a reliable preceding lookup and unique key.
• Revisiting a page cannot create accidental duplicate items.
• QA tests verify the written list item, not only the service page.

Related guidance

• List lookup actions
• SharePoint site link settings
• Shared action settings
• Assign actions