The Instructions API provides a way to associate helpful guidance with specific field sets. When a user is mapping data with a similar field structure, the appropriate instructions can be retrieved and displayed to guide them through the process.

Key features include:

• Field-specific instructions: Store instructions for specific combinations of fields
• Automatic matching: Instructions are automatically matched to sheets with similar field structures
• Metadata support: Add custom metadata to instructions for additional context
• Full CRUD operations: Create, read, update, and delete instructions through a RESTful API

Create Instructions

POST /v1/instructions

Request Body:

{
  "instructions": "Map the 'email' field to the customer's primary email address.",
  "fieldKeys": ["first", "last", "email", "subscribed", "phone"],
  "metadata": {
    "category": "customer-data"
  }
}

Get Instructions by Sheet ID

GET /v1/instructions/sheet/:sheetId

Update Instructions

PATCH /v1/instructions/:instructionId

Delete Instructions

DELETE /v1/instructions/:instructionId

How It Works

Instructions are tied to mapping families, which are collections of fields that share a common structure. The system uses a confidence threshold to determine which instructions to display, ensuring that users only see guidance that's relevant to their current data.

Example Usage

Here's a simple example of how to create instructions using the API:

// Create instructions for customer data fields
fetch('https://api.flatfile.com/v1/instructions?environmentId=us_env_123&scope=us_acc_456', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer your_secret_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    instructions: "Map the 'email' field to the customer's primary email address. The 'first' and 'last' fields should be mapped to the customer's first and last name.",
    fieldKeys: ["first", "last", "email", "subscribed", "phone"],
    metadata: {
      category: "customer-data",
      importance: "high"
    }
  })
})
.then(response => response.json())
.then(data => console.log('Instructions created:', data));

The default data retention period has been updated from 10 days to 365 days, providing users with a longer default timeframe for data storage. Additionally, the description text has been simplified to "Keeps data for a set duration from its collection" without referencing a specific policy timeframe.

This change gives users more time to work with their data before it expires, while maintaining the flexibility to configure custom retention periods as needed.

We've enhanced the user experience in Data Clips by hiding the collaborator input when no space guests exist:

• The collaborator input is now automatically hidden in the Data Clip create modal when there are no space guests
• Similarly, the collaborator section is hidden in the share modal when no guests are available
• This provides a cleaner interface by only showing relevant options based on the current space context

This improvement streamlines the Data Clips creation and sharing workflow by removing unnecessary UI elements when they're not applicable.

We've enhanced our filtering capabilities with a new Advanced Filters feature that supports querying by field validation status. This powerful addition allows you to build dynamic filters that combine field selection with validation checks.

Key improvements include:

• Support for the FFQL is operator with values of error and valid
• Ability to create complex filters targeting specific fields with validation issues
• User-friendly interface for building advanced filter queries
• Seamless integration with existing filtering capabilities

For example, you can now easily find all records where a specific field (like "email") has validation errors, or combine this with other conditions to create precise filters for your data cleanup workflows.

This feature is particularly useful for data quality management, allowing you to quickly identify and address problematic fields across your datasets.

• The guestAuthentication array field has been replaced with a new guestLinkUrl string field in the DataClip model
• When updating a DataClip with sharedLink set to "unrestricted", a guest link with a permanent access token is generated
• When updating a DataClip with sharedLink set to "restricted", a direct sheet URL is generated without a token
• The system now properly handles existing guest links to prevent unnecessary regeneration
• The URL format has been improved for better usability and security

This change provides a more consistent and reliable way to share DataClips with guests, with clearer distinction between restricted and unrestricted access modes.

This change applies to all links in documents, whether they're created using Markdown syntax or HTML anchor tags.

We've added a new keepRecordIds flag to maintain record IDs during transformations. This enhancement provides greater control over how records are processed during transformation operations.

Key Benefits:

• Maintains data consistency across transformation previews
• Preserves record relationships and references
• Improves transformation accuracy by maintaining original record IDs

Technical Details:
When keepRecordIds is set to true, the system uses updateRecords instead of the previous add/delete approach, ensuring that record IDs remain unchanged throughout the transformation process. This is particularly valuable when:

• Working with data that has established relationships between records
• Performing multiple transformations where maintaining record identity is important
• Integrating with systems that rely on consistent record identifiers

Usage:
The keepRecordIds flag can be included in transformation job configurations:

// Example of creating a transformation job with keepRecordIds
const transformationJobResponse = await HTTPService.createJob({
  type: "workbook",
  operation: "transform",
  source: workbookId,
  destination: destinationWorkbookId,
  config: {
    destinationSheetId: destinationSheetId,
  },
  input: {
    programId: "your-program-id",
    version: "v2",
    keepRecordIds: true, // Set to true to preserve record IDs
  },
});

This feature is backward compatible - keepRecordIds defaults to false, maintaining the existing behavior for current implementations.

• Users can now add new rows by hovering over row dividers in the index column
• An "Insert row" button appears when hovering between rows
• Clicking the button adds a new row at the selected position
• The feature provides a more intuitive way to add data at specific positions in a table

This enhancement improves the user experience by making row insertion more discoverable and allowing precise control over where new rows are added in the dataset.

Optimized performance of the getAgents endpoint through pagination implementation. This significantly improving response times and scalability when working with large collections of agents.

The findAndReplaceRecords method in the WorkbooksService now checks if the field
being replaced is readonly and throws an error if excludeReadOnly is set to
true, preventing modification of readonly fields.

Several new tests have been added to validate the behavior of the replaceRecords
operation with readonly records and fields, covering scenarios with
excludeReadOnly set to true and false.

The SearchRecordsOptions and GetCellValuesOptions interfaces have been updated
to include the new excludeReadOnly option.

Example usage:

// Replace non-readonly records or fields
const records = await wb.op.replaceRecords({
  sheetId: wb.contacts.id,
  options: {},
  find: "John",
  replace: "Jonathan",
  field: { key: "firstName" },
  legacyReplace: false,
  actorId: UserId.make(),
});

// Skip readonly records or fields
const records = await wb.op.replaceRecords({
  sheetId: wb.contacts.id,
  options: { excludeReadOnly: true },
  find: "John",
  replace: "Jonathan",
  field: { key: "firstName" },
  legacyReplace: false,
  actorId: UserId.make(),
});

• Spanish (es-419)
• Malay (ms)
• Dutch (nl)
• Polish (pl)
• Swedish (sv)
• Thai (th)
• Chinese Traditional (zh-hant)
• Chinese Traditional Hong Kong (zh-hant-HK)

The implementation of the clearColumn method has been refactored. Instead of using the map and filter array methods, it now uses the reduce method to generate the recordsUpdates array. The new implementation checks if the field value exists and if the field is not read-only before clearing it. This change likely improves performance and readability.

The wording of the info and outcome.message properties in the transitionJob call has been updated from "Column was removed" to "Column was cleared". This change provides more accurate messaging about the action performed.

Additionally, the code now handles read-only fields correctly. If a field is marked as read-only in the RecordConfig, its value will not be cleared.

These changes improve the functionality, performance, and messaging of the clearColumn logic without introducing any breaking changes to the external interface.

• properly escape field keys containing special characters like periods
• correctly apply the error state and appropriate error messages when duplicate values are encountered for fields with a unique constraint
• handle cases where all initially added records have invalid (duplicate) values for fields with a unique constraint

This can be used with the new space-configure-from-template plugin to create new
spaces using an existing space as a template.

When using Autobuild for a new App, the space generated during Autobuild will
automatically be tagged as the template for that App.

Example:

const field = {
  key: 'ReadonlyColumn',
  label: 'Readonly Column',
  type: 'string',
  readonly: true
}

Attempting to clear this column will throw an error: 'Column is readonly and
cannot be cleared'.

An error is also thrown if attempting to clear any column in a readonly sheet.
This prevents modifying data in readonly sheets.

Example:

const sheet = {
  config: {
    readonly: true,
    fields: [...]
  }
}

Attempting to clear a column in this sheet will throw an error: 'Sheet is
readonly. Column cannot be cleared'.

These changes ensure data integrity by preventing unintended modification of
readonly data.

In the English translation file, the title of the “mapValues” section has been
updated from “Map values” to “Map Fields”.

We've resolved several issues affecting the Edit and Create App forms:

• Fixed form validation issues
• Improved error handling
• Enhanced user feedback

Simplified the loading step by removing the detailed progress indicators and
showing only a centered loader component.

Updated the BlueprintTab component to display a bottom border and align the
blueprint view action icons to the right.

If the proposed array value is the same as the existing array value in either
the source or artifacts, it will not be included in the changeset returned by
getDataDiff.

The function now uses the lodash isEqual utility to compare array values,
instead of strict equality (===), to account for differences in order or
reference of array elements.

For example, if the proposed tags array is ['jedi', 'sith'], it will not be
included in the changeset if the existing source tags are ['JEDI', 'SITH'] or if
the existing artifact tags are ['jedi', 'sith'], because the values are
considered equal despite differences in capitalization or array order.

This change ensures that unnecessary changes are not included in the changeset
when working with array values, reducing noise and improving the accuracy of the
changeset calculation.

Secrets have been updated to introduce new optional fields for filtering.

A new optional actorId field of type ActorId has been added to the
ListSecrets request type and WriteSecret type for secrets. This allows
filtering secrets by the associated actor (user, guest, agent, or api key).

Added new methods to for managing stored sheet constraints: getConstraints,
createConstraint, getConstraintById, updateConstraint, and
deleteConstraint.

With the addition of archived spaces there is now an ability to unarchiveSpace
method and space:unarchived event.

Deprecated use of metadata field at the cell value level, recommending use of
record level metadata instead.

Updates to Snapshots resource to track changes to a sheet's schema (i.e. added
and removed columns). A more robust Snapshot will enable more complex features
when comparing 2 different snapshots.

Actions Resource

Actions are now a first class resource. Developers may now create, retrieve,
update, and delete actions via the api. New action events ActionCreated,
ActionUpdated, and ActionDeleted are now being published and an actionId field
has been added to the Context of events.

Agent Versioning

Agents versioning has been introduced. You may now retreieve agent versions via
the api and revert to a previous version via the api and the dashboard.

Token Refresh

Guests actively using their space will have their token's automatically renewed.

Sheet & Cell Updates

Support for array values in cell values has also been added.

Job Metadata

Metadta is now available on the JobConfig type, allowing additional data to be
associated with jobs.

Note that sessions created via embedded or the api will not be constrained, this
is a dashboard only validation.

New fields 'guide' and 'guardrail' have been added to Actions. These options
enable providing markdown guidance and warnings to your users.

actions: [
  {
    operation: 'submitActionFg',
    mode: 'foreground',
    label: 'Submit For Approval',
    type: 'string',
    description: 'Submit this data to a webhook.',
    primary: true,
    guide: {
        content: "### Personalized Guide \n\n Before performing..."
    },
    guardrail: {
        content: "### Warning! \n\n This Submit ..."
    }
  },
  {...}
],

The markdown content of guide will become accessible to the end user via a
tooltip on the action element.

The guardrail component will render as a modal warning before the action event
is triggered. This can be useful for actions that have critical consequences or
require user acknowledgment before proceeding.

This can be useful for actions that have critical consequences or require user
acknowledgment before proceeding.

The "requireAllValidTotal" option has been added for custom actions in the Sheet
toolbar. This new option requires all rows in the Sheet to be valid for the
action to be enabled, regardless of selection. If "requireAllValidTotal" is set
and there are any validation errors in the entire Sheet, the custom action will
be disabled with the corresponding tooltip message.

The existing "requireAllValid" option has been updated to only apply to the
selected rows, rather than all rows. If "requireAllValid" is set and there are
validation errors in the selected rows, the custom action will be disabled with
the corresponding tooltip message.

Introduces support for handling locked sheets (indicated by the locked icon),
and improves the handling of import files.

A new reference-list property type has been added to allow defining an array
of values referenced from another sheet. Links will be established automatically
by the matching engine or similar upon an evaluation of unique or similar
columns between datasets.

The ReferencePropertyConfig has been updated to make the relationship
property optional, allowing it to be omitted.

New options have been added to the ListWorkbooksRequest to allow filtering
workbooks by name, namespace, label, and treatment, as well as controlling
whether to include sheets. For example, you can now pass a name parameter to
filter workbooks by name, or a treatment parameter to filter by treatment. The
includeSheets boolean parameter controls whether sheet data is included in the
response.

In AgentConfig type, a new optional property sourceMap of type string has been
added. This allows including a source map for the agent code.

A new property treatments of type Flatfile.WorkbookTreatments[] has been
added to the Workbook and CreateWorkbookConfig types. This array allows
specifying treatments for a workbook, with the currently available treatment
being ExtractedFromSource. This change introduces a new external interface
that developers using the package should be aware of when creating or updating
workbooks.

Example usage:

import { Flatfile } from "@flatfile/api";

const workbookConfig: Flatfile.CreateWorkbookConfig = {
  // ...other properties
  treatments: [Flatfile.WorkbookTreatments.ExtractedFromSource],
};

A new JobOutcomeTrigger type has been introduced to specify whether a job
outcome's effect should be triggered automatically or manually.

We have enhanced the cell editing experience with an auto-expanding cell input
that dynamically adjusts to fit the content. This improvement ensures that users
can view and edit their data without constraints, enhancing the overall editing
experience.

Improvements have been made to error handling and user feedback in the file
import and mapping process. If an error occurs, a popover is displayed to the
user with the error message, providing clearer feedback on failures during the
import process.

We've added a new feature that allows users to select the header row in the data
preview. This feature is particularly useful when the first row of your data
contains column headers, as it enables you to specify the header row for
accurate data mapping.

You can now search for users in the manager users page. This feature allows you
to quickly find users by name, email, or role, making it easier to manage your
user base.

There is now a /users/:userId/resend-invite endpoint enabling admins to resend
an invitation to a user who has not yet accepted it.

We added a method to delete multiple mapping rules from a program. This new
deleteMultipleRules method simplifies the management of mapping rules by
allowing bulk deletions. The DeleteMultipleRulesRequest type represents the
request payload, detailing the array of rule IDs to be deleted.

We have introduced a new delete method that allows you to delete an app.

The ValidationMessage type has been enhanced with two new optional properties:
field and path. The field property specifies which field the validation
message pertains to, while the path property, of type JsonPathString,
specifies the JSONPath for the validation message. These enhancements provide
more context and precision in validation feedback.

The JobOutcomeNext type now includes a new view option, allowing jobs to
specify a custom view that should be displayed upon completion. To support this,
we introduced the JobOutcomeNextView type, which provides details for the
custom view, including the sheet ID, hidden columns, and an optional label.

We introduced a new updateSheet method that allows you to update a sheet's
name, slug, and metadata. The SheetUpdateRequest type represents the update
request payload, including the name, slug, and metadata of the sheet.
Additionally, an optional metadata property has been added to the Sheet and
SheetUpdate types, allowing for the storage of contextual metadata related to
the sheet.

A new "Update View" button can now be found in the job outcome modal for jobs
that modify the visibility of columns in a workbook sheet. This button triggers
updating the column visibility based on the job outcome.

There are 2 new capabilities to the next property of Job Outcomes:

• view gives developers the ability to manipulate the Sheet's view on
  completion of a Job - Giving control over things like applying a filter or
  hiding a column
• download gives developers the ability to include file details (such as a
  fileName and URL), which are then used to trigger a download to the user's
  browser on completion of the job

We've added new domain Environment events expanding the scope of domains our
system recognizes. To leverage these events, you can listen on to the following
topics: The corresponding event topics are environment:created,
environment:updated, and environment:deleted.

We have added descriptions for the DeleteRecordsJobConfig properties to provide
better clarity: An optional filter param allows allows you to provide options
to filter records, with the default set to none while the filterField param
enables narrowing the valid/error filter results to a specific field, but it
requires the filter to be set.

We corrected a typo in the JobOutcomeNextFiles type by renaming the file
property to files to accurately represent an array of file objects.

Saving and Sharing Custom Views

Users can now apply filters, sorting, and search queries to the Sheet data and
save those settings as a reusable view. Key changes include:

• Added a "Views" dropdown in the Sheet toolbar to manage and apply saved views.
• Added a "Save View" modal that allows users to name and save the current Sheet
  filters/sorting as a view.
• Users can copy a sharable link with the view settings applied.
• Saved views are grouped into "My Views" and "All Views" sections.
• Added backend APIs to create, update, and delete saved views.
• Added new React hooks and components to support the saved views functionality.
• Updated translations for the new UI elements related to saved views.

The data property now returns an array of Document objects instead of the
previous DocumentResponse. This change standardizes the format and improves
consistency in how document data is handled.

We added a new predecessorIds property to JobConfig. This property allows
you to specify job dependencies, meaning you can list the IDs of jobs that must
be completed before the current job can start. This helps in managing and
sequencing job execution more effectively.

We added a new feature to handle job outcomes more effectively with a new type
called JobOutcomeNext and its variant files. This includes:

• JobOutcomeNextFileObject Stores individual file information with an ID and
  optional label.
• JobOutcomeNextFiles Handles multiple files, including an array of
  JobOutcomeNextFileObject instances and an optional label.

We also added a waiting value to the JobStatus enum to indicate when a job is
paused or pending, improving job processing workflows.

We updated ListViewsRequest to include optional pageSize and pageNumber
properties, allowing for pagination when retrieving views. We've also added a
createdBy property to View and ViewResponse to track the creator of each
view.

Previously, the workbook:created event was emitted even when the workbook was
only being updated. Now, the logic emits a workbook:updated event when
necessary. Additionally, the POST /:workbookId/rebuild endpoint now handles
eventing properly.

Expanded Support for Date Formats:

We've broadened our parsing algorithms to accurately recognize and sort a wider
variety of date formats. This update ensures that when users upload files
containing date fields, the system robustly handles various international date
formats and styles.

Improved Sorting Accuracy:

Dates are now correctly sorted based on their actual chronological order,
regardless of the format input. This enhancement reduces errors and
inconsistencies previously encountered with date sorting, ensuring data
integrity and reliability during file uploads.

User Experience Improvement:

Users no longer need to modify or standardize date formats in their files before
uploading. Flatfile automatically interprets and processes diverse date inputs,
simplifying workflows and reducing manual data preprocessing.

Selecting a Sheet in the mapping flow has been updated to apply the same sort
order consideration as the sidebar. This enhancement ensures consistency in
workbook sorting for improved user navigation.

Now, origin tracking is available for file uploads, supporting sources like
Google Drive, File System, Box, and OneDrive.

Case-Insensitive Checking:

Our latest update enhances the validation process by identifying duplicate field
keys in workbook sheets, including case-insensitive comparisons. This ensures
that field keys are unique regardless of character casing, maintaining data
integrity and consistency across your datasets.

Data Integrity Assurance:

By preventing the entry of duplicate keys, even when differences are only in
letter casing, we enhance the accuracy and reliability of data processing within
our application.

A new new sizing options has been added for string fields to enhance visual
customization and user interface consistency.

See the new
property.

Extended Wait Time for Workbook Readiness:

To accommodate more complex data processing needs, we have extended the maximum
wait time for workbook readiness from 30 to 120 seconds. This adjustment ensures
that larger or more complex workbooks have sufficient time to complete their
build process without interruption.

Added Timeout Functionality:

We've introduced a new timeout feature that automatically stops the workbook
building process if it exceeds the allotted time. This prevents prolonged waits
and potential system overloads, improving overall system reliability.

Improved Logging Capabilities:

To aid in troubleshooting and optimize workbook build performance, we have
enhanced our logging system. Logs now include additional context information,
offering deeper insights into the workbook building process and helping identify
and resolve issues more efficiently.

We've introduced a new configuration property that allows users to set
individual cells within a record to read-only. This enhancement extends our
previous functionality where only entire columns or sheets could be designated
as read-only. Now, you can apply more granular control over data manipulation by
restricting editing at the cell level, improving data integrity and compliance.

See the
reference.

Fixed Sheet Name Sanitization for Downloads

We've improved the file download process by sanitizing sheet names that contain forward slashes. Previously, when a sheet had a name with forward slashes (e.g., "people/Contacts"), downloading the sheet could cause issues with file paths. Now, forward slashes in sheet names are automatically replaced with underscores when generating download filenames, ensuring a smooth download experience regardless of the sheet naming convention used.

Users can now seamlessly move to the next row in the cell by hitting the enter
key. This enhancement improves the user experience and streamlines data entry in
the Flatfile platform.

Users can now edit text in multi-line mode, enhancing the editing experience
within the platform.

You can now upload a file from Box. Once you've connected your Box account, you
can select a file to upload directly into Flatfile.

You can now set the default App for your Account. This App will be your default
landing page. Additionally, any unlinked Spaces will appear here.

We’ve fine-tuned the interplay between AI-generated mapping suggestions and
user-defined mapping history to enhance accuracy and user trust in our system.
Previously, AI recommendations marked as “very confident” could override
mappings with a user history score greater than 0.99. To address this, we’ve now
implemented a cap on AI mapping scores, ensuring they do not exceed 0.99. This
change guarantees that high-confidence user history takes precedence, fostering
a more reliable and user-centric mapping experience.

We've enhanced our user invitation system for improved clarity and data
integrity. Each user can now hold only one active invitation at any given time.
Any new invitation issued to a user will automatically replace the previous one.
This measure is designed to maintain data accuracy and eliminate user confusion.

We've refined our column management experience to align with your expectations
for immediate, responsive interactions. Key updates include:

Instant Feedback: Adjustments made within the column management panel now
reflect instantly on the table. This immediate update ensures you can
dynamically manage your view without waiting for panel closure.

Enhanced User Experience: This change addresses feedback regarding the previous
UX, where updates only occurred post-panel closure, leading to confusion. Now,
you can see the impact of your selections or deselections in real-time, making
for a more intuitive and satisfying user experience.

These improvements are designed to make your data management processes more
efficient and user-friendly, allowing for seamless adjustments to your viewing
preferences on the fly.

lastActivityAt is designed to provide you with comprehensive insights into the
activity within your Spaces. Here's what you need to know:

What is lastActivityAt?

An optional datetime attribute that marks the date of the last significant
activity within a Space. Activities considered include, but are not limited to,
adding records to a sheet, uploading files, or altering the configuration of a
workbook.

Precision and Insight:

Tracked with second-by-second-level precision, lastActivityAt offers a
valuable overview of your Space's engagement and operational dynamics, helping
you understand user behavior and space utilization better.

Reach out with feedback as we continue to enhance the utility of this feature to
support your needs better.

Learn more

We fixed an issue where Documents weren't automatically updating in response to
event stream activities (such as document creation, updates, or deletions). This
fix ensures that document changes are now promptly reflected in the UI, keeping
your Space synchronized with all recent activities.

We've resolved a critical bug in the RecordHook functionality, where metadata
wasn't correctly assigned during record updates. By overhaulubg the workflow for
setting and clearing metadata across various scenarios, we've can ensure
accurate and consistent metadata management.

Users can now update their space metadata object with a theme configuration to
customize the look of their emails. When this feature is flagged on, users can
enjoy custom theming in their email communications.

{"theme":
        {"email":
        {"logo":"https://i.imgur.com/xuzxTAU.png",
        "textColor":"#FDEBF7",
        "titleColor":"#FFC0CB",
        "buttonBgColor":"#A7C7E7",
        "backgroundColor":"#34495E",
        "buttonTextColor":"#FFFFFF",
        "footerTextColor":"#F4D1D1"}
        }
}

Learn more about Theming.

We’ve addressed a nuanced issue concerning enum mapping and rule application in
datasets with no values. Previously, the system saved enum mapping rules with a
logic in place to reuse these rules if every value in a new dataset matched the
rule. This approach inadvertently included scenarios where datasets had no
values, considering them as matching all rules due to the absence of values.

Now, the system filters and applies enum mapping rules based solely on the
values present in the new dataset. This change ensures that rules are applied
more accurately, enhancing the system’s logic in handling datasets, especially
those without any values. This update aims to provide a more reliable and
logical framework for data processing and rule application.

Enjoy longer, uninterrupted sessions when working with your Flatfile Dashboard.

We've upgraded the Files View with new capabilities to improve your file
management workflow. Now, you can select and upload multiple files
simultaneously through the File Uploader, streamlining the process.

While the upload progress is displayed for the initial file to maintain clarity,
rest assured that all selected files are being uploaded.

Additionally, the drag-and-drop feature has been enhanced to support multiple
files, making it easier than ever to upload documents directly into the Files
View. This update is designed to enhance productivity and simplify your data
management tasks.

We've streamlined the loading process for Spaces by eliminating an unnecessary
request for translations that previously triggered an additional getSpaceById
call. This refinement reduces the load time, ensuring Spaces are displayed more
promptly for a smoother user experience.

We've upgraded the GET /spaces endpoint to support an empty value for the
namespace query parameter. This update allows for more nuanced filtering,
specifically enabling the identification of spaces without a namespace. When the
namespace parameter is omitted entirely, the endpoint now returns spaces across
all namespaces, providing greater flexibility in data retrieval and management.

By strategically eliminating or deferring five key blocking requests, we've
streamlined the data fetching process. Key improvements include the removal of
non-essential data fetches, optimizing the placement of the i18n context for
more efficient rendering, and introducing a new utility for pre-processing date
formats.

These updates collectively result in a smoother, faster user experience,
reinforcing our commitment to efficiency and performance.

We've streamlined the loading process for Spaces by eliminating an unnecessary
request for translations that previously triggered an additional getSpaceById
call. This refinement reduces the load time, ensuring Spaces are displayed more
promptly for a smoother user experience.

Beyond the existing functionalities of sorting, replacing empty values, and
conducting searches within fields, we’ve now integrated a precise value
filtering option for columns. This new feature includes a convenient search
mechanism to effortlessly pinpoint and filter by the specific value you’re
seeking. Streamline your data analysis and management with this robust filtering
capability.

In our continuous efforts to streamline data import processes, we've implemented
an improvement targeting the scenario where mapping rules from previous imports
include destination fields no longer present in the current schema. This
situation can arise if a custom field was added during a past import session and
the data being imported is from a completely new sheet, often observed in
embedded imports. With this update, we ensure a smoother data mapping experience
by automatically filtering out rules that do not match the current destination
blueprint, maintaining consistency and accuracy in your data integration
efforts.

We’re excited to announce the launch of the Flatfile Dedicated Mapping API, a
significant enhancement to our suite of tools. This new API, encapsulated within
a user-friendly Python library, is designed to fully harness Flatfile’s mapping
capabilities. It provides a robust solution for mapping schemas directly within
your systems, ensuring that your data remains secure in your database. This API
is ideal for a range of applications, from data pipelines and API integrations
to complex data conversion workflows.

The essence of mapping with this API is the transformation of source records
into target records. This process ranges from straightforward tasks like
renaming fields (for example, changing “first_name” to “firstName”) to more
complex operations such as extracting substrings from fields or concatenating
multiple fields.

Our Mapping API and accompanying Python library bring forth new opportunities
for efficient and precise data mapping, offering customization to meet your
unique needs and workflow requirements.

To get started, refer to the
README.

We've added an expansion of our language support to include a variety of new
translations. This update builds upon our existing capabilities, which
previously covered French, German, Indonesian, Portuguese, and Spanish.

What's New?

• Italian (it)
• Japanese (jp)
• Korean (kr)
• Brazilian Portuguese (pt-BR)
• Turkish (tr)
• Vietnamese (vi)
• Chinese (zh)

Our goal is to continuously add languages that resonate with our diverse user
base. If there's a language you need that we haven't yet included, let us know!

Developers can now add an optional flag to Actions, preventing users from
initiating Actions when Sheets or Workbooks don’t yet have any records. This
helps avoid unnecessary job failures and ensures Actions are performed only once
data is present.

actions: [{
        "constraints": [{ "type": "hasData" }]
}]

Learn more about all the constraints available for
Sheet and Workbook Actions. or
See the Guide to see it in use.

We’re delighted to introduce a new constraint in Sheets aimed at bolstering data
integrity. This constraint guarantees that a designated combination of two or
more fields maintains uniqueness throughout the entire Sheet.

To activate this feature, it’s as simple as adding certain parameters to the
constraints property in your Sheet configuration.
See a breakdown of the
necessary parameters to effectively implement composite uniqueness.

Based on user feedback, we've updated the visual design of the "Powered by
Flatfile" chip to distinguish it from actionable buttons, enhancing the user
interface for clarity.

For those interested in a fully branded experience, we offer the option to
remove this chip entirely through our Professional
package.

For users utilizing the trackChanges on their Workbooks (disables your actions
until all commits are complete), we’ve addressed a critical workflow concern.

Changes in a Reference field result in the creation of a new commit event, which
was leaving the original commit incomplete. Furthermore, this new commit wasn’t
triggering an event emission, leading to a chain of incomplete commits.

We’ve refined the commit completion process: now, commits will be marked as
complete whenever the user explicitly references a commit in an update request.

This adjustment is handled out of the box with @flatfile/plugin-record-hook
and ensures a more streamlined and reliable change tracking experience.

Enhancements to the Spaces sidebar now offer at-a-glance insights for greater
efficiency: each workbook's entry displays a count of contained Sheets,
alongside a tally of records within each Sheet. Additionally, the validity of
records is intuitively indicated with color-coded dots—green for valid and red
for invalid—directly within the Sheet summary. This allows for quick
identification and management of data accuracy.

We've optimized the file deletion process for large files. The next time you
remove a sizable file, expect to experience a noticeably faster removal speed.

We've extended the functionality of the toolbarBlocking job mode beyond
individual Sheets. Now, when it's applied to Workbook-mounted actions, this mode
also disables workbook actions (including all of the Sheets actions/toolbars)
during a job's progress. By its nature, it also still allows interaction with
the actual data tables.

This enhancement provides more consistent control throughout your entire
Workbook, ensuring tasks are completed efficiently and without accidental
interference or unintended navigation.

Learn more

We've introduced an exciting new capability to enhance user interaction and
feedback in our application. You can now add custom messages to actions,
tailored according to their state:

• Error
• Info

These messages will be displayed as tooltips when users hover over an action,
providing context-specific text that corresponds to the action's current state.

Follow the guide

Previously, using workbook update endpoint necessitated submitting all the
fields, even for minor adjustments to an action. Now, with our improved PATCH
endpoint, you can update actions without needing to include the fields
property in your payload.

This refinement simplifies the update process, focusing solely on the changes
you intend to make.

See the endpoint

A Toast now displays intermediate states to keep you informed every step of the
way during file extraction.

When uploading a file directly to the table, you’ll see statuses like “Waiting
for Extraction”, “Extracting”, and “Unsupported File”, along with detailed
information about the outcome of extraction jobs.

When uploading on the Files page, the error message is toned down to an info
message, as uploading files without an extractor is a legitimate scenario.

These updates are aimed at enhancing transparency and efficiency, ensuring
you’re well-informed throughout the file extraction process.

See extractor plugins

We've refined the search mechanism for empty cells in the GET records endpoint.
In the past, users would specify null in the searchValue parameter to locate
empty cells. However, this method posed ambiguity as it didn't clearly
distinguish between an exact search for null values and a partial search for the
string "null".

Now, to accurately search for cells with null values, you should use empty
double quotes "" in the searchValue parameter.

See the endpoint

We're excited to announce a broad range of new theming capabilities that enhance
the visual appeal and customization of our platform:

Usage

{
  "theme": {
    "root": {
      "borderColor": "pink",
      "modalBorderRadius": "10px",
      "popoverBorderRadius": "8px",
      "tabstripActiveColor": "deepskyblue",
      "tabstripInactiveColor": "orange",
      "popoverBackgroundColor": "limegreen",
      "tabstripHoverTextColor": "gold",
      "tooltipBackgroundColor": "hotpink",
      "tabstripHoverBorderColor": "purple"
    }
  }
}

1. Theming for Tabs: Customize the look and feel of tabs to better match your
   application's design and user experience.

2. Enhanced Tooltip Styling: Gain more control over tooltip aesthetics with
   expanded theming options, ensuring they align seamlessly with your interface.

3. Refined Borders Across Components: Apply custom themes to borders, providing
   a sharper and more cohesive visual distinction for various elements.

4. Popover Customization: Tailor the appearance of popovers with new theming
   capabilities, enhancing their integration within your application's layout.

5. Modal Window Styling: Elevate the design of modal windows with customizable
   theming options, contributing to a more engaging and harmonious user
   experience.

These updates offer a greater degree of flexibility in customizing the
appearance of key UI components, allowing for a more integrated and visually
consistent application design.

Learn more.

We're delighted to announce that field descriptions now support Markdown
formatting. This enhancement enables you to create more informative and engaging
field descriptions, complete with formatted text and hyperlinks.

Usage

"fields": [
  {
    "key": "code",
    "label": "Product Code",
    "description": "This can be **markdown**."
    "type": "string"
  },
]

• Rich Formatting Capabilities: Leverage the power of Markdown to format your
  field descriptions, making them more readable and useful.

• Incorporate Links: Easily include links in your field descriptions, providing
  direct access to additional resources or related information.

• Versatile Display Across Interfaces: These enriched descriptions are displayed
  as tooltips within the data table and in mapping. Additionally, the full text
  of the descriptions is available in the data checklist for comprehensive
  insights.

This update is designed to improve the clarity and effectiveness of field
descriptions, enhancing the overall user experience in data interaction and
comprehension.

Learn more about Blueprint and Fields.

We've enhanced the inputForm feature in Actions by supporting defaultValue
settings for enums, strings, and textarea field types.

Usage

"inputForm": {
  "type": 'simple',
  "fields": [
    {
      "key": 'planName',
      "label": 'Plan Name',
      "type": 'string',
      "description": 'The name of the plan',
      "defaultValue": 'Default plan'
    },
  ]
}

This update allows for more intuitive and efficient data entry, as default
values can be pre-filled in these fields, streamlining the user experience.

Learn more about Actions and Input Forms.

The latest updates in our theming capabilities bring a fresh look and enhanced
customization to various UI elements:

Usage

{
  "theme": {
    "root": {
      "badgeBorderColor": "green",
      "interactiveBorderColor": "orange",
      "interactiveBorderRadius": "0px"
    },
    "table": {
      "cell": {
        "active": {
          "borderWidth": "2px",
          "boxShadow": "3px 3px 0px 0px #000000"
        }
      },
      "tooltip": {
        "borderRadius": "0px"
      },
      "lookupEditor": {
        "option": {
          "borderRadius": {
            "hover": "0px",
            "active": "8px"
          },
          "backgroundColor": {
            "hover": "yellow",
            "active": "lavender"
          }
        }
      }
    }
  }
}

1. Enhanced Dropdown, Text Input, and Context Menu Theming: Users can now apply
   customized themes to dropdowns, text inputs, and context menus, offering a
   more cohesive and personalized interface design.

2. Refined Active Cell Styling in Tables: The active cell in the table now
   features themable border width and box shadow, adding depth and focus to the
   selected cell.

3. Upgraded Tooltips in Tables: Tooltips in the table now support theming for
   border radius and box shadow, allowing for smoother integration with the
   overall design aesthetic.

4. New Optional Border for Badges: An optional border can now be added to badges
   within the app. This update extends to TT badges in enum columns, providing a
   consistent and visually appealing element across the platform.

These theming enhancements are part of our ongoing commitment to provide a
versatile and visually engaging user experience, allowing for greater
consistency and branding alignment across our platform.

Learn more.

We're pleased to announce the expansion of our theming capabilities with new
customization options for checkboxes:

Usage

{
  "theme": {
    "root": {
      "checkboxBorderRadius": "0px",
      "checkboxBorderColor": "red"
    },
    "table": {
      "inputs": {
        "checkbox": {
          "borderColor": "magenta"
        }
      }
    }
  }
}

1. Customizable Checkbox Border Radius: Users now have the flexibility to theme
   the border radius of checkboxes, allowing for a more personalized and
   visually cohesive interface.

2. Theming for Checkbox Border Color: Alongside border radius customization,
   users can also theme the border color of checkboxes, adding another layer of
   visual customization to match your application's aesthetic.

3. Override Options in Table View: In table contexts, users have the added
   ability to override the default checkbox border color, offering even more
   control over the table's appearance and consistency with your overall design
   theme.

These enhancements aim to provide greater flexibility and control over the UI,
enabling users to tailor the look and feel of checkboxes to better align with
their unique branding and design preferences.

Learn more.

We're excited to announce new additions to our theming capabilities, allowing
for even more customization and a refined user experience.

Usage

"theme": {
  "root": {
    "pillBorderRadius": "0px",
    "badgeBorderRadius":"10em"
  },
  "table": {
    "buttons": {
      "pill": {
        "color": "white",
        "backgroundColor": "magenta"
      },
      "iconColor": "magenta"
    }
  }
}

What's New:

1. Pill and Badge Border Radius Customization: You can now tailor the border
   radius of pills and badges within space theming. This update enables you to
   define and apply a consistent look across all pills and badges in the space
   according to your design preferences.

2. Toolbar Button Color Theming: We've also introduced the option to customize
   the color of toolbar buttons, giving you more control over the visual style
   of your toolbar.

3. Inherited and Customizable Toolbar Filters: Toolbar filters will
   automatically inherit the pill border radius settings for a unified
   appearance. However, this can be overridden to suit specific design needs,
   offering both convenience and flexibility.

These enhancements are part of our ongoing commitment to providing a versatile
and user-friendly platform that caters to your unique theming requirements.

Learn more.

We've given our foreground jobs a fresh, new look:

1. Enhanced Job Modal Header: The job modal header now prominently displays job
   information, making it instantly visible and accessible.
2. Refined Display Details: Information that was previously in the header is now
   elegantly presented as an ultralight subline for improved readability.
3. Optimized Layout: We've repositioned the display of the percentage and
   remaining time for better clarity and focus.
4. Improved Time Estimation: For estimated completion time, we've introduced a
   fallback mechanism based on simple linear extrapolation, ensuring more
   accurate and reliable predictions.

These updates are designed to offer a more intuitive and streamlined user
experience in tracking and managing foreground jobs.

In addition to the existing ability to link to external URLs and trigger
downloads, you can now also display links to internal resources upon job
completion. This enhancement broadens the scope of actions you can perform,
offering more versatility in directing users to relevant resources or actions
post-job completion.

In this code below, we will create a button that says “See all downloads” with
this path: /space/us_sp_1234/files?mode=export

Usage

await api.jobs.complete(jobId, {
  outcome: {
    message: `The file has been created`,
    acknowledge: true,
    //Reference: https://platform.flatfile.com/s/space/{$id}/{path}?{$query}
    next: {
      type: "id",
      id: "dev_sp_1234",
      path: "files",
      query: "mode=export",
      label: "See all downloads",
    },
  },
});

This improvement adds versatility and flexibility to your job outcomes,
enhancing user interaction and experience.

Learn more.

You can now also display links to retry a job upon job completion or failure.
This enhancement broadens the scope of actions you can perform, offering more
versatility in directing users to relevant resources or actions post-job
completion.

Usage

await api.jobs.complete(jobId, {
  outcome: {
    message: `The file has been created`,
    acknowledge: true,
    next: {
      type: "retry",
      label: "Try again",
    },
  },
});

This improvement adds versatility and flexibility to your job outcomes,
enhancing user interaction and experience.

Learn more.

We've expanded the theming capabilities for filters, providing a more
customizable and visually appealing interface:

Usage

"theme": {
    "table": {
      "filters": {
        "outerBorder": "2px red solid",
        "innerBorderRadius": "0px",
        "outerBorderRadius": "0px"
      }
  }
}

1. New Styling Features for Filters: We've introduced the option to customize
   filters with borders and border radius as part of the table theme.

2. Flexible Border Radius Design: To accommodate the varying sizes of elements
   and the potential difference in calculated border radius, we now use both
   inner and outer border radius settings. This enhancement not only ensures a
   cohesive look but also adds an extra layer of styling flexibility to the
   filters.

These improvements are designed to offer more control over the aesthetics of
filters, enabling a seamless and integrated visual experience.

Learn more.

We're excited to announce the addition of the new GET
/workbooks/{workbookId}/commits endpoint. This improvement streamlines the
process of retrieving all commits associated with a specific workbook, offering
a more efficient way to determine the completion status of all processing
activities on that workbook.

While this enhancement primarily benefits the Flatfile UI, the endpoint is fully
exposed, making it a valuable tool for developers looking to optimize commit
retrieval and processing status checks in their own applications.

See the endpoint

To enhance clarity and efficiency in job processing, we’ve implemented an update
for managing long-running jobs. Previously, jobs that weren’t acknowledged
within 5 minutes would silently fail due to a timeout by the agent, leading to
confusion as these jobs never reached completion (They were left in an executing
state).

To address this, we’ve now added a routine check that occurs every 5 minutes.
This check will automatically fail jobs that are still executing but haven’t
been
acknowledged
(ack’d) within this timeframe. This update ensures better transparency and
control in the job execution process, reducing confusion and streamlining
operations.

Previously, developers faced challenges in determining when all rows were valid,
essential for preventing unintended data egress.

Now, developers can now add an optional flag to Actions, preventing users from
initiating Actions when Sheets or Workbooks contain invalid records.

actions: [{
  ...
  constraints: [{ type: 'hasAllValid' }]
  ...
}]

Add a constraints parameter in your Action that includes type: hasAllValid,
to disable actions when there are invalid records.

Learn more

We've added a new feature that allows you to search for spaces using their Space
ID in the Spaces table. This enhancement simplifies the process of locating
specific spaces quickly and efficiently.

We assign an 80% value to other users' history compared to the current user's
history. Previously, this was only applied to field mapping, Now, this approach
has been extended to enum mapping as well.

This update addresses an issue where conflicting histories between two users
could result in one user being unable to edit due to the other's history taking
precedence.

With this enhancement, the system now more effectively balances historical
inputs from different users, ensuring smoother and more equitable enum mapping
automation.

We’ve added a new feature that allows for the selection and bulk deletion of
Spaces from your list. This enhancement is particularly beneficial for customers
managing numerous Spaces, as it eliminates the need to delete each Space
individually, streamlining the process and saving time. Enjoy!

We've introduced a new feature that allows for selective hiding or showing of
columns, enabling users to customize their view for more focused work.
Additionally, your column visibility preferences will now be automatically saved
to local storage, ensuring that your personalized settings are remembered for
future sessions. This update aims to enhance user efficiency by allowing you to
tailor the interface to your specific needs and workflow.

Previously, accessing Flatfile either directly through a URL or via an iframe
with an accessToken would categorize all user activities under an anonymous
guest. Now, if you know the guestId, interactions in Flatfile can be tied back
to that person.

This is made possible with a new endpoint, /guests/:guestId/token, which
generates an accessToken, and can be used to load the Flatfile space at
http://platform.flatfile.com/space/:spaceId?token=:accessToken.

With this method, Guests are now accurately named and identifiable, enhancing
user recognition and auditing.

See the endpoint.

When either the source (file) or destination (Blueprint) list contains more than
100 enums, our mapping AI will now utilize a simplified algorithm. This change
addresses scenarios where customers have extensive enum lists, such as 5,000
different Shopify products, which previously slowed down our assignment
algorithm. With this update, the execution speed for such extensive lists will
be faster, ensuring a more efficient and responsive experience for clients with
large datasets.

We’ve fixed an issue where guests with
workbook-only access
could upload files but couldn’t extract them due to access restrictions. Guests
can now upload and extract files smoothly in workbooks they have access to.

There are a few places where the Flatfile logo appears to your end customers.

1. The Powered By Flatfile logo appears in the bottom right of Workbooks.
2. When sending invitations to Users or Guests, the Flatfile logo is included at
   the top of the emails.

For those seeking a complete white-labeling experience, we offer a fully
customizable solution as part of our Pro plans and above. Feel free to get in
touch with us at support@flatfile.com to discuss
the possibilities of a fully whitelabeled experience tailored to your needs.

Within each Space, we've implemented an informative tooltip providing essential
details about the Space. This tooltip serves as valuable support for addressing
customer inquiries and issues. However, we understand that there are scenarios
where you may prefer to hide this information from your customers.

To accommodate your preferences, we've introduced the option to hide this Space
tooltip. To make this adjustment, you can utilize the "Update Environment" patch
available in our
API Reference.

metadata: {
  showSpaceInfo: false;
}

With this unification, you can now seamlessly interact with our API, ensuring a
smoother and more reliable experience.

We're excited to announce a new parameter within Sheet configuration, aptly
named mappingConfidenceThreshold. This parameter empowers you to fine-tune
your experience when working with automatically suggested fields during mapping
jobs.

With mappingConfidenceThreshold, you have the flexibility to configure the
minimum required confidence level. Think of it as a precision control, offering
you the choice between conservative (exact match) or liberal (fuzzy matching)
settings.

How it works

Set the value greater than 0 and up to a maximum of 1, for a more precise
control over the mapping process:

  sheets: [
    mappingConfidenceThreshold: .6,
    {...}
  ]

Learn more

Now, FFQL queries made via filter: in the the search bar can be seamlessly
combined with other filters. Whether you prefer using tabbed filters like
“valid” and “error,” or you rely on the “Filter By Value” menu, you can now
harness the power of FFQL alongside these filters.

With this update, you’ll experience precise narrowing of row results every time
you apply FFQL queries in conjunction with other filters. No more guesswork—your
filtered results will be spot on, making it easier than ever to find the
information you need with pinpoint accuracy.

You can now control the font of the headers in a table using the
column.header.fontFamily property.

Learn more

We've improved the functionality for copying cells from external spreadsheets
into our system. Now, when you copy cells containing more than one line, these
new lines are preserved in the cell value upon pasting.

While these additional lines may not be visually apparent in the table, you can
verify their presence by inspecting the data through the API, or by copying and
pasting the cell content into another application.

This update ensures better data integrity and consistency when transferring
content with complex formatting.

We have lifted the previous 255-character limit for mappings, jobs, and enum
mappings. This update allows for greater flexibility and more detailed entries
in these areas.

API users now have the capability to restore an archived space. This can be done
by setting the archivedAt property of the space to null via the
PATCH /spaces/:spaceId endpoint.

We've enhanced the deletion process for Spaces. In the past, deleting a Space
did not automatically cascade to its Workbooks and Sheets. Now, with the latest
update, soft deleting a Space will also soft delete its associated Workbooks and
Sheets.

Furthermore, we've refined the GET /workbooks query. It now filters out
workbooks linked to previously deleted Spaces, ensuring that only relevant and
active workbooks are displayed. This update is helpful for Spaces deleted before
this improvement was implemented.

We've addressed an issue in the table where enum options without a label were
incorrectly displaying as 'undefined'. With the latest update, in cases where an
enum option lacks a label, the table will now default to showing the option's
value instead.

This ensures a more accurate and user-friendly display of data.

Previously, developers faced challenges in determining when all hooks had
finished running, essential for ensuring data transformation completion and
preventing unintended data egress. As a workaround, they resorted to creating
placeholder fields that defaulted to invalid states. When a hook completed
processing for a record, it marked the field as valid, allowing submission only
when there were no errors in this field.

Now, we're thrilled to introduce a solution to simplify this process—an all-new
event: commit:completed. This event signals the end of all processing tasks.

settings: [{ trackChanges: true }];

Add a settings parameter in your sheet that includes trackChanges: true, to
disable actions on both Sheets and Workbooks until any pending commits have been
completed.

Learn more

We're excited to introduce a third job mode called toolbarBlocking alongside
the existing foreground and background modes. With this new mode,
toolbarBlocking, you have the flexibility to disable the Sheet Toolbar and
Column Header Menus while still allowing users to enter records manually.

Learn more

We've enhanced the bulk selection experience by enabling paste functionality.
When you paste, we simply transition you out of the selection state, similar to
when editing. Note: if you paste without selecting any cells, the operation will
automatically apply to the bulk-selected rows.

Now, by simply incorporating the embed HTML entity into your markdown body and
providing the sheet ID, workbook ID, and name, you can effortlessly embed Sheets
into Documents. Additionally, you have the flexibility to choose whether the
embedded Sheet starts in an expanded or collapsed state when the document is
loaded.

<embed
  type="embedded-sheet"
  name="Contacts"
  defaultExpanded="true"
  sheetId="your_sheet_id"
  workbookId="your_workbook_id"
/>

This enhancement provides further freedom to tailor document-driven interactions
precisely to your needs.

Learn more

Documents, which are standalone webpages within your Spaces, can now host a
variety of actions, just like Workbooks, Sheets, and Files.

Document-Mounted Actions have their own configuration within a Document object.
The executable code within an Action is compiled into a Job entity, offering the
flexibility to run asynchronously or immediately. This empowers you to create
more interactive and dynamic Documents, enhancing the overall user experience
within your Flatfile Spaces.

//your document can now have an action that looks like this
actions: [
  {
    operation: 'sendAction',
    mode: 'foreground',
    label: 'Send to...',
    description: 'Send this page to someone.',
    primary: true,
  },
  {...}
]

Learn more

With the introduction of these API actions, you gain the ability to manage sheet
locking within your application. The sheets.lock action allows you to lock a
sheet, preventing any further modifications to its content. Conversely, the
sheets.unlock action enables you to release the lock and restore full editing
capabilities to the sheet.

These new API actions provide greater control and flexibility when it comes to
managing sheet access and data integrity.

See the endpoint

Documents have gained a new capability, allowing them to seamlessly transition
into full-screen takeovers, thus removing their presence from the sidebar.

How it works:

To enable this functionality, we've introduced a new property on Documents:
treatments. This property allows users to define specific descriptors for each
Document. When a Document is assigned the "ephemeral" treatment, it will
transform into a full-screen overlay, visible exclusively within the Spaces
dashboard, while being discreetly tucked away from the Spaces sidebar.

This enhancement enhances user creativity and provides the freedom to tailor
document-driven interactions precisely to their needs.

await api.documents.create(spaceId, {
  treatments: ["ephemeral"],
  title: "Getting Started",
});

Learn more

Building upon our existing language support (based on your customers’ browser
locale), which already included French, German, Portuguese and Spanish
translations, we’ve expanded our capabilities to cater to an even broader
audience.

Need another language? Let us know and we’ll prioritize getting it added.

When acknowledging a job from a Workbook or Sheet action, you now have the
option to set the estimatedCompletionAt parameter. Setting the estimated time
of completion for the job leads to more informative and interactive features in
the UI.

1. In the Foreground Job overlay, you'll see real-time progress displayed as a
   percentage, along with an estimate of the remaining time.

2. Additionally, the Jobs Panel will share visibility into the estimated
   remaining time for acknowledged jobs.

Learn more about using Actions.

See the
API Reference.

This improvement is particularly beneficial for @flatfile/plugin-record-hook,
which can now retrieve and respond to all records in a single find/replace
operation, thanks to the 10,000-row batching.

Learn more about sharing secrets.

Now, when initiating an action, you have the option to gather additional
information from end users to facilitate the successful completion of the
intended task.

Here’s how it works:

Suppose you want to allow users to specify the name of the file they intend to
export. In such cases, you can configure input fields for your action. When an
end user triggers this action, a secondary dialog will appear, prompting them to
provide the necessary information.

The available input types include:

• string: For capturing text-based information.
• textarea: Ideal for longer text entries or descriptions.
• number: To collect numeric data.
• boolean: For simple yes/no or true/false responses.
• enum: Enables users to select from a predefined list of options.

Two easy ways to get started:

• Learn about all the parameters available on inputForm for Actions
  here.
• Or follow this copy/paste Guide
  to quickly see it in action in your code.

With additional fields, end users can seamlessly map to fields that don’t exist
by simply adding a new property to any of your new or pre-existing Blueprint(s).

Here’s how it works:

• When you set allowAdditionalFields to true, your Sheet gains the ability to
  accept additional fields, extending beyond what’s originally specified in its
  configuration.
• These extra fields can be incorporated, either through API integrations or by
  end users during the file import process.
• Fields that go beyond the Blueprint’s initial setup are marked with a
  treatment property set to additional, ensuring complete transparency over what
  extends the Blueprint.
• What’s more, adding a custom field is a breeze—its name will be automatically
  set to match the header name from the file being mapped. This simplifies the
  process.

See the docs.

Our aim is to make it easy for everyone to monitor events, find problems, and
help developers avoid overcomplicating their code with excessive Console logs
that would need removal later.

With our enhanced Event logs, you can now:

1. View a comprehensive list of logged events, categorized by event topic.
2. Easily discern the status of each event.
3. Gauge the execution time of each event.
4. Access events chronologically, with the most recent at the top.
5. Dive into each event for context and review any associated console logs.

As an added bonus, you have the capability to filter events, focusing solely on
failures.

See it live: platform.flatfie.com/logs

In this update, we've harmonized the process by accepting space characters as
valid characters for secret names in both the API and the UI. Your secret names
can now include spaces without any issues.

Building upon our existing language support (based on your customers’ browser
locale), which already included French, German, and Spanish translations, we’ve
expanded our capabilities to cater to an even broader audience.

Need another language? Let us know and we’ll prioritize getting it added.

Until now, you could only utilize Markdown for your Documents. However, we're
excited to inform you that HTML support has been seamlessly integrated, offering
you even more versatility to tailor your Documents exactly to your liking.

For instance, if you needed to eliminate dashes from UUID fields, you'd
naturally want "abc-123" to transform into "abc123" rather than mysteriously
turning null.

We value your feedback. Now, you can confidently perform partial replacements
without the hassle of unexpected null values.

We are excited to introduce localization features in Flatfile! Now, your
customers will enjoy automatic translations based on their browser locale,
including French, German, and Spanish.

Key Features:

• Translations are exclusively applied in Spaces (guest areas).
• Our user-friendly guide will assist you in effortlessly translating and
  personalizing the content within your space, whether it's custom actions,
  documents, and more.
• Require another language? Send us a note, and we'll make it a priority to
  include it.

Follow the guide or try the
Localization demo Space to get
started.

Previously, the primary:true concept on Actions didn't affect Sheet actions,
leaving them all in the "more actions" drop-down. But now, setting primary to
true will showcase these actions right in the Sheet toolbar, as buttons with
clear, user-friendly text.

We've introduced the ability to add code blocks to your Documents. You can now
use the following syntax to define code blocks and specify the language:

Your code will be formatted accordingly, enhancing the clarity and presentation
of your content.

filter: first_name eq ""

Now, you can easily query and filter records with empty values.

1. Add Markdown + HTML Documents to your Space
2. Customize the look and feel of Flatfile to match your brand

acknowledge: false

By default, job outcomes are reported through a toast notification in the
top-right corner. To utilize this, simply set outcome => message. This
approach ensures that your job completion status is promptly communicated to the
end user.

acknowledge: true

When the acknowledge option is configured as true, a persistent full-screen
modal is presented. This modal remains visible until the user interacts by
clicking the "Continue" button, acknowledging the outcome.

Usage

await api.jobs.complete(jobId, {
  outcome: {
    acknowlege: true,
    message: "Text here.",
  },
});

This enhancement provides flexibility in how you choose to inform users about
job outcomes. Learn more.

Job outcomes have been upgraded to support next action links. Now, you can
display links to external URLs, trigger downloads, or retry jobes upon job
completion/failure.

Usage

await api.jobs.complete(jobId, {
  outcome: {
    next: Url | Download | Retry,
    message: "Text here.",
  },
});

This improvement adds versatility and flexibility to your job outcomes,
enhancing user interaction and experience.

Learn more.

Two key enhancements to Actions have been introduced:

Disable Actions When Invalid Records: Developers can now add an optional
flag to Actions, preventing users from initiating Actions when Sheets or
Workbooks contain invalid records. This helps avoid unnecessary job failures and
ensures Actions are performed on valid data.

constraints: [{ type: 'hasAllValid' }],

Disable Actions When No Selected Records: To enhance the user experience,
we've introduced the hasSelection flag. When added as a constraint, this flag
disables Actions if no records are selected in the Sheet or Workbook, ensuring
Actions are only triggered when relevant data is chosen.

constraints: [ { type: 'hasSelection' }],

Learn more.

Enhanced Number Field Queries:

When conducting equality or inequality FFQL comparisons for number fields, the
query value is now cast to a number and then compared with the parsed "shadow"
value. This rectifies issues related to numeric comparisons. Additionally, we've
resolved a bug where numbers with no digits before the decimal point (e.g.,
".3") were not being properly parsed into shadow values.

Advanced Date Field Handling:

For date fields, query values are now attempted to be parsed into dates. On
the SQL side, a CASE statement is employed to parse the stored values into
dates for accurate comparison. To accommodate SQL-side date parsing
requirements, we've integrated a regex pattern to detect YYYY-MM-DD, m/d/yy,
and m/d/yyyy formats. This ensures correct parsing and comparison of date
values.

Fix for Invalid Number Input:

We've resolved a bug where changing a number field to an invalid number left the
previous "shadow" value intact. Now, in such cases, the previous shadow value is
properly cleared, leading to consistent and accurate behavior.

These updates contribute to improved query handling, better data integrity, and
a more seamless experience when working with number and date fields.

We've introduced a new parameter: tooltip to Actions, allowing the addition of
tooltips. These tooltips are now visible in the user interface for both buttons
and list items whenever the associated Action is enabled. This enhancement
provides users with clear and context-aware explanations for enabled Actions,
contributing to an improved overall user experience.

Visit the Getting Started page on your Dashboard to discover four new
options for effortlessly generating demo spaces:

1. Namespaces
2. Metadata
3. Egress
4. Sidebar Customization

Similar to the rest of the options, we've provided the underlying code for each
Space, simplifying the process of breaking down and comprehending the elements
on display.

The authentication query has been streamlined for optimized performance.
Extensive benchmarking has revealed that this refinement contributes to a
reduction of approximately 20 milliseconds for each request. This enhancement
results in faster overall processing and improved response times.

Furthermore, the default page size for Spaces has been set to 10, aligning
it with the specifications outlined in the API documentation.

In addition, the loading state of the "Continue" button has been refined to
ensure smooth recovery from server errors. This adjustment enhances the overall
user experience by providing more graceful handling of unexpected issues during
the process.

With the removal of the extraction step for CSV/TSV/PSV files, the import
experience is now more seamless than ever. As soon as the upload is complete,
these files are instantly extracted, ensuring an efficient and immediate
handling of your data.

The impact of this change is remarkable. What used to take approximately 3 and a
half minutes to extract now concludes in less than 10 seconds.

In addition, we now natively support TSV and PSV files meaning you don't need to
use an extractor plugin to support these file types.

While speed is the prime advantage, this upgrade doesn’t merely boost
performance. It also simplifies and enhances reliability in our system.
Previously, concerns about only a fraction of a file being extracted are now
history. Furthermore, this approach strategically eases the load on our
database, reducing the likelihood of encountering resource limits.

In essence, it’s a win-win for both efficiency and user experience.

Navigate to your Dashboard's Getting Started page to find an array of new
options for effortlessly creating demo spaces. Additionally, we've included the
underlying code for each Space, making it straightforward to deconstruct and
understand what you're seeing.

We’ve implemented a state-of-the-art technology to substantially enhance the
reliability and performance of our queue system. This improvement has a profound
impact on the execution of asynchronous tasks, like data validation.

This update enhances your workflow by centralizing experiences under the
Command+k shortcut.

A straightforward forward slash, followed by these options, grants access to our
data transformation and query tools:

• /transform (AI-powered)
• /query (AI-powered)
• /search (global search)
• /filter (Flatfile Query Language, ffql)
• /in (field-specific search)

Chat with us or email support@flatfile.com to
have this feature flagged on in your Account today!

The Sidebar now has three different states:

• Collapsed state
• Open state
• Totally hidden state

Additionally, the Sidebar will now automatically collapse itself on smaller
screens.

• Breaking the word
• Limiting the name to two lines and giving it an ellipsis if it overflows
• Adding a tooltip with the space name to truncated names
• Previously, badge names in the data checklist could break to two lines making
  them hard to read. This is also fixed.