Documentation
Start typing to search…

Lookup Record

Definition

The Lookup Record action allows you to find and retrieve a single record from a specified zenphi Table by matching specific search criteria. This action is fundamental for workflows that need to access existing data, enabling you to fetch information based on one or more conditions you define.

  • Key capabilities:
    • Search any zenphi Table using one or more conditions (e.g., find a user where 'Email' equals '[email protected]').
    • Select specific fields to retrieve, making your data flow more efficient.
    • Determine if a record was found, allowing for conditional logic in your flow.

This action serves as a crucial data retrieval tool, enabling your automations to work with specific, existing information from your zenphi Tables.

Inputs

  1. Table

    • Purpose: This field is for selecting the specific zenphi Table you want to search for a record in.
    • Practical Guidance: You will typically choose a table from a dropdown list that populates with all the tables available in your zenphi environment. This is almost always a static value selected when you build the flow.
    • Use Case Context: You would use this field to select your "Projects" table to find information about a specific project.

  2. Condition

    • Purpose: This section allows you to define the specific rules or criteria that a record must meet to be selected. You can add multiple conditions and link them with 'and' or 'or' logic to create precise queries.
    • Practical Guidance: For each condition, you will define three parts: the column to search, the operator to use for comparison, and the value to match. The value can be a static value (e.g., you type the text "Completed" to find records with that exact status) or a dynamic value from the token picker (e.g., you use the 'Submitter Email' token from a form trigger to find a record matching the person who submitted the form).
    • Use Case Context: You would use this to configure a search to find a record where the 'Status' column is equal to "In Progress".
    • Properties:
      • column: The specific column within the selected table that you want to evaluate.
      • operator: The comparison rule to apply, such as equal to, contains, starts with, or is not null.
      • value: The data used for the comparison, which can be hardcoded or supplied dynamically from a previous action.

  3. Select fields to retrieve record data

    • Purpose: This field lets you choose which specific columns (fields) of data you want the action to return once it finds a matching record.
    • Practical Guidance: You can select one or more fields from a list of all available columns in the table. By selecting only the fields you need, you make your flow more efficient. For example, instead of retrieving all 20 columns for a customer, you might only need their 'Email' and 'Subscription ID'.
    • Use Case Context: You would use this to retrieve only the 'Phone Number' and 'Contact Person' fields from a record in your "Clients" table.

  4. Number of records to skip

    • Purpose: This field allows you to ignore a specified number of matching records before selecting the one to return.
    • Practical Guidance: This is useful for pagination or if your conditions might match multiple records and you don't want the very first one. For example, setting this to 1 will skip the first matching record and return the second one. You can use a static number or a dynamic value from a loop or calculation.
    • Use Case Context: You would set this field to '2' to find the third employee record that matches the condition 'Department equals Sales'.

Outputs

  1. Found Record

    • Data Description: This output is a simple boolean (true or false) value that indicates whether a record matching your conditions was successfully found.
    • Workflow Utility: This is extremely useful for controlling the path of your flow. You can use this output in an 'If Condition' action to create different branches. For example, if 'Found Record' is true, you can proceed to update the record. If it's false, you could branch to a 'Create Record' action instead.

  2. Record

    • Data Description: This is an object containing all the data from the fields you chose to retrieve in the input configuration, along with the record's unique ID and version.
    • Workflow Utility: This output holds the core data you need for subsequent steps. You can use the tokens from this object to populate fields in other actions. For example, you could use the Record.Email token in a 'Send Email' action or the Record.Status token in a conditional logic check.
    • Properties:
      • Record id: The unique identifier (GUID) for the record in the zenphi Table. This ID is essential for accurately targeting this specific record in later steps, such as an 'Update Record' or 'Delete Record' action.
      • Version: An identifier that tracks changes to the record over time.

Example Use Cases

  1. Validate User Existence Look up a user's email from a form submission in an "Employees" table to verify they are a valid employee before proceeding with a request.
  2. Retrieve Data for Notifications Find a specific project record by its ID to get the project manager's email address and send them an automated status update.
  3. Prevent Duplicate Entries Before creating a new client record, perform a lookup to check if a record with the same company name or email already exists.
  4. Route Dynamic Approvals Look up an employee's record to retrieve their manager's ID, then use that information to assign an approval task for a leave request.
  5. Enrich Data in a Workflow Find a product record using a SKU from an order form to pull its price, description, and inventory level for use in subsequent actions.

Example

Scenario: Your HR department uses a zenphi Form for employees to submit IT support requests. To ensure requests are routed to the correct department and manager for awareness, the workflow needs to automatically find the employee's details (like their department and manager's email) from a central "Employee Directory" table based on the email address they provide in the form.

Steps to Implement:

  1. Set Up the Trigger. Start the flow with a "zenphi Form" trigger. The form should have fields for the employee's request details and will automatically capture the submitter's email address.
  2. Configure the "Lookup Record" action. Add the action immediately after the trigger to find the employee who submitted the form.
    • Table: Select the "Employee Directory" zenphi Table from the dropdown list.
    • Condition: Configure the search criteria to find the specific employee.
      • column: Select the Email column.
      • operator: Choose equal to.
      • value: Use the token picker to select the Submitter Email token from the form trigger.
    • Select fields to retrieve record data: Check the boxes for the Department and Manager Email fields, as this is the information needed for routing.
  3. Use the Retrieved Data. Add an "If Condition" action to check the Found Record output.
    • If Found Record is true, add an "Assign a Task" action inside the "Yes" branch. Use the Record.Manager Email token from the Lookup Record action to assign a notification task to the employee's manager.
    • If Found Record is false, add a "Send Email" action in the "No" branch to notify an administrator that an unknown user submitted a request.

Outcome: This automation instantly enriches incoming requests with crucial data from the master employee list. It eliminates the need for manual lookups, ensures requests are routed accurately based on the employee's department, and keeps managers informed automatically. This saves significant time for the HR and IT teams and reduces the risk of human error.

Best Practices

  1. Always Handle the "Not Found" Scenario Use the boolean Found Record output in an "If Condition" action immediately after the lookup. This allows you to build a robust workflow that defines what should happen if a record is found (the "Yes" path) versus what should happen if it isn't (the "No" path), preventing potential errors downstream.

  2. Retrieve Only the Fields You Need Use the Select fields to retrieve record data option to specify exactly which columns you require for subsequent steps. Retrieving all fields from a wide table can slow down your flow and clutter the token menu. Limiting the data pull makes your workflow more efficient and easier to manage.

  3. Use Unique Identifiers for Conditions Whenever possible, structure your condition to search on a column that contains a unique value (e.g., Employee ID, Email Address, Order Number). This ensures the Lookup Record action finds the exact single record you intend to work with and avoids ambiguity if multiple records could match a less specific condition.

  4. Combine with Update or Create Actions The Lookup Record action is most powerful when used to check for the existence of data before modifying it. A common pattern is: Lookup Record -> If Found -> Update Record; If Not Found -> Create Record. This "upsert" logic is fundamental for keeping your data tables synchronized and accurate.

Updated about 7 hours ago