> ## Documentation Index > Fetch the complete documentation index at: https://docs.liberate.ai/llms.txt > Use this file to discover all available pages before exploring further. # Entity table node # Entity Table Node The **Entity Table Node** lets you maintain static reference data in CSV format and look up values during workflow execution. Use it for mapping codes to names, storing regional settings, or any data that changes infrequently. > [!NOTE] > > Entity Tables are ideal for reference data that rarely changes - like state codes, loss type mappings, or regional configurations. For dynamic routing logic, use a Decision Table Node instead. ## Overview Use an Entity Table Node when you need to: * Map codes to human-readable descriptions * Look up regional or state-specific values * Store carrier or product codes and names * Maintain coverage type definitions * Reference timezone or locale data * Store static configuration values *** ## Entity Table vs. Decision Table | Entity Table | Decision Table | | - | - | | Static data lookup | Conditional routing logic | | Simple key-value mapping | Multiple conditions with operators | | CSV-based storage | Visual rule builder | | Exact match only | Supports wildcards and comparisons | | Reference data | Business rules | **Use Entity Table when:** * You need to look up a value by a key * Data is static (changes infrequently) * No conditional logic required **Use Decision Table when:** * You need if/then routing * Multiple conditions determine output * Rules use operators like greater than, less than, wildcards *** ## Configuration Click on an Entity Table Node to open its configuration panel. ### Basic Settings | Setting | Description | | - | - | | **Title** | Descriptive name for the node | | **CSV Data** | The reference data in CSV format | | **Lookup Key** | Column to match against (primary key) | | **Input Path** | Context path containing the lookup value | | **Output Path** | Where to store the lookup result | ### CSV Format Entity Tables use standard CSV format: ```csv theme={null} key_column,output_column1,output_column2,output_column3 value1,result1a,result1b,result1c value2,result2a,result2b,result2c value3,result3a,result3b,result3c ``` * First row contains column headers * First column is typically the lookup key * Subsequent columns contain data to retrieve * Values are comma-separated * Use quotes for values containing commas *** ## How Lookups Work 1. Workflow reaches the Entity Table Node 2. Node reads the value from **Input Path** in context 3. Node searches the **Lookup Key** column for a match 4. If found, the entire row is returned to **Output Path** 5. If not found, output is null or empty ### Example Lookup **CSV Data:** ```csv theme={null} state_code,state_name,timezone,region CA,California,America/Los_Angeles,West TX,Texas,America/Chicago,South FL,Florida,America/New_York,Southeast NY,New York,America/New_York,Northeast ``` **Configuration:** * Lookup Key: `state_code` * Input Path: `policyState` * Output Path: `stateInfo` **Context before:** ```json theme={null} { "policyState": "TX" } ``` **Context after:** ```json theme={null} { "policyState": "TX", "stateInfo": { "state_code": "TX", "state_name": "Texas", "timezone": "America/Chicago", "region": "South" } } ``` *** ## Insurance Examples ### State Code Lookup Map state abbreviations to full names and regional data. **CSV:** ```csv theme={null} state_code,state_name,timezone,region,regulatory_contact AL,Alabama,America/Chicago,Southeast,aldoi@alabama.gov AK,Alaska,America/Anchorage,West,insurance@alaska.gov AZ,Arizona,America/Phoenix,Southwest,insurance@azinsurance.gov CA,California,America/Los_Angeles,West,commissioner@insurance.ca.gov CO,Colorado,America/Denver,Mountain,dora_ins@state.co.us FL,Florida,America/New_York,Southeast,floir@floir.com GA,Georgia,America/New_York,Southeast,oci@oci.ga.gov NY,New York,America/New_York,Northeast,consumers@dfs.ny.gov TX,Texas,America/Chicago,South,consumerprotection@tdi.texas.gov WA,Washington,America/Los_Angeles,West,mike.kreidler@oic.wa.gov ``` **Configuration:** * Lookup Key: `state_code` * Input Path: `insuredState` * Output Path: `stateData` **Usage in subsequent Mapping Node:** ```jsonata theme={null} { "displayState": $.stateData.state_name, "claimTimezone": $.stateData.timezone, "regulatoryEmail": $.stateData.regulatory_contact } ``` *** ### Loss Type Codes Map internal loss codes to categories and descriptions. **CSV:** ```csv theme={null} loss_code,category,subcategory,description,typical_reserve WTR-001,Water,Pipe,Pipe burst or plumbing leak,5000 WTR-002,Water,Flood,External flooding or storm water,15000 WTR-003,Water,Appliance,Water heater or appliance failure,3000 WTR-004,Water,Roof,Roof leak or ice dam,8000 FIR-001,Fire,Structure,Structural fire damage,50000 FIR-002,Fire,Electrical,Electrical fire,25000 FIR-003,Fire,Kitchen,Kitchen or cooking fire,15000 FIR-004,Fire,Smoke,Smoke damage only,10000 THF-001,Theft,Burglary,Home burglary or break-in,5000 THF-002,Theft,Vehicle,Theft from vehicle,2000 THF-003,Theft,Package,Package theft or porch piracy,500 WND-001,Wind,Storm,Wind or storm damage,12000 WND-002,Wind,Hail,Hail damage,8000 WND-003,Wind,Tornado,Tornado damage,75000 ``` **Configuration:** * Lookup Key: `loss_code` * Input Path: `reportedLossCode` * Output Path: `lossDetails` **Result:** ```json theme={null} { "reportedLossCode": "WTR-001", "lossDetails": { "loss_code": "WTR-001", "category": "Water", "subcategory": "Pipe", "description": "Pipe burst or plumbing leak", "typical_reserve": "5000" } } ``` *** ### Carrier Codes Map carrier codes to full names and contact information. **CSV:** ```csv theme={null} carrier_code,carrier_name,claims_phone,claims_email,portal_url ACME,Acme Insurance Co,800-555-0100,claims@acmeins.com,https://claims.acmeins.com SAFG,SafeGuard Mutual,800-555-0200,claims@safeguard.com,https://portal.safeguard.com NTWD,Nationwide Premium,800-555-0300,fnol@nationwide-prem.com,https://claims.nationwide-prem.com ALLST,AllState Partners,800-555-0400,newclaim@allstatepartners.com,https://allstatepartners.com/claims LIBS,Liberty Secure,800-555-0500,claims@libertysecure.com,https://libertysecure.com/portal ``` **Configuration:** * Lookup Key: `carrier_code` * Input Path: `policyCarrier` * Output Path: `carrierInfo` *** ### Coverage Type Definitions Look up coverage codes and deductible information. **CSV:** ```csv theme={null} coverage_code,coverage_name,coverage_description,default_deductible,max_limit DWELL,Dwelling,Structure of the home,1000,500000 PERS,Personal Property,Contents and belongings,500,250000 LIAB,Liability,Personal liability coverage,0,300000 MEDP,Medical Payments,Medical payments to others,0,5000 LOSS,Loss of Use,Additional living expenses,0,100000 SCHD,Scheduled Property,Specifically listed valuables,0,50000 FLOD,Flood,Flood damage coverage,5000,250000 EQKE,Earthquake,Earthquake damage coverage,10000,500000 ``` **Configuration:** * Lookup Key: `coverage_code` * Input Path: `requestedCoverage` * Output Path: `coverageDetails` *** ### Adjuster Assignments by Region Map regions to assigned adjuster teams. **CSV:** ```csv theme={null} region,team_name,team_lead,team_email,team_phone,capacity Northeast,NE Claims Team,Sarah Johnson,ne-claims@company.com,800-555-1001,150 Southeast,SE Claims Team,Michael Chen,se-claims@company.com,800-555-1002,200 Midwest,MW Claims Team,Lisa Anderson,mw-claims@company.com,800-555-1003,175 Southwest,SW Claims Team,James Rodriguez,sw-claims@company.com,800-555-1004,125 West,West Claims Team,Emily Park,west-claims@company.com,800-555-1005,180 ``` **Configuration:** * Lookup Key: `region` * Input Path: `claimRegion` * Output Path: `assignedTeam` *** ### Timezone Conversions Store timezone data for date/time handling. **CSV:** ```csv theme={null} timezone_id,display_name,utc_offset,observes_dst America/New_York,Eastern Time,-5,true America/Chicago,Central Time,-6,true America/Denver,Mountain Time,-7,true America/Phoenix,Arizona Time,-7,false America/Los_Angeles,Pacific Time,-8,true America/Anchorage,Alaska Time,-9,true Pacific/Honolulu,Hawaii Time,-10,false ``` **Configuration:** * Lookup Key: `timezone_id` * Input Path: `customerTimezone` * Output Path: `timezoneInfo` *** ## Handling Missing Values When a lookup key is not found in the Entity Table, the output will be null or empty. ### Check for Missing Data Use a Mapping Node after the Entity Table to handle missing lookups: ```jsonata theme={null} { "lookupSuccessful": $exists($.stateData) and $.stateData != null, "stateName": $.stateData.state_name ? $.stateData.state_name : "Unknown State", "timezone": $.stateData.timezone ? $.stateData.timezone : "America/New_York" } ``` ### Default Values Pattern 1. Entity Table Node performs lookup 2. Mapping Node checks if result exists 3. If missing, apply default values 4. Continue workflow with guaranteed data ``` Entity Table → Mapping (apply defaults) → Next Node ``` *** ## Updating Entity Table Data Entity Tables contain static data that is configured at design time. ### When to Update Update your Entity Table CSV when: * New codes or values are added (new states, new loss types) * Reference data changes (phone numbers, emails) * Business requirements change * Corrections are needed ### How to Update 1. Open the workflow in the editor 2. Click on the Entity Table Node 3. Edit the CSV data in the configuration panel 4. Save the node 5. Create a new release 6. Deploy to QA, then Production > [!WARNING] > > Entity Table changes require a new workflow release. For data that changes frequently, consider using an external API with a Task Node instead. *** ## Best Practices ### Use Clear Column Names ```csv theme={null} # Good - descriptive column names state_code,state_name,timezone,region # Bad - unclear abbreviations sc,sn,tz,rg ``` ### Include All Expected Values Ensure your CSV contains all possible lookup values. Add new rows when new codes are introduced. ### Keep Tables Focused One Entity Table should serve one purpose: | Bad | Good | | - | - | | One table with states, carriers, and loss codes | Separate tables for each data type | ### Use Consistent Key Formats Ensure lookup keys are formatted consistently: ```csv theme={null} # Good - consistent uppercase codes CA,California TX,Texas FL,Florida # Bad - inconsistent casing CA,California tx,Texas Fl,Florida ``` ### Document Your Tables Add a Note Node explaining what the Entity Table contains and when it was last updated: ``` Entity Table: State Reference Data Last Updated: 2025-02-01 Contains: 50 US states + DC + territories Source: Internal reference database ``` *** ## Common Issues ### Lookup Returns Null **Symptom:** Entity Table returns null even though the value exists. **Fixes:** * Check for case sensitivity (CA vs ca vs Ca) * Verify no leading/trailing whitespace in CSV * Confirm Input Path points to correct context field * Check that the lookup key column name matches configuration ### Wrong Column Returned **Symptom:** Getting unexpected data from lookup. **Fix:** Verify column names in CSV header row match what you expect. Check for typos. ### CSV Parse Errors **Symptom:** Entity Table fails to load or returns errors. **Fixes:** * Ensure proper CSV format (commas, not tabs) * Quote values that contain commas: `"New York, NY"` * Remove any special characters or line breaks within values * Check for consistent number of columns in each row ### Numeric Values as Strings **Symptom:** Numbers from Entity Table cannot be used in calculations. **Fix:** Entity Tables return all values as strings. Use a Mapping Node to convert: ```jsonata theme={null} { "reserveAmount": $number($.lossDetails.typical_reserve) } ``` *** ## Entity Table vs. External API | Entity Table | External API (Task Node) | | - | - | | Data stored in workflow | Data stored externally | | Changes require release | Changes immediate | | No network latency | Network call required | | Limited size | Unlimited data | | Simple lookups only | Complex queries possible | **Use Entity Table when:** * Data is small (under 1000 rows) * Data changes infrequently * Lookup speed is critical * No external dependencies desired **Use External API when:** * Data is large or complex * Data changes frequently * Multiple systems need same data * Advanced querying required *** ## Next Steps > [card] [Decision Table Node](https://docs.liberate.ai/workflows/nodes/decision-table-node.md) > > Conditional routing with business rules > [card] [Mapping Node](https://docs.liberate.ai/workflows/nodes/mapping-node.md) > > Transform lookup results > [card] [Task Node](https://docs.liberate.ai/workflows/nodes/task-node.md) > > Look up data from external APIs > [card] [Code Node](https://docs.liberate.ai/workflows/nodes/code-node.md) > > Complex data processing logic This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.