> ## Documentation Index > Fetch the complete documentation index at: https://flatfile.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Sentiment Analysis Plugin > Automatically analyze sentiment in text fields and add sentiment scores and categories to your Flatfile records This plugin analyzes the sentiment of text within specified fields of records in a Flatfile Sheet. It operates during the data processing phase by hooking into the record commit lifecycle. For each designated text field, the plugin calculates a sentiment score, categorizes it as 'positive', 'negative', or 'neutral', and adds this information back to the record in two new fields: `_sentiment_score` and `_sentiment_category`. It also adds informational messages to the record detailing the outcome of the analysis. This is useful for automatically classifying customer feedback, product reviews, support tickets, or any other free-text data to quickly gauge user sentiment. ## Installation Install the plugin using npm: ```bash theme={null} npm install @flatfile/plugin-enrich-sentiment ``` ## Configuration & Parameters The plugin accepts a configuration object with the following parameters: ### `sheetSlug` (required) * **Type:** `string` * **Description:** The slug of the sheet that this plugin should run on. ### `textFields` * **Type:** `string[]` * **Description:** An array of field keys (column names) that contain the text to be analyzed. * **Default:** `['description']` ### `automaticValidation` * **Type:** `boolean` * **Description:** A flag to enable or disable the sentiment analysis. If set to `false`, the plugin will add an info message to each record indicating that analysis is disabled but will not perform any analysis. * **Default:** `false` - The analysis only runs if this is explicitly set to `true`. ### `errorMessages` * **Type:** `object` * **Description:** A configuration object for custom error messages. Note: This option is defined in the type interface but is not used in the current plugin implementation. ## Usage Examples ### Basic Usage ```javascript theme={null} import { FlatfileListener } from '@flatfile/listener'; import { enrichSentiment } from '@flatfile/plugin-enrich-sentiment'; export default function(listener) { // Analyzes the 'description' field in the 'contacts' sheet. listener.use(enrichSentiment({ sheetSlug: 'contacts', textFields: ['description'], automaticValidation: true })); } ``` ```typescript theme={null} import { FlatfileListener } from '@flatfile/listener'; import { enrichSentiment } from '@flatfile/plugin-enrich-sentiment'; export default function(listener: FlatfileListener) { // Analyzes the 'description' field in the 'contacts' sheet. listener.use(enrichSentiment({ sheetSlug: 'contacts', textFields: ['description'], automaticValidation: true })); } ``` ### Multiple Text Fields ```javascript theme={null} import { FlatfileListener } from '@flatfile/listener'; import { enrichSentiment } from '@flatfile/plugin-enrich-sentiment'; export default function(listener) { // A more detailed configuration for a customer feedback sheet. // Analyzes both 'comment' and 'feedback' fields. listener.use(enrichSentiment({ sheetSlug: 'customer-feedback', textFields: ['comment', 'feedback'], automaticValidation: true })); } ``` ```typescript theme={null} import { FlatfileListener } from '@flatfile/listener'; import { enrichSentiment } from '@flatfile/plugin-enrich-sentiment'; export default function(listener: FlatfileListener) { // A more detailed configuration for a customer feedback sheet. // Analyzes both 'comment' and 'feedback' fields. listener.use(enrichSentiment({ sheetSlug: 'customer-feedback', textFields: ['comment', 'feedback'], automaticValidation: true })); } ``` ### Advanced Custom Usage ```javascript theme={null} // This example shows how to use the exported helper functions // inside a custom recordHook for more fine-grained control. import { FlatfileListener } from '@flatfile/listener'; import { recordHook } from '@flatfile/plugin-record-hook'; import { performEnrichSentiment } from '@flatfile/plugin-enrich-sentiment'; export default function(listener) { listener.use(recordHook('reviews', async (record) => { const reviewText = String(record.get('review_text')); // Use the exported helper function directly const { error, result } = performEnrichSentiment(reviewText, 'review_text'); if (error) { record.addWarning('review_text', error); } else if (result) { // Custom logic: only add a 'positive_review' flag if (result.category === 'positive' && result.score > 3) { record.set('positive_review', true); record.addInfo('review_text', 'This is a highly positive review!'); } } return record; })); } ``` ```typescript theme={null} // This example shows how to use the exported helper functions // inside a custom recordHook for more fine-grained control. import { FlatfileListener } from '@flatfile/listener'; import { recordHook } from '@flatfile/plugin-record-hook'; import { performEnrichSentiment } from '@flatfile/plugin-enrich-sentiment'; export default function(listener: FlatfileListener) { listener.use(recordHook('reviews', async (record) => { const reviewText = String(record.get('review_text')); // Use the exported helper function directly const { error, result } = performEnrichSentiment(reviewText, 'review_text'); if (error) { record.addWarning('review_text', error); } else if (result) { // Custom logic: only add a 'positive_review' flag if (result.category === 'positive' && result.score > 3) { record.set('positive_review', true); record.addInfo('review_text', 'This is a highly positive review!'); } } return record; })); } ``` ### Using Utility Functions ```javascript theme={null} import { analyzeSentiment } from '@flatfile/plugin-enrich-sentiment'; const analysis = analyzeSentiment("Flatfile is an amazing tool!"); // analysis -> { score: 6, category: 'positive' } ``` ```typescript theme={null} import { analyzeSentiment } from '@flatfile/plugin-enrich-sentiment'; const analysis = analyzeSentiment("Flatfile is an amazing tool!"); // analysis -> { score: 6, category: 'positive' } ``` ## API Reference ### `enrichSentiment(config: EnrichSentimentConfig)` The main entry point for the plugin. It creates and registers a `recordHook` with Flatfile that performs sentiment analysis on incoming records based on the provided configuration. **Parameters:** * `config` (EnrichSentimentConfig): An object containing configuration options * `sheetSlug` (string): The slug of the sheet to target * `textFields` (string\[]): An array of field keys to analyze. Defaults to `['description']` * `automaticValidation` (boolean): Must be `true` to enable analysis **Returns:** A function of type `(listener: FlatfileListener) => void` which is used to install the plugin into a Flatfile listener. ### `analyzeSentiment(text: string)` A pure function that takes a string of text and returns its sentiment analysis. **Parameters:** * `text` (string): The input text to analyze **Returns:** An object with the following properties: * `score` (number): A numerical score representing the sentiment. Positive values are positive, negative values are negative * `category` ('positive' | 'negative' | 'neutral'): A string category for the sentiment ### `performEnrichSentiment(value: string, field: string)` A wrapper around `analyzeSentiment` that includes basic validation and formats the output for use within a record hook. It checks for empty input and structures the return value with either an error or a result object. **Parameters:** * `value` (string): The text value from the record field * `field` (string): The name of the field being analyzed, used for creating informative messages **Returns:** An object with one of two shapes: * On success: `{ error: null, result: { score: number, category: string, message: string } }` * On error (empty input): `{ error: string, result: null }` ## Troubleshooting ### Empty Text Fields If a text field specified in the `textFields` configuration is empty or null, the plugin will not throw an error. Instead, it will add a warning to the record using `record.addWarning()` with a message like "No text found for sentiment analysis in field: \[field\_name]". ### Analysis Not Running If `automaticValidation` is set to `false` or is omitted, the plugin will not perform any analysis or add any warnings. It will only add an informational message to the record stating that automatic analysis is disabled. ## Notes ### Default Behavior * The plugin is **disabled by default**. You must explicitly set `automaticValidation: true` to enable sentiment analysis. * If no `textFields` are specified, the plugin will default to analyzing the `description` field. ### Generated Fields The plugin adds two new fields to each processed record for each analyzed text field: * `_sentiment_score`: Contains the numerical sentiment score * `_sentiment_category`: Contains the sentiment category ('positive', 'negative', or 'neutral') Ensure your Sheet configuration or downstream systems can handle these new fields. ### Configuration Considerations * The configuration property to enable the plugin is `automaticValidation` (boolean), not `autoAnalysis`. * The `errorMessages` property in the `EnrichSentimentConfig` type is defined but not currently implemented in the plugin's logic. * The plugin relies on the `sentiment` npm package for its analysis logic.