Find Entity

Audience: Low-code Engineers

Skill Prerequisites: Actions, Connectors, Tokens

Searches a Dynamics 365 / Dynamics CRM entity (table) with conditions and loads the first matching record into tokens. You pick which attributes (columns) to read and the token name for each one.

Use it when you know something about the record, like an email address or account number, but not its GUID. If you already have the GUID, use Read Entity.

note

This action is part of the Dynamics (CRM, 365) add-on (DnnSharp.DynamicsCrm). The add-on is installed separately and needs the DYNCRM feature in your license. If it isn't licensed, the action fails with a "not licensed" error. If you don't see the Dynamics actions, the add-on isn't installed.

Typical Use Cases

• Find a contact by email address before creating or updating it
• Get the GUID of an account from its account number, then use it in Update Entity or Delete Entity
• Get the newest or oldest record that matches a filter, using Order By
• Show Dynamics data, such as a customer's name or status, on a form or page

Don't use it to

• Read a record whose GUID you already have. Use Read Entity instead.
• Get more than one record. Use Read Multiple Entities instead.
• Check whether a record exists by mapping its Id. If nothing matches and Id Mapping is set, the action fails. See When nothing matches.

Related Actions

Action Name	Description
Read Entity	Reads one record by its GUID.
Read Multiple Entities	Reads all matching records into a list.
Create Entity	Creates a record.
Update Entity	Updates a record by its GUID.
Delete Entity	Deletes a record by its GUID.
Test Connector	Checks that a Dynamics Service Connector can sign in.

Input Parameter Reference

Parameter	Description	Supports Tokens	Default	Required
Connector	The Dynamics Service Connector that holds the Dynamics server address and sign-in details. See Connectors.	No	empty	Yes
Logical Name	The entity to search. The list shows the entities of the selected connector by display name. The value saved is the entity's logical name, for example contact or account. You can also type a logical name or a token. The value is converted to lowercase.	Yes	empty string	Yes
Id Mapping	The name of the token that receives the GUID of the found record, for example ContactId. Leave it empty if you don't need the GUID. It can't be the same as one of the Output Token Name values in Attribute Mapping.	Yes	empty string	No
Attribute Mapping	The attributes to read. For each row, enter the attribute's logical name in Attribute Name, for example fullname, and the token to create in Output Token Name, for example ContactName. See Output tokens.	No	None	No
Conditions	The filter. Each row has a Logical Operator (And/Or), an Attribute Name (logical name), a Condition Operator and a Value. See Conditions. With no rows, any record can match.	Only in Value	None	No
Order By	Sorts the matches before the first one is taken. Each row has an Attribute Name and an Order Type. See Considerations.	No	None	No

Output Parameters Reference

Token	Description
[<Id Mapping>]	The GUID of the found record, for example [ContactId]. Only created when Id Mapping is set.
[<Output Token Name>]	One token per row of Attribute Mapping, holding the attribute's value, for example [ContactName].
[<Output Token Name>:Id], [<Output Token Name>:Name], [<Output Token Name>:LogicalName]	Extra tokens for reference attributes (Lookup, Customer, Owner): the referenced record's GUID, its name and its entity logical name, for example [ParentAccount:Id].

Output tokens

The value in each token depends on the attribute type:

• If Dynamics returns a formatted value for the attribute, the token gets that. For example, an option set gives its label (Active), not its number. Money and number values may include currency symbols or thousands separators.
• Date and time attributes are never formatted. They're written in ISO 8601 format, for example 2026-09-27T14:30:00.0000000Z. Date Only attributes use the short date format of the current culture.
• Otherwise, the raw value is used: money as its amount, option sets as their number, and references as the GUID.
• For reference attributes (Lookup, Customer, Owner), use the :Id token when you need the GUID. The main token may hold the record's name instead.
• If the attribute is empty in Dynamics, the token is empty.

Conditions

Each row compares an attribute with a value. The Value column supports tokens. The Attribute Name column doesn't.

Condition Operator	Value
Equal, NotEqual, GreaterThan, LessThan, GreaterEqual, LessEqual	One value.
Like, NotLike	One value. Use % as the wildcard, for example %@example.com.
Contains, DoesNotContain, BeginsWith, DoesNotBeginWith, EndsWith, DoesNotEndWith	One value.
In, NotIn	One value per line.
Between, NotBetween	Two values, one per line: the low value, then the high value.
Null, NotNull	No value.

Rows are combined with And. When a row's Logical Operator is Or, an Or group starts at that row, and the rows after it go into that group. For example, rows A, Or B, C mean A And (B Or C). Keep filters simple, or put the Or rows last.

When nothing matches

• If Id Mapping is empty, the action succeeds and all the attribute tokens are set to empty strings.
• If Id Mapping is set, the action fails with an error.

To check whether a record exists, leave Id Mapping empty and test a mapped attribute that's never empty, for example [ContactEmail] != "". Or use Read Multiple Entities with Output Total Records Count.

Considerations

• Only the first match is used. If several records match, the others are ignored. Add conditions or Order By so the right one comes first.
• Order Type isn't applied in 1.28. Sorting always uses ascending order, whatever Order Type says. To get the newest record, filter on a date instead, or use Read Multiple Entities and pick the entry you need.
• Use logical names. Entity and attribute names are the lowercase logical names, such as emailaddress1, not display names such as Email. An unknown attribute name makes the action fail.
• Conditions compare with Dynamics values. For option sets, compare with the number (for example 0), not the label. For references, compare with the GUID.
• The sign-in is cached. The connection is reused until its security token is about to expire. Use Test Connector to check a connector. See Add Connector to create one in actions.
• Errors. Wrong sign-in details, a wrong entity name or an invalid condition make the action fail. Use the On Error actions of Execute Actions to handle it.

Examples

tip

To understand how to use the below examples, please see Running Examples.

In these examples, replace the connector Entry value with the ID of your own Dynamics Service Connector, or select the connector after importing.

1. Find a contact by email address

This action searches contacts that have a name for the address in the Email token. It saves the contact's GUID in [ContactId], its name in [ContactName] and its parent account in [ParentAccount], [ParentAccount:Id], [ParentAccount:Name] and [ParentAccount:LogicalName].

{
    "Title": "Find Entity",
    "ActionType": "DynamicsCrm.FindEntity",
    "Description": "Find the contact with this email",
    "Parameters": {
        "Credentials": {
            "Entry": "00000000-0000-0000-0000-000000000000"
        },
        "LogicalName": "contact",
        "IdMapping": "ContactId",
        "AttributeMapping": {
            "fullname": "ContactName",
            "parentcustomerid": "ParentAccount"
        },
        "Conditions": [
            {
                "LogicalOperator": "And",
                "AttributeName": "emailaddress1",
                "ConditionOperator": "Equal",
                "Value": "[Email]"
            },
            {
                "LogicalOperator": "And",
                "AttributeName": "fullname",
                "ConditionOperator": "NotNull",
                "Value": ""
            }
        ]
    }
}

The action fails if no contact matches, because Id Mapping is set. Use the next example when a match isn't guaranteed.

2. Check whether an account number is already used

This action leaves Id Mapping empty, so it doesn't fail when nothing matches. Afterwards, [ExistingAccountNumber] is empty if no account has that number. A later action can use a condition such as [ExistingAccountNumber] != "".

{
    "Title": "Find Entity",
    "ActionType": "DynamicsCrm.FindEntity",
    "Description": "Look for an account with this number",
    "Parameters": {
        "Credentials": {
            "Entry": "00000000-0000-0000-0000-000000000000"
        },
        "LogicalName": "account",
        "AttributeMapping": {
            "accountnumber": "ExistingAccountNumber",
            "name": "ExistingAccountName"
        },
        "Conditions": [
            {
                "LogicalOperator": "And",
                "AttributeName": "accountnumber",
                "ConditionOperator": "Equal",
                "Value": "[AccountNumber]"
            }
        ]
    }
}

Revised 09/27/2026