Transform

🚀 GraphQL to Flatfile Blueprint is now available with @flatfile/plugin-graphql-schema@1.0.0 🚀

@flatfile/plugin-graphql-schema provides a robust solution for leveraging GraphQL data structures within Flatfile, enhancing data management capabilities and adaptability.

• Dual Functionality: The newly released GraphQL to Flatfile Blueprint plugin offers versatile integration options for your Flatfile workspace. Use it to either generate a Flatfile Blueprint directly from GraphQL or configure a Flatfile Space using GraphQL, streamlining your data integration processes.

• Flexible Input Sources: The plugin supports multiple methods for supplying GraphQL data:

  • API Endpoint: Connect directly to a GraphQL API to fetch data.
  • Schema File: Upload a GraphQL schema file.
  • Custom Callback: Implement a custom callback function for advanced data handling and customization.

See the docs.

Transform

@flatfile/util-common@1.1.1

The common utils now include a new deleteRecords utility. This streamlines the creation of the delete records job, which is a common use case and more appropriate for bulk deletion of records.

Transform

@flatfile/plugin-dedupe@1.0.0

The deduplication capability of @flatfile/plugin-dedupe has been expanded beyond the initial 10,000 records limit. Now, it effectively dedupes the entire sheet, ensuring comprehensive data integrity across larger datasets. Additionally, with the latest update, @flatfile/plugin-dedupe can create bulk record deletion jobs, streamlining the process of removing duplicates and optimizing performance.

Transform

@flatfile/util-common@1.0.1

This release replaces the api.records.get on @flatfile/api with a fetch to the GET records endpoint. This significantly improves large response times.

Transform

@flatfile/xlsx-extractor@1.11.2

This update addresses an issue with how columns were managed when encountering blank header columns. Previously, the last column was incorrectly removed in such cases. Now, the column with the blank header is precisely identified and removed, ensuring more accurate data representation and integrity in your workflows.

Transform

@flatfile/plugin-foreign-db-extractor@0.0.2

• Improved Error Handling: This release enhances the error management capabilities of the plugin, ensuring more robust and informative error responses during data extraction processes.

• Accurate File Status Updates: Upon successful job completion, the file status is now correctly updated, providing clear visibility and tracking of job outcomes.

• Enhanced Database Availability Checks: Recognizing the potential delays in database readiness, the plugin now includes polling mechanisms for database users. This ensures that operations proceed only when the restored database is fully available, enhancing the reliability of data interactions.

Transform

@flatfile/plugin-record-hook@1.4.5

This release brings improvements and optimizations to enhance performance and functionality: Smart Change Detection: The plugin now intelligently compares original and modified values to identify actual changes. If there’s no change (a no-op situation), it avoids unnecessary record updates, enhancing efficiency and better supporting trackChanges.

UMD Build Availability: A UMD build is now included, expanding compatibility across different module systems and environments.

Slimmer Node.js Build: The Node.js build has been optimized to reduce its size, improving load times and resource usage.

Removal of Axios Dependency: We’ve eliminated the Axios dependency in favor of native solutions, streamlining the library and reducing external dependencies. Custom Concurrency Control: The plugin now implements its own concurrency control mechanism, moving away from reliance on external libraries. This bespoke solution is tailored to the specific needs of record hook operations, enhancing stability and performance.

These updates mark a step forward in optimizing @flatfile/plugin-record-hook for developers and ensuring seamless integration into your data processing workflows.

Learn more in the docs.

Automations

@flatfile/plugin-export-workbook@0.1.6

This update introduces several enhancements to improve your data export workflows:

Sheet-Specific Exports: Users now have the flexibility to export individual sheets within a workbook, providing greater control over data management and distribution.

Customizable Job Names: To further personalize your workflow, this version allows you to specify custom job names, offering an alternative to relying on the default naming convention.

Enhanced Character Checks: We’ve implemented additional checks for characters that might not be recognized by Excel, reducing the likelihood of errors after exporting the workbook.

These improvements are designed to make your data export process more efficient and tailored to your specific needs.

Learn more about exporting workbooks with @flatfile/plugin-export-workbook

Automations

@flatfile/plugin-webhook-egress@1.2.3

The latest version introduces key improvements for enhanced functionality and user experience:

Switch to Fetch: In this version, we’ve transitioned from using axios to fetch for HTTP requests, streamlining the library’s usage across different environments. Browser Compatibility: The plugin is now fully compatible with browser environments, extending its utility beyond server-side applications.

Enhanced Response Rejection Handling: The integration of our response rejection utility allows for sophisticated post-webhook action decisions. Following a webhook egress, the utility analyzes the response to determine whether to delete records that were successfully submitted or to mark them with a status column reflecting their outcome. It also allows specifying custom error messages for fields within records that encountered rejections.

This update aims to offer more flexibility, reliability, and broader applicability of the webhook egress plugin, ensuring seamless integration into your data workflow.

Learn more in the docs

Transform

@flatfile/plugin-autocast@0.7.6

0.7.6 introduces string casting capabilities to the autocast plugin. With this new feature, numbers and booleans can now be automatically converted to strings, making it easier to manage data types across your applications.

This enhancement is particularly useful in conjunction with the rawNumbers property found in @flatfile/plugin-xlsx-extractor, where numeric values extracted from documents can be seamlessly transformed into string fields for consistency and ease of use.

Learn more

Extractors

@flatfile/plugin-delimiter-extractor@0.9.1&@flatfile/plugin-xlsx-extractor@v1.11.3`

New header logic has been added to the @flatfile/plugin-delimiter-extractor and @flatfile/plugin-xlsx-extractor. This update brings our extractors in line with Flatfile’s core header detection capabilities, offering three distinct header detection strategies: default, explicitHeaders, and specificRows.

By employing the default strategy, the extractors now automatically scan the first 10 rows of your file to identify the header row based on the highest count of non-empty cells.

Discover more about these enhanced header detection options and how they can streamline your data import processes.

Extractors

@flatfile/plugin-xlsx-extractor@1.11.3

This release brings essential updates and improvements to enhance your experience with Excel file extractions:

File Size Detection: The plugin now actively detects when a file is too large for extraction, guiding users to opt for CSV uploads for better handling.

Date Format Specification: Introducing the dateNF parameter, enabling users to define specific date formats for Excel file parsing (e.g., yyyy-mm-dd), ensuring that dates are correctly recognized and formatted.

Handling Empty Sheets: Previously, empty sheets within Excel files would result in errors. With this update, the plugin gracefully handles such cases by appropriately failing the job without causing unexpected errors.

These improvements are aimed at providing a more robust, user-friendly experience for working with Excel files, ensuring data integrity and easing the extraction process.

Learn more about the improvements

Schemas

🚀 Introducing @flatfile/plugin-convert-yaml-schema 🚀

@flatfile/plugin-convert-yaml-schema automates the process of converting YAML into the Flatfile Blueprint.

To get started, simply provide a sourceUrl of your schema, and wrap it with the plugin:

listener.use(
  configureSpaceWithYamlSchema([
    { sourceUrl: "https://example.com/yaml" },
  ])
);

Additionally, you can enhance the experience with a few optional parameters:

• options.workbookConfig: The options.workbookConfig parameter allows you to incorporate other optional Workbook configurations seamlessly.
• options.debug: Toggle the options.debug parameter on/off to access helpful debugging messages for development purposes.
• callback: The callback parameter, which receives three arguments—event, workbookIds, and a tick function—empowers you with the ability to update the Job’s progress. Note: This callback function is invoked once the Space and Workbooks are fully configured.

With the @flatfile/plugin-convert-yaml-schema, you can simplify the schema conversion process—all in one powerful package.

Check out the docs.

Schemas

🚀 Introducing @flatfile/plugin-convert-json-schema 🚀

@flatfile/plugin-convert-json-schema automates the process of converting JSON Schema into the Flatfile Blueprint.

To get started, simply provide a sourceUrl of your schema, and wrap it with the plugin:

listener.use(
  configureSpaceWithJsonSchema([
    { sourceUrl: "https://example.com/customer.schema.json" },
  ])
);

Additionally, you can enhance the experience with a few optional parameters:

• options.workbookConfig: The options.workbookConfig parameter allows you to incorporate other optional Workbook configurations seamlessly.
• options.debug: Toggle the options.debug parameter on/off to access helpful debugging messages for development purposes.
• callback: The callback parameter, which receives three arguments—event, workbookIds, and a tick function—empowers you with the ability to update the Job’s progress. Note: This callback function is invoked once the Space and Workbooks are fully configured.

With the @flatfile/plugin-convert-json-schema, you can simplify the schema conversion process—all in one powerful package.

Check out the docs.

Extractors

@flatfile/plugin-json-extractor@0.1.1

The JSON extractor now intelligently flattens nested objects, combining their field keys into a single, structured format until it reaches a primitive type, making data extraction more comprehensive and user-friendly.

Core

@flatfile/plugin-record-hook@1.1.11

In a recent update, we introduced a comparison mechanism to track changes between original and modified values, ensuring that records were only updated when both value and messages had changed. However, this approach unintentionally excluded updates to metadata when no changes were detected in value or messages.

In this version, we’ve refined the process by comparing the entire original record object with the modified record object. This ensures that no updates, including metadata changes, are left unaccounted for, regardless of whether there were changes in the value or message fields. Your records are now more comprehensively managed and updated.

Core

@flatfile/plugin-record-hook@1.1.10

Previously, there was an issue with completing commits while using the @flatfile/api client-side, which led to the error message “Cannot read properties of undefined (reading ‘get’).” To address this problem, we’ve made a swift and effective transition to using fetch. Soon, we plan a more comprehensive solution.

Core

@flatfile/plugin-record-hook@1.1.9

• Previously, an issue arose when attempting to complete a commit with the trackChanges flag (a Workbook setting to disable actions on Sheet and Workbook when there is a commit that has not been completed) disabled on the Workbook. This issue has been resolved, and commits are now exclusively triggered when the trackChanges feature is enabled for the Workbook.

• Additionally, we’ve implemented an advanced deep comparison method between the original record and the potentially modified record. This enhancement guarantees that only essential patches for updated records are transmitted, resulting in a notably more efficient and precise data update process.

Automations

@flatfile/plugin-export-workbook@0.0.8

When exporting a workbook, a job completion message is now available with an added feature. You can now include a “Next” URL within the job completion message, providing a seamless transition to the next step in your workflow.

Automations

@flatfile/plugin-export-workbook@0.0.7

In this update, we’ve made several valuable improvements to enhance your experience:

Export Record ID Option: You can now utilize an optional flag to export the Record ID, adding flexibility and precision to your exports.

Column Pattern Generator Fix: We’ve addressed and fixed issues related to the column pattern generator, ensuring accurate and reliable data generation.

Column Count per Sheet: We’re now passing the column count to the generator for each sheet, optimizing data handling for your specific needs.

Improved Error Handling: We’ve refined error handling to ensure that jobs are properly marked as failed in case of errors, providing better transparency and control.

File Cleanup: To keep your Space clean and efficient, files are now automatically deleted after they have been successfully uploaded, promoting tidy data management.

These updates collectively contribute to a smoother and more efficient workflow for your tasks.

Extractors

@flatfile/plugin-extractor-xlsx@1.8.0

In this version, we’ve added a valuable enhancement to the Excel Extractor by exposing SheetJS’s “raw” option. This option empowers users to preserve formatted text by default. When raw is set to true, the extractor will return the raw value, offering greater flexibility and control over extracted data.

Automations

@flatfile/plugin-automap@0.1.1

Previously, initiating the “import” process, whether by dropping a file into a sheet or clicking the “Import” button from a file, created an unintended secondary workbook:map job. This secondary job was detected by the automap plugin, leading to duplicate entries in a sheet.

In this version, we’ve introduced a solution to address this issue. We’ve added an “isAutomap” flag to the job’s input, which allows the automap plugin to filter jobs accordingly. If the “isAutomap” flag is not provided, the automap plugin will gracefully exit, ensuring a more streamlined and error-free workflow.

Automations

@flatfile/plugin-automap@0.1.1

Previously, when initiating the “import” process, which could be triggered by either dropping a file into a sheet or clicking the “Import” button from a file, a secondary workbook:map job was created. This unintentionally triggered the automap plugin, leading to duplicate entries within a sheet.

In response to this issue, this version introduces an isAutomap flag within the job’s input. The inclusion of this flag allows the automap plugin to apply appropriate filtering. If the flag is not provided, automap will gracefully exit without processing the job, thereby resolving the issue of duplicate entries in the sheet.

Automations

@flatfile/plugin-automap@0.1.0

Previously, the Automap plugin exclusively matched the defaultTargetSheet with the sheet.name or sheet.id. In this update, we have expanded the matching capability to include the sheet.slug. This enhancement provides greater flexibility and precision when configuring default target sheets within the Automap plugin. This improvement is especially beneficial when you need to pass something like the sheet name + filename dynamically, making the mapping process even more versatile.

Extractors

@flatfile/util-extractor@0.4.5

util-extractor is a crucial dependency used in all extractor plugins. We’ve made an important fix on the import method across all extractor plugins. If you previously encountered the following error message, you can now resolve this issue by updating to the latest extractor version.

Module not found: Error: Can't resolve '@flatfile/api/api'

Extractors

@flatfile/plugin-space-configure@0.1.4

An improvement was made to allow for configuring Spaces with no Workbooks.

Extractors

Major (Agent) Plugin-based Extraction Speed Improvements Just Went Live

We noticed the record insert portion of extraction taking far longer in plugins than in the core platform (with CSVs). We had to get to the bottom of why there was such a disparity and we’re thrilled to say we have a solution. We’re seeing a 700k file that once took between 10-12 mins now only takes 1-1.5 min!

But wait, there’s more:

Additionally, end users will now get updated percentages during the upload process and will receive a success message when the file is successfully extracted.

Upgrade your extractor(s) to the latest to enjoy this optimization:

• @flatfile/plugin-xlsx-extractor@1.7.5
• @flatfile/plugin-delimiter-extractor@0.7.3
• @flatfile/plugin-json-extractor@0.6.4
• @flatfile/plugin-pdf-extractor@0.0.5
• @flatfile/plugin-xml-extractor@0.5.4
• @flatfile/plugin-zip-extractor@0.3.7

Extractors

@flatfile/plugin-psv-extractor@1.6.0 & @flatfile/plugin-tsv-extractor@1.5.0

We’re excited to announce that PSV and TSV file types, previously reliant on plugins, are now natively supported by the Flatfile Platform! 🚀

As part of this enhancement, we’ve marked these plugins as deprecated. Developers will receive a friendly console log notification, making it clear that these plugins are no longer needed. Enjoy the streamlined experience!

Core

🚀 Introducing @flatfile/util-response-rejection

Meet @flatfile/util-response-rejection, a new utility for showcasing rejected Records from an external API to your customers. Managing rejected data during egress is vital for maintaining data accuracy, and this utility simplifies the entire process, ensuring a smoother experience for handling these instances.

Here’s what it does:

1. Takes a RejectionResponse containing rejected Records and a rejection message.
2. Locates the corresponding Record and adds the rejection message as an error to the Record cell.

You can also utilize this utility directly with any listener.

Learn more in the docs.

Extractors

@flatfile/plugin-extractor-___

All extractors have been fine-tuned to seamlessly handle extractions within a job, allowing the plugin more time to complete the extraction with less risk of the Agent timing out.

Additionally, we’ve resolved a bug that was causing extractions to falsely indicate completion when running in parallel, ensuring extraction truly finishes before signaling completion.

Transform

@flatfile/plugin-autocast@0.2.2

Dates that were cast to a UTC string using the autocast plugin were showing as invalid after transformation. A fix for this was added to version 0.2.2.

Learn more.

Transform

@flatfile/plugin-autocast

In the most recent update, we’ve introduced some exciting enhancements. You can now implement an optional fieldFilter to specify which fields autocast should operate on.

Check it out:

listener.use(autocast({ sheetSlug: 'bar' }, ['numberField', 'dateField']))

Learn more.

Extractors

🚀 Introducing @flatfile/plugin-autocast

Effortlessly transform data in your Sheets to align with the field types specified in the Blueprint.

Supported field types:

• Numbers: String numbers (‘1’), string decimals (‘1.1’), and string numbers with commas (‘1,000’) are interpreted as numbers.

• Booleans:

  • Truthy values: ‘1’, ‘yes’, ‘true’, ‘on’, ’ ’, ‘y’, and 1.
  • Falsy values: ’- ’, ‘0’, ‘no’, ‘false’, ‘off’, ’ ’, ‘n’, 0, -1.

• Dates: Date strings and numbers are cast to a UTC string (note: YYYY-MM-DD... is interpreted as an ISO 8601 date and is treated as treated as UTC, while other formats are treated as local time and converted to UTC).

  • ‘2023-08-16’ => ‘Wed, 16 Aug 2023 00:00:00 GMT’
  • ‘08-16-2023’ => ‘Wed, 16 Aug 2023 00:00:00 GMT’
  • ‘08/16/2023’ => ‘Wed, 16 Aug 2023 00:00:00 GMT’
  • ‘Aug 16, 2023’ => ‘Wed, 16 Aug 2023 00:00:00 GMT’
  • ‘August 16, 2023’ => ‘Wed, 16 Aug 2023 00:00:00 GMT’
  • ‘2023-08-16T00:00:00.000Z’ => ‘Wed, 16 Aug 2023 00:00:00 GMT’
  • 1692144000000 => ‘Wed, 16 Aug 2023 00:00:00 GMT’

Note: @flatfile/plugin-record-hook listens for the same event type (commit:created). Plugins will fire in the order they are placed in the listener.

Check out the docs.

Extractors

🚀 Introducing @flatfile/plugin-jobs-handler

Our latest plugin, @flatfile/plugin-jobs-handler, streamlines handling Flatfile Jobs, which are a large unit of work performed asynchronously on a resource such as a file, Workbook, or Sheet.

Options at your fingertips:

• Update Job progress using await tick(progress, message), returning a promise for JobResponse.
• opts.debug Enable debug logging for the plugin

To get started simplifying the management of your Jobs, explore the README.

Extractors

🚀 Introducing @flatfile/plugin-space-configure

Streamline the dynamic setup of new Flatfile Spaces with @flatfile/plugin-space-configure.

How it works:

• The setup parameter holds the Blueprint for the new Space.
• And the callback parameter (invoked once the Space and Workbooks are fully configured) receives three arguments:

1. event
2. workbookIds
3. Using the @flatfile/plugin-jobs-handler under the hood, the tick function can be used to update the Job’s progress.

To simplify auto-configuring your Spaces, explore the README.

Extractors

All extractors now support chunkSize and parallel

A new version of an underlying utility (@flatfile/util-extractor) introduces 2 new options for extracting records in all extractor plugins:

• chunkSize: (Default: 3,000) Define how many records you want to process in each batch. This allows you to balance efficiency and resource utilization based on your specific use case.
• parallel: (Default: 1) Choose whether the records should be processed in parallel. This enables you to optimize the execution time when dealing with large datasets.

Note: Previously, we were extracting with a chunkSize of 1,000.

Ex: Excel Usage: (See docs)

listener.use(ExcelExtractor({ chunkSize: 300, parallel: 2 }))

If you update your extractor plugin to the latest, you will receive these new options.

Extractors

@flatfile/plugin-delimiter-extractor

Now that the platform includes native support for TSV and PSV files, developers are no longer required to use a plugin specifically for these formats. As a result of this enhancement, the documentation for the @flatfile/plugin-delimiter-extractor has been revised to reflect this update.

For users who are already utilizing or have integrated a plugin for TSV and PSV files, there’s no need to worry about any disruptions. While the extraction will occur twice, resulting in a “extraction complete” status being displayed twice, the process remains functional and intact.

Extractors

🚀 Introducing @flatfile/plugin-pdf-extractor

Our latest plugin, @flatfile/plugin-pdf-extractor, introduces the power of parsing .pdf files in Flatfile.

Options at your fingertips:

• opt.apiKey: Feed in your pdftables.com API key to unlock the magic.
• opt.debug: Toggle debugging messages to streamline development.

Tech Behind the Scenes:

• Empowered by remeda for dynamic functional programming and data handling.
• Seamlessly integrates Pattern Matching with TypeScript through ts-pattern.

See the docs

Extractors

@flatfile/plugin-dedupe@0.0.2

Includes fixes to properly job ack on failure and use a new instance of listener after a filter operation. It also adds server errors to logging.

Extractors

@flatfile/util-file-buffer@0.0.3

A fix was made to only run fileBuffer on uploaded files. This fixes an issue where extraction was occurring during export improperly.

All extractor plugins went up one tick to leverage this update to the file buffer.

Transform

🚀 Introducing @flatfile/@flatfile/plugin-dedupe

@flatfile/plugin-dedupe adds a touch of magic by seamlessly removing duplicate records right within a sheet with several options to fit your use case:

• opt.keep: Decide whether to hang on to the first or last duplicate record.
• opt.custom: Craft your own dedupe function, for those out-of-the-box scenarios.
• opt.debug: Toggle on those helpful debug messages when you’re in the lab.

Tech:

• Powered by ts-pattern for in-depth Pattern Matching in TypeScript.
• Leverages the mighty remeda for JavaScript’s functional programming and data wizardry.

See the docs

Extractors

🚀 Introducing @flatfile/plugin-delimiter-extractor

Introducing the latest addition to our extractor plugins: @flatfile/plugin-delimiter-extractor. Designed to streamline your data extraction tasks, this plugin is tailored to process delimited files including tab (\t), pipe (|), semicolon (;), colon (:), tilde (~), caret (^), and hash (#).

Parameters and Options:

• fileExt specifies the file name or extension to listen for, allowing you to define the file types to process.
• options.delimiter the delimiter character used in the file.
• options.dynamicTyping automatically convert numeric and boolean data in the file to their appropriate data types, ensuring accurate processing.
• options.skipEmptyLines: With ‘true’, completely empty lines (evaluating to an empty string) will be skipped during parsing. With ‘greedy’, lines with only whitespace characters are also skipped.
• options.transform define a function to be applied to each parsed value before dynamicTyping.

See the docs

Extractors

@flatfile/plugin-xlsx-extractor@1.4.0

Includes a fix for ghost rows in Excel files (happened if there was formatting on a cell but no data)

Extractors

@flatfile/plugin-delimiter-extractor@0.4.0 & @flatfile/plugin-xlsx-extractor@1.5.0

Adds ability to support duplicate headers with non-unique header keys.

Extractors

@flatfile/plugin-delimiter-extractor@0.3.0 & @flatfile/plugin-xlsx-extractor@1.3.2

Adds header row auto-detection (the same function used for CSVs in platform) 

Extractors

@flatfile/plugin-zip-extractor@0.3.2

Includes a fix to exclude unwanted dir (MACOSX) and it now checks file name not full path