Data Import Reference

How to create or update a Spendlab budget from imported data.

Whether building a spreadsheet for yourself or developing a data integration for your organization, use this documentation to ensure your data is successfully imported into Spendlab.

For other topics, refer to the main Reference Guide.

Contents

• Templates & Quick Start
• How to Import
• Data Encoding
• Value Formatting
• Columns
• Attributes
• Compact Layouts
• Missing Data
• Duplicate & Overlapping Data
• FAQ
• Contact Us

Templates & Quick Start

• Use a template as a starting point for importing data into Spendlab.

• Spreadsheet format: Open this file with a spreadsheet program (such as Excel, Google Sheets, or Numbers) and copy/paste from there into Spendlab.

  • Spendlab Data Template.xlsx

• Directly importable format: These data files in CSV format can be dragged and dropped directly into Spendlab to import data.

  • Spendlab_database_template.csv
  • Spendlab_report_template.csv

• Read on for more details about importing and formatting your data.

How to Import

• Choose an import destination

  Spendlab can either create a new file or update an existing file in response to data you import.

• Create a new budget: If you import data when Spendlab is showing the welcome screen with no budget file open, it will create a new budget file and populate it with the imported data.

• Update an existing budget: If you import data when a budget file is already open, Spendlab will use the imported data to update that existing file.

  When updating an existing file, Spendlab will:

  • Ask permission to add new rows for any Category/Name combinations in the imported data that are not already present in the file. If there is any missing information, the importer will use default values.
  • Update existing rows with new data from the import, overwriting old values if necessary.
  • Leave unchanged any existing information that is not overridden by the imported data.

• Import the data

  There are three ways to get your data into Spendlab:

• Toolbar Menu — Choose File > Import Data... to open the import dialog. From there you can paste CSV data or choose a .csv file from your computer.

• Copy & paste — Select rows and columns in your spreadsheet (Excel, Google Sheets, Numbers, etc.), copy them, and paste directly into Spendlab. The app will detect tabular data and attempt to import it automatically.

• Drag & drop — Drag a .csv file from your desktop or file browser and drop it onto the Spendlab window. The import process will automatically begin.

  Note that you cannot drag and drop a .xls or .xlsx file directly into Spendlab. You must either copy and paste from the spreadsheet or save it as a .csv file before importing.

Data Encoding

• Spendlab imports data from one or more tables formatted as follows.

• CSV format: The data must be formatted as plain text with table cells separated by a standard delimiter (comma, tab, pipe, semicolon, or ASCII code 30 or 31). If you copy and paste from a spreadsheet, this format will usually be generated automatically.

• Table headers: The first row of a table must contain column headers. The columns can be in any order (with some exceptions described below), but each column must be one of the column types that Spendlab recognizes.

• Table separators: If you import more than one table at a time, each table must be separated from other tables by a row that only contains one or more hyphens (or any dash-like character). See the templates for examples.

• Blank rows: Empty rows are ignored by the importer.

• Comments: Rows that start with a "#" sign (pound/hash symbol) are treated as comments and are ignored by the importer.

• In this documentation, we display tables in spreadsheet format for ease of reading. However, if you are creating a data pipeline or script, you should output the plain text representation (CSV format).

  Table displayed as a spreadsheet:

  Funding source	Attribute	Value	Period Start
  NIH grant	Balance including indirects	$292,695	2025-07-01
  DOE grant	Balance including indirects	$110,638	2025-07-01

  Table represented as plain text (comma-separated values):

  Funding source,Attribute,Value,Period Start
  NIH grant,Balance including indirects,292695,2025-07-01
  DOE grant,Balance including indirects,110638,2025-07-01

  ---

  Most spreadsheet programs automatically create the plain-text format when you copy cells, so you can directly copy and paste into Spendlab.

Value Formatting

• Keywords: Keywords are displayed Like This throughout this documentation. The importer recognizes keywords with any mix of upper or lower case, but they must be spelled exactly as shown. The importer does not use AI or inexact matching.
  • Valid keyword variants: "Period Start", "period start", "PERIOD START"
  • Invalid keyword variants: "PeriodStart", "Period Star", "Start Of Period".
• Monetary values: Thousand separators and currency symbols are allowed but ignored (no currency conversions). For example, "$50,000" and "¥50,000" are both equivalent to "50000".
• Rate values: Must be formatted as a percentage of 100. For example, use "54.3%" rather than "0.543". The percent sign "%" is optional but recommended.
• Date values: Most common standards are accepted, but we recommend non-ambiguous formats such as "2025-12-01" (ISO 8601) or "Dec 1, 2025" (US-en date format).
• Boolean values: Accepted values include "true"/"false" and "yes"/"no" with any mix of upper or lower case.

Columns

• Example with all standard columns: planned supplies costs as monthly recurring expenses.

  Category	Name	Period Start	Period End	Attribute	Value	Recurring Interval	Funding Source
  Supplies	NIH project	2024-09-01	2025-09-01	Total direct costs	$4,300	per month	NIH grant
  Supplies	NIH project	2025-09-01	2026-09-01	Total direct costs	$3,800	per month	NIH grant

• Spendlab recognizes the following data columns. They can be in any order.

• Category

  The name of the budget section that will be imported into. (For example: "Funding sources", "People", "Travel".)

  Matching is not case-sensitive, and any whitespace is trimmed. For example, " SUPPLIES   " will match an existing section named "Supplies".

  If no section with this name exists, a new section will be created.

  The following keywords have special meaning when used in the Category column:

  • File or File Setting — allows you to edit a file-wide setting, such as the file name or currency symbol.
  • Funding Source or Total — always matches the "Funding sources" section.
  • External Funding Source — creates an externally managed funding source with no tracked balance (instead of a default internal funding source).
  • Person, People, Personnel, or Labor — always matches the "People" section.
  • Supply or Supplies — always matches the "Supplies" section.
  • Equipment — always matches the "Equipment" section.
  • Currency Definition — creates a reusable monetary value that can change over time (see Definitions).
  • Rate Definition — creates a reusable percentage value that can change over time (see Definitions).

• Name

  The name of the Spendlab row that will be imported into. (For example: "NIH grant", "Jane Doe", "Conferences".)

  The importer looks for exact matches and then partial matches. For example, "NIH grant" and "304-551" will both match an existing funding source named "NIH grant (304-551)".

  Matching is not case-sensitive, and any whitespace is trimmed. For example, " NIH GRANT   " will match an existing funding source named "NIH grant".

  If no matches are found within the specified Category, a new row will be created with the provided Name.

• Attribute

  Specifies what property of the row to set. (For example: "Balance including indirects", "Salary", "Total direct costs".) Each type of row has its own set of valid attributes; see the Attributes Reference for a complete list.

• Value

  The number, date, or text value to set for the specified Attribute. (For example: "$50,000", "25%", "2025-07-01", "false".) See the Value Formatting section for more details.

• Period Start

  The start date for the data entry. (For example: "2025-07-01", "Jul 1, 2025".) For values that span a time range, use in conjunction with Period End. For one-time values, only Period Start is required.

• Period End

  The end date for the data entry. (For example: "2026-07-01", "Jul 1, 2026".) Used in conjunction with Period Start to define a date range for expenses, effort blocks, or funding installments.

  • You can specify end dates as either the last day of the period (e.g., "June 30, 2026") or the first day of the next period (e.g., "July 1, 2026").
  • If omitted, a default time duration is used.

• Recurring Interval

  Specifies how to interpret the Value over the time period from Period Start to Period End. Valid options:

  • none (default) — Value represents the total amount with no repeats
  • year — Value represents the annual amount
  • quarter — Value represents the quarterly amount
  • month — Value represents the monthly amount
  • half month — Value represents the amount per half-month period
  • two weeks — Value represents the biweekly amount

  For example, if Value is "$1,000", Recurring Interval is "month", and the time period spans 3 months, the total expense will be $3,000. If instead the Recurring Interval is omitted or "none", the total expense over the 3-month period will be $1,000, spread evenly over the 3 months as $333.33 per month.

• Funding Source

  The name of the funding source from which the expense or salary is paid. (For example: "NIH grant".) Must match the Name of an existing or concurrently imported funding source row. If omitted, the item is imported with an "unassigned" funding source to be manually allocated later.

  For rows with split funding, use multiple data rows with the Split attribute to specify the percentage from each source. (See the templates for examples.)

Attributes

• Each Spendlab object has an associated set of attributes. Each attribute expects certain values to be included in the data import row.

• Constant attributes require a Value in the data import row.

  Category	Name	Attribute	Value
  Funding source	NIH grant	Indirect rate	55.3%
  Funding source	NIH grant	Color	Light Purple

• Time series attributes require at least a Value and Period Start in the data import row.

  Category	Name	Attribute	Value	Period Start	Period End
  Funding source	NIH grant	Total including indirects	$388,828	2025-08-01	2026-08-01
  Supplies	NIH grant	Total direct costs	$50,000	2025-08-01	2026-08-01

• See the templates for more examples in context.

  Most attributes are optional and will fall back to default values if omitted.

  Attributes listed below are constant unless "Time Series" is specified.

• File Settings

  • File name — String — Sets the name of the Spendlab file. This appears at the top of the window and is used as the file name when saving or exporting.
  • Time step — Keyword — Specifies the pay period interval or minimum time unit used throughout the budget. Most dates in Spendlab are constrained to these time boundaries.
    • Accepted values: "month" (default), "half month", or "two weeks" (or "biweekly").
    • If using "two weeks" (or "biweekly"), also provide a value for Time step base.
    • Include this setting near the beginning of your import file, before any time series data.
  • Time step base — Date — The start date of any biweekly calendar period.
    • Required when using a biweekly Time step; ignored for other Time step settings.
    • Any date is supported, but most organizations with a biweekly calendar have periods starting on a Sunday. Pick any valid pay period and use its start date as the value of this setting.
    • Include this setting near the beginning of your import file, before any time series data.
  • Currency symbol — String — Sets the currency symbol displayed for all financial values in the budget.
    • Examples: "$", "€", "£".
    • This is for display purposes only. All financial values in a file should use the same currency. (Spendlab does not perform currency conversions.)
  • View start — Date — Sets the start date of the visible time range in the viewport. This is for display purposes only and does not affect the underlying data. By default, the viewport will expand if necessary to show all imported data.
  • View end — Date — Sets the end date of the visible time range in the viewport. This is for display purposes only and does not affect the underlying data. By default, the viewport will expand if necessary to show all imported data.

• All row types

  • Note — String (Time series optional) — Creates a sticky note in the budget with any text you provide. If you include a date in the Period Start column, the note will be an inline note anchored at that position along the timeline; otherwise, the note will appear on the row header.

• Funding sources

  • Total including indirects — Number (Time series) — Creates a funding installment for the specified budget period. The value represents the total amount including both direct and indirect costs.
    • Use Period Start and Period End to specify the budget period.
  • Total direct costs — Number (Time series) — You can optionally use this keyword instead of Total including indirects if the funding source doesn't have an indirect rate, or you don't want to track its indirect costs in Spendlab.
    • The Indirect rate for the funding source must be set to 0% or left undefined.
  • Balance including indirects — Number (Time series) — Records an actual balance at a specific point in time.
    • Use Period Start to specify the date of the balance entry.
  • Balance direct costs — Number (Time series) — You can optionally use this keyword instead of Balance including indirects if the funding source doesn't have an indirect rate, or you don't want to track its indirect costs in Spendlab.
    • The Indirect rate for the funding source must be set to 0% or left undefined.
  • Indirect rate — Percent or String — Sets the indirect rate for the funding source.
    • Percent value (e.g., "54.5%") — Sets a constant indirect rate for the funding source.
    • String value (e.g., "Federal indirect rate") — Links the indirect rate to a rate definition by name. This is useful when the indirect rate changes over time or is shared across multiple funding sources.
    • The keywords "none", "ignore", "n/a", "na", and "null" are equivalent to "0%".
  • Indirect rate definition — String — You can optionally use this keyword instead of Indirect rate to require that the value be a definition name.
  • Carry over balances — Boolean — Controls the carry-over behavior for the funding source.
    • Set to true (or yes) to carry remaining balances forward until the end date.
    • Set to false (or no) to reset the balance at each funding period boundary.
  • End date — Date — Sets the end date for the funding source, after which no further expenses can be charged.
  • Color — String — Sets the display color for the funding source. This affects visual appearance only.
    • Accepted values: "Blue", "Green", "Orange", "Purple", "Brown", "Light Blue", "Light Green", "Light Brown", "Light Purple", "Teal", "Light Teal", "Plum", "Pink".

• External funding sources

  Externally managed funding sources are used only for allocating effort in Spendlab. They have no configurable attributes.

• People

  • Salary — Number (Time series optional) — Sets the full-time equivalent salary for the person.
    • Provide a value in the Recurring Interval column to specify whether the value is per year, month, two weeks, or hour. (The default is year.)
    • If you provide dates in the Period Start and Period End columns, the salary will be set only during the specified time period. (A currency definition will be created if necessary to store this time series.)
  • Fringe rate — Percent (Time series optional) — Sets the fringe benefit rate for the person. The fringe amount is calculated by multiplying this rate by the salary.
    • If you provide dates in the Period Start and Period End columns, the fringe rate will be set only during the specified time period. (A rate definition will be created if necessary to store this time series.)
  • Other or Tuition — Number (Time series) — Sets the additional costs such as tuition for the person. Unlike Salary and Fringe rate, this is required to be a time series.
    • If a currency definition is not already linked to the person, a new one will be created to store this time series. The new definition's Add indirects attribute will be yes for Other and no for Tuition.
  • Salary definition — String — Links the person's salary to a currency definition by name. This allows the salary to change over time or be shared across multiple people.
  • Fringe rate definition — String — Links the person's fringe rate to a rate definition by name. This allows the fringe rate to change over time or be shared across multiple people.
  • Other definition or Tuition definition — String — Links additional costs such as tuition to a currency definition by name.
  • Rate — Percent (Time series) — Specifies the effort percentage for a work block during the specified time period. For example, 100% means full-time and 50% means half-time.
    • The default is 100%.
    • If you provide a value in the Funding Source column, the person's effort will be fully allocated to that source during the time period.
  • Hours — Number (Time series) — Sets the number of hours worked during the specified time period. This is used for hourly employment when the salary unit is set to "per hour".
    • If you provide a value in the Funding Source column, the person's effort will be fully allocated to that source during the time period.
  • Split — Percent (Time series) — Specifies how to split payment across multiple funding sources.
    • A value in the Funding Source column is required.
    • For a given time period, all splits should sum to 100%.

• Expense rows (Supplies, Equipment, Travel, etc.)

  • Total direct costs — Number (Time series) — Creates an expense block for the specified time period. The value represents the direct cost only, before any indirect costs are added.
  • Split — Percent (Time series) — Specifies how to split the expense across multiple funding sources.
    • A value in the Funding Source column is required.
    • For a given time period, all splits should sum to 100%.
  • Add indirects — Boolean — Controls whether the expense is exempted from indirect costs.
    • Set to yes (or true) to specify that indirect costs apply to this expense row.
    • Set to no (or false) to exempt the expense.
    • The default is yes, except for rows in the Equipment category (where the default is no).

• Currency definitions

  • Total direct costs — Number (Time series) — Creates a value block for the specified time period in the currency definition.
    • By default, definition blocks automatically repeat on a yearly interval if there are no future blocks defined. This allows you to add values for known time periods only, while still getting reasonable projections further into the future.
  • Yearly increase — Percent — Specifies an automatic yearly increase for auto-repeated values in the definition. For example, a value of 3% means each year's value will be 3% higher than the previous year.
  • Add indirects — Boolean — Controls whether the expense is exempted from indirect costs.
    • Set to yes (or true) to specify that indirect costs apply to this expense row.
    • Set to no (or false) to exempt the expense.
    • The default is yes, except for rows in the Equipment category (where the default is no).

• Rate definitions

  • Rate — Percent (Time series) — Creates a value block for the specified time period in the rate definition.
    • Rate values will automatically fill forwards and backwards into any time periods that are left undefined in your data import.

Compact Layouts

Spendlab supports alternative column types and layouts that can make data tables more compact and easier to use in spreadsheets.

• Date Headers

  Value, Period Start, and Period End columns can be replaced with date-labeled value columns. Each date header represents the Period Start for its column's values and the Period End for the previous date column (if any).

  Date headers with two time periods defined (January and February):

  Category	Name	Attribute	Funding source	2025-01-01	2025-02-01	2025-03-01
  People	Anna	Split	NIH grant	40%	50%
  People	Anna	Split	DOE grant	60%	50%
  People	Jose	Split	NIH grant	100%	100%

• Category Headers

  The Category and Name columns can be replaced with a single column with a header named for the category (e.g., People).

  People	Attribute	Value	Funding source	Period start	Period end
  Anna	Split	40%	NIH grant	2025-01-01	2025-02-01
  Anna	Split	60%	DOE grant	2025-01-01	2025-02-01
  Jose	Split	100%	NIH grant	2025-01-01	2025-02-01

• Attribute Headers

  The Attribute and Value columns can be replaced with a single column with a header named for the attribute (e.g., Split).

  People	Split	Funding source	Period start	Period end
  Anna	40%	NIH grant	2025-01-01	2025-02-01
  Anna	60%	DOE grant	2025-01-01	2025-02-01
  Jose	100%	NIH grant	2025-01-01	2025-02-01

  You can add multiple attribute columns to a table if all the attributes have shared context (such as Category, Name, and Period start/Period end).

• Omitted Columns

  Columns can be left blank or omitted completely if they are not applicable to the type of data being imported.

  Recurring Interval does not apply to percentage values, so it can be removed from this table.

  Category	Name	Attribute	Value	Funding source	Period start	Period end	Recurring Interval
  People	Anna	Split	40%	NIH grant	2025-01-01	2025-02-01
  People	Anna	Split	60%	DOE grant	2025-01-01	2025-02-01
  People	Jose	Split	100%	NIH grant	2025-01-01	2025-02-01

• These layout alternatives can be combined. For example, you can use both category headers and date headers in the same table for maximum compactness.

• Use hyphen rows if importing multiple tables together. If you import more than one table at a time, each table must be separated from other tables by a row that only contains one or more hyphens (or any dash-like character). See the templates for examples.

Missing Data

• You can import as much or as little data as you want, with any combination of layout options. The importer is designed to be flexible to handle common spreadsheet layouts and missing information.

• Automatic defaults: If relevant cells are left blank (or a whole column is omitted), the importer will fall back to Spendlab's default values.

  • Most defaults are zero ($0 or 0%). A notable exception is the default $60,000 salary for newly-created people rows.

  For example, if only the following information is provided for "Anna" (and there is not already a row for "Anna" in the target Spendlab file), then importing this table will create a new People row with the default salary ($60,000), fringe rate (0%), and other costs ($0).

  People	Split	Funding source	Period start	Period end
  Anna	100%	NIH grant	2025-01-01	2025-02-01

• Non-applicable columns can be left blank or omitted completely if they are not relevant to the type of data being imported.

  For example, funding source balance entries do not need a Period End, Recurring Interval, or Funding Source.

  Category	Name	Attribute	Value	Period Start	Period End	Recurring Interval	Funding Source
  Funding source	NIH grant	Balance including indirects	292,695	2025-01-01
  		Balance including indirects	243,695	2025-04-01

• Inferred Category and Name: If the Category or Name value(s) are left blank on a data row, the importer will use the nearest preceding non-blank value.

  Inferred Category and Name values make tables easier to navigate visually:

  Category	Name	Split	Funding source	Period start	Period end
  People	Anna	40%	NIH grant	2025-01-01	2025-02-01
  		60%	DOE grant	2025-01-01	2025-02-01
  	Jose	50%	NIH grant	2025-01-01	2025-02-01
  		50%	TA	2025-01-01	2025-02-01

Duplicate & Overlapping Data

• Data is imported sequentially, so later import lines override previous lines if they conflict.

  If the conflicting lines use time periods that only partially overlap, later imports will adjust the overlapping period (creating new blocks if necessary), and leave non-overlapping time periods unchanged.

  For example, importing these two rows:

  Category	Funding source	Total direct costs	Period start	Period end
  Supplies	NIH grant	$10,000	2025-01-01	2026-01-01
  Supplies	NIH grant	$892	2025-07-01	2025-08-01

  Results in three time blocks:

FAQ

• Can I re-import updated data? Yes. Imports are additive and designed for iteration.
• Can I undo a data import? Yes. Use the Undo button in the toolbar to revert any changes made by a data import. (Just as you would undo any other changes you make in Spendlab.)

Contact Us

• We welcome your questions and feedback! Email Lisa at .