Records steps

Records steps work on one row at a time (or one row and its related rows). Most of them identify the row with a table and an Entity Id, an expression that gives a lookup to that row, such as a flow input, a column of a row you read earlier, or a step result.

Dynamics 365 CE on-premisesWordingApplies to the other edition

On-premises, step descriptions say “record” where Dataverse says “row”, and the Row type is called Entity.

Get Entity By Id

Reads one row by its id, with the columns you choose.

Setting	What it does	Required
Entity Type	The table to read from.	Yes
Entity Id	An expression that gives a lookup to the row.	Yes
Columns	The columns to read, chosen in the property picker.	No

Outputs: <Step>, one row with the chosen columns.

Behavior: if no row has that id, the step does not fail. The variable is simply empty. Test for that with a Condition (for example Not Null(GetAccount)) before using the row. Read only the columns you need.

Example: read the Account from the input AccountId with Account Name, Credit Limit and Owner, before checking its credit.

Get Entities By Relationship

Reads the rows related to a row through a relationship.

Setting	What it does	Required
Relationship Type	One To Many or Many To Many.	Yes
Entity Type	The table of the row you start from.	Yes
Entity Id	The row you start from.	Yes
Relationship	The relationship to follow, picked from the table’s relationships.	Yes
Entity Role	Entity One or Entity Two. Shown only for a many-to-many relationship of a table with itself.	When shown
Columns	The columns of the related table to read.	No

Outputs: <Step> Entities, a list of rows.

Example: get all Contacts of an Account through the one-to-many relationship, then loop over them with an Iterator.

Save Entity

Creates a row, or updates one. It creates when the row has no id yet and updates when it has one.

Setting	What it does	Required
Entity	An expression that gives a row: a New Variable of type Row, or a row read earlier and changed with Update Variable.	Yes
Template Logical Name	The table to save to, when the row comes from a template (Template Definition type).	For template rows
Template Id	An optional id, shown only for template rows.	No
Reload Entity after Save	When on, the columns you set are refreshed with the values the server stored, for example values changed by other business logic or calculated by the system.	No

Outputs: none of its own. After a create, the row variable you saved holds the new id, so later steps can use it as a lookup.

Behavior: Save Entity takes the whole row. You set the field values beforehand with Update Variable.

Example: New Variable FollowUp of type Row (Task); Update Variable sets Subject, Regarding and Due Date; Save Entity with Entity = FollowUp creates the task.

Delete Entity

Deletes one row.

Setting	What it does	Required
Entity Type	The table.	Yes
Entity Id	A lookup to the row to delete.	Yes

Outputs: none.

Example: delete a temporary “Draft Quote Line” row after it has been copied to the final quote.

Clone Record

Copies a row and, optionally, its child rows.

Setting	What it does	Required
Table and record	The row to copy.	Yes
Copy Related Records	One-to-many relationships whose child rows are copied too. One level deep.	No
Add Field to Change on the Copy	Values that replace copied values on the new row. Empty: “The copy keeps the original values”.	No

Outputs: <Step>.Output.recordId, a lookup to the new row.

Behavior:

• Only columns that can be set when creating a row are copied.
• The owner, the status and status reason, and the business process position are never copied. The copy starts active and is owned by the user who runs the flow.
• Activity parties (To, CC and so on) are copied as new parties.
• Child rows are read before anything is created. If there are more than 5,000 child rows, the step fails and nothing is created.
• If copying a child row fails after the main copy was created, the error names the copy that was created and the child that failed.

Example: clone last year’s Opportunity with its Opportunity Products, and set Topic on the copy to Concatenate("Renewal - ", GetOpp.name).

Assign Record

Gives a row to a new owner, a user or a team.

Setting	What it does	Required
Table and record	The row to assign.	Yes
New Owner	An expression that gives a user or a team, for example an owner lookup or a Team constant.	Yes

Outputs: none.

Behavior: the owner must be a user or a team; otherwise the editor shows “The new owner must be a user or a team.” Works the same on Dataverse and on-premises.

Example: when a Case is escalated, assign it to the Tier 2 Support team.

Set State / Status

Activates, deactivates or otherwise changes a row’s status.

Setting	What it does	Required
Table and record	The row to change. Changing the table clears State and Status Reason.	Yes
State	The new status, picked from the table’s own values.	Yes
Status Reason	The new status reason. When empty, the state’s default status reason is used.	No

Outputs: none.

Behavior: Case, Opportunity, Quote and Order have their own close operations and are not supported. Use Execute SDK Message with messages such as CloseIncident or WinOpportunity for those.

Example: deactivate a Contact (State = Inactive) when its Account is closed.

Share / Unshare Record

Shares a row with users or teams, changes their rights, or removes the share.

Setting	What it does	Required
Action	Share (add rights), Change rights or Unshare.	Yes
Table and record	The row to share.	Yes
Users and Teams	One or more entries (Add User or Team). Each can be a user, a team, or a list of them, such as the output of Resolve Recipients.	Yes, at least one
Access Rights	Any of Read, Write, Delete, Append, Append To, Assign, Share.	Unless the action is Unshare

Outputs: none.

Behavior:

• Share (add rights) adds the rights you tick to any the user or team already has.
• Change rights replaces their rights with the ones you tick.
• Only users and teams can receive a share (“A record can only be shared with users and teams.”).
• Duplicate users and teams are removed.

Example: share a confidential Opportunity with Read and Write for the deal desk team, then unshare it when the deal closes.

Add / Remove Team Member

Adds users to a team, or removes them.

Setting	What it does	Required
Action	Add members or Remove members.	Yes
Team Type	Owner team or Record access team.	Yes
Team	The owner team.	For owner teams
Record	The row whose access team you change.	For access teams
Access Team Template	The access team template of that row’s table.	For access teams
Users	One or more entries (Add User). Each can be a user or a list of users.	Yes, at least one

Outputs: none.

Behavior:

• Only users can be members.
• For owner teams, users who are already in the team (or already out of it) are skipped, so duplicates do not make the step fail.
• For access teams, users are added to or removed from that row’s access team.

Example: when an Account’s manager changes, remove the old manager from the Account’s access team (template “Account Team”) and add the new one.

Queue

Works with queues. The fields depend on the Action you choose.

Setting	What it does	Required
Action	Add to queue, Pick (assign to a user), Release back to the queue, Remove from queue or Route with routing rules.	Yes
Record	The row to queue or route.	For Add to queue and Route with routing rules
Queue	The queue to add the row to.	For Add to queue
Move from Queue	A queue to move the row out of.	No (Add to queue)
Queue Item	The queue item to pick, release or remove.	For Pick, Release and Remove
User	The user who picks the item.	For Pick
Remove the item from the queue	When ticked, picking also removes the item from the queue.	No (Pick)

Outputs: for Add to queue only, <Step>.Output.queueItemId, a lookup to the new queue item.

Example: add a new Case to the Billing queue, then pick the returned queue item for the case owner with a second Queue step.

Recalculate Rollup

Recalculates rollup columns of a row now, instead of waiting for the system’s scheduled rollup job.

Setting	What it does	Required
Table and record	The row whose rollups to recalculate.	Yes
Rollup Columns	One or more rollup columns. If the table has none, the editor shows “This table has no rollup columns.”	Yes

Outputs: none. To use the new values, read the row again with Get Entity By Id afterwards.

Example: after creating invoices, recalculate the Account’s “Total Invoiced” rollup and read it back for a credit check.

Add Entity Annotation

Adds a note, optionally with a file attached, to a row.

Setting	What it does	Required
Entity Type	The table of the row.	Yes
Entity Id	The row to attach the note to.	Yes
Title	The note’s title. The editor shows it as optional, but a step without a Title fails when it runs. A title that is empty at run time is fine.	Yes (at run time)
Description	The note’s text. Always set it, even to an expression that can be empty: a step without a Description fails when it runs.	Yes (at run time)
Is Document	When on, the note carries a file, and File Name and Content appear.	No
File Name	The file name, including its extension.	When Is Document is on
Content	The file content as text, for example Base64 from an API response.	When Is Document is on

Outputs: none.

Behavior: the file type is set from the file name’s extension (pdf, docx, png and so on).

Example: attach the signed contract PDF returned by an e-signature API to the Quote as Signed Contract.pdf.

Associate Relationship

Links two rows through a many-to-many relationship. The editor lists only the table’s many-to-many relationships; to link rows through a one-to-many relationship, set the lookup column and save the row instead.

Setting	What it does	Required
Entity Type	The table of the first row.	Yes
Entity Id	The first row.	Yes
Relationship	The many-to-many relationship.	Yes
Entity Role	Entity One or Entity Two, for a relationship of a table with itself.	When shown
Entity	The other row.	Yes

Outputs: none.

Example: add a Contact to a Marketing List.

Associate Multiple Relationship

Like Associate Relationship, but links one row to several rows at once.

Setting	What it does	Required
Entity Type, Entity Id	The row to link from.	Yes
Relationship	The many-to-many relationship.	Yes
Entity Role	For a relationship of a table with itself.	When shown
Entities	A list of the rows to link to.	Yes

Outputs: none.

Example: link all products returned by a query to a Campaign.

Disassociate Relationship

Unlinks two rows. The settings are the same as Associate Relationship.

Example: remove a Contact from a Marketing List when the contact unsubscribes.

Disassociate Multiple Relationship

Unlinks one row from several rows. The settings are the same as Associate Multiple Relationship.

Example: remove every discontinued product from a Campaign.

Related

• Queries steps
• Variables
• Flow step reference