Link Menu Expand (external link) Document Search Copy Copied
This website is for Zenphi public documentation.

Find Row

Definition

The Find row action in Smartsheet enables you to retrieve the data from a single, specific row within a sheet based on its unique identifier. Unlike listing all rows, this action targets one precise record to fetch its current values. Key capabilities include:

  • Pinpointing a specific record using its unique Row ID.
  • Retrieving the raw data structure of a row for further processing.

This action is essential when you need to fetch the latest details of a specific item—such as a specific task, order, or ticket—to update other systems or trigger conditional logic in your automation.



Inputs

1. Connection

  • Purpose: Establishes the link between Zenphi and your Smartsheet account.
  • Practical Guidance: Select an existing connection from the dropdown menu. If you have not connected Smartsheet yet, you can create a new connection by clicking the + button and logging in with your Smartsheet credentials.
  • Use Case Context: Ensures the workflow has permission to read the specific sheet you are targeting.

2. Sheet Id

  • Purpose: Specifies exactly which sheet contains the row you want to find.
  • Practical Guidance: Select the specific sheet from the dropdown list that appears after you select your connection. (Note: As with all Smartsheet actions in Zenphi, the sheet must be selected directly from the dropdown menu).
  • Use Case Context: You would select your “Project Tracking” sheet here to retrieve a task row from that specific project list.

3. Row Id

  • Purpose: Requires the unique identifier for the specific row you wish to retrieve, acting as the address for the row.
  • Practical Guidance:
    • Dynamic (Recommended): In most automations, you will not know the ID ahead of time. You typically map this using the token picker from a previous step, such as a List Rows action or a trigger that provided the ID.
    • Static: To find a specific ID manually, open Smartsheet, right-click the desired row, select “Properties,” and copy the Row ID. You can then paste this value into the field.
  • Use Case Context: You would map the Row ID from a “New Row Added” trigger to this field to fetch the full details of the row that just started the workflow.



Outputs

When you retrieve a row from Smartsheet, the output does not automatically display the fields as structured objects. Instead, the action returns the Result as raw application/json text. You must parse this JSON on your end. The most straightforward way to do this is by passing the Result into a Convert JSON to Object action.

1. Result

  • Data Description: Contains the raw data returned from Smartsheet for the requested row in a raw JSON text format.
  • Workflow Utility: To use the specific data inside this row, you must parse this output.


How Smartsheet Row Data Is Structured

Each retrieved row is returned as an object that includes:

  • id (Row ID)
  • rowNumber
  • Only the fields that contain values
  • Fields are represented by their column IDs, not their column names

For example, a single filled field may look like this: "360258290274180": "Task 2"

Notice that:

  • The key is the column ID
  • The column name does not appear in the output


Example – Row with Filled Fields

If a sheet contains hundreds of columns but only 3 are filled, the output object would look like this:

{
  "id": 6197623273492356,
  "rowNumber": 1,
  "360258290274180": "Task 1",
  "4863857917644676": "Details 1",
  "2612058103959428": "diana@demo.mbfcorp.com"
}

Only non-empty fields are included.


Attachments

If a row includes an attachment, it will appear like this:

{
  "FileName": "adminConsentRequestDetails.png",
  "ContentType": "image/png",
  "Size": 197,
  "payload": "urn:file:8fbd52ff886945779a295ea344f01b4a:70479dfeab0e4731aa758fd3e2262f68"
}

To access the file:

  1. Pass the payload value to the Find Zenphi File action.
  2. Use the returned file from that action in the next step.


Important Note About Parsing

To correctly parse the output using Convert JSON to Object, you must:

  1. Retrieve a sample row where all fields are filled.
  2. Use that full row JSON in the Schema → Sample JSON Payload section.

This ensures that all possible fields are generated in the output object, even if some rows later contain empty values.



Example Use Cases

1. Retrieve Latest Task Details: Fetch the current status, assignee, or comments of a specific task using its Row ID before sending a status report.

2. Process Approval Requests: Get the full details of a request row when an approval workflow is triggered by a specific Row ID.

3. Sync Data to External Systems: Pull specific row data to update a corresponding record in a CRM (like Salesforce) or a database using the Row ID as a key.

4. Verify Row Existence: Attempt to find a row to confirm it exists and verify its current values before performing an update or calculation.

5. Enrich Notification Data: Retrieve complete row information to populate dynamic fields in an email or Slack notification based on a simple ID reference.



Example Scenario

Goal

You have an automated order processing workflow. When an external system (like an e-commerce platform) updates an order status, it sends a webhook to Zenphi containing the Smartsheet Row ID associated with that order. You need to retrieve the full details of that row (such as Customer Name and Order Total) to generate a confirmation invoice .pdf.


Steps to Implement

1. Set the Trigger: Select the Http Trigger to receive the incoming webhook payload from your external system. Ensure the payload includes the Row ID.

2. Configure the Find row Action:

  • Connection: Select your authorized Smartsheet connection.
  • Sheet Id: Choose the “Orders Master List” sheet from the dropdown menu.
  • Row Id: Use the token picker to map the Row ID value received from the Http Trigger body.

3. Parse the Output (Essential Next Step): Since the output of Find row is raw JSON, add a Convert JSON to Object action immediately after this step. Pass the Result token from the Find row action into the JSON converter to make the individual cell values (like “Customer Name”) accessible for the .pdf generation step.


Outcome

The workflow successfully locates the specific order row using the provided ID. It retrieves the raw data, which is then parsed by the subsequent step, allowing you to map specific cell values into your invoice generation action without manually searching the sheet.



Best Practices

1. Map IDs Dynamically: Always use the token picker to map the Row ID from a previous step (like a trigger or a List Rows action) rather than hardcoding it, as Row IDs are unique and specific to each record.

2. Plan for JSON Parsing: Remember that this action returns raw data. You must include a Convert JSON to Object action immediately after this step to extract specific column values for use in your workflow.

3. The “Fully Populated Row” Schema Trick: Because Smartsheet omits empty fields from the JSON, your Convert JSON to Object schema might miss columns if your sample row has blank cells. Create a dummy row in your Smartsheet where every single column is filled. Run a test flow to retrieve that row’s JSON, and use that exact JSON as your Schema Sample.

4. Validate Row IDs: Ensure the Row ID provided to the action is valid and exists in the specified sheet; providing an incorrect ID will cause the action to fail.

5. Use for Single Records: Use this action when you need to target a specific, known entry. If you need to process multiple rows based on criteria (e.g., status is complete), use the List Rows action instead.