Software Documentation

Software Documentation

Inventory and Effect ManagementDocumentation

Intermediate Last updated: April 2, 2024

2 Importing inventory from a file

You can import a new inventory file or convert your inventory from our old software Finale Business by doing Option A, B, or C, and then right clicking on the imported items in the effects window and doing “Edit this effect simulation or rack” from the context menu to fix up the simulations one by one.   To see a preview of a simulation, hover the cursor over the white border of the black effect icon

Option A) If you want to convert your My Fireworks from Finale Business to Finale 3D, then please create a show in Finale Business containing one of each effect from your My Fireworks, spaced out one at a time with a few seconds in between each effect.  Save the show as an HBS file, launch Finale 3D, and do the menu item, “File > Import > Import Effects from HBS file…”

Option B) If you already have a Finale Inventory / Master Inventory account, then you don’t need to re-import it.  You can just connect to it with the menu item, “File > Finale Inventory > Configure Finale Inventory connection” or the web page “finale3d.com > My Account > Connect to Finale Inventory”.

Option C) If you have a list of products from your own inventory or a price list from a supplier in an Excel file or a CSV/TEXT file, or in the inventory file format from other major scripting software (EFX, MDB), you can import the list into Finale 3D to use those products for scripting shows.  Finale 3D will create simulations for the effects automatically from the descriptions and other information in your product list file, even if the descriptions are in a non-English language.

For Option A and Option B, that’s all there is to it.  You don’t need to read any further.  For Option C, there are additional details.  The rest of this article covers these details and provides a technical explanations of what is going on.

The detailed steps for Option C are:

  1. Prepare the inventory file to import.   You need to convert the file to a format that Finale 3D can import.  If your original file happens to be an EFX file from Show Director or MDB effect database from ScriptMaker, then the file is okay as is; skip to the next step.  Otherwise please import your file into Excel and edit the file so that it has a single header row with only the supported fields and one data row per item.  From Excel, export the file in “Unicode Text (*.txt)” format, which produces the file that can be imported into Finale 3D.  Please refer to the import template Excel file at the bottom of this page for the list of supported fields.   Finale 3D supports importing inventory files in the TXT or CSV formats with comma or tab delimiters, encoded as ASCII, UTF-8, or UTF-16; but the “Unicode Text (*.txt)” option from Excel is the most reliable.  If your Excel file contains any line breaks or tab characters embedded in cell text, you need to remove them before exporting the CSV or TXT file.  The easiest way is to create a second sheet in Excel that references the original sheet with the Excel formula =CLEAN() for each cell, and then copy/paste the clean sheet using “Paste special > Values”.
  2. Import the file.  Launch Finale 3D.  Do “File > Import > Import effects file…” then choose the location for the effects. The most common locations for importing are “My effects” or an effect database file (FDB file).  Upon import, Finale 3D will examine the file and present a dialog telling you how many products it contains, and indicating if any column headers were mis-labelled.  You also will have the option to select the units of measure for duration and prefire explicitly, or leave Finale 3D to guess based on the values (it usually guesses correctly).  Click okay to import the file.
  3. Save the inventory file.  Once you are satisfied with the imported file, you will need to save the imported effects.  The steps to save depend on the location you chose to import your effects.  If you imported into your online “My effects” collection, then save by going to “File > Sync with network” to upload your effects to the cloud.  If you imported your effects into an exiting FDB effects file, or created a new FDB effects file with the imported effects, then save by going to “File > Effects files > Save (fdb format)”.  The FDB file is saved locally on your computer, you can copy, email, or transfer to other computers to share it or create backups.
  4. Optionally copy to your Finale Inventory account.  If you are using the Finale Inventory web-based inventory management software (www.finaleinventory.com) or if you have a Master Inventory from Finale Business, then you can copy the effects to your account as by simply selecting the rows to copy, then Ctrl+C, then switching to your Finale Inventory account from the blue selector in the upper right of the effect window, then Ctrl+V to paste.  If your Finale Inventory account doesn’t appear in the blue selector’s context menu, then you need to configure Finale 3D for your inventory account by going to “File > Finale Inventory > Configure Finale Inventory connection”.

Step (1) mentions “fixing” the format of your product list or inventory file or making the column headers match “what Finale 3D expects”.  The basic idea is that if you make your CSV file match the column headers displayed at the top of the effects window, then those columns of data will be imported from your file into the “matching” columns in the window.  The full explanation is a little more complicated because Finale 3D relies on some columns of data that your imported file may not include, such as the Duration column, the Height Meters column, and the Type column. When you import your file, Finale 3D will calculate default values for these properties of the columns are not in your file or if the cells are blank in of the effects in the file.  Thus, even though these columns are required in the effects window, it is okay if your original imported file does not contain them.

So what columns do you actually need, and what columns are optional?  At a minimum, you need these two columns in your imported file:

Table 1 – Required columns for imported inventory files

Part Number The unique identifier for the effect, like P10001 or 3LD253CK.
Description A description of the effect, like “30mm Red Peony” or “Bomba Roja Con Aro Azul” or “Синяя в красную хризантему”.

Based on this information alone, Finale 3D can fill in the other columns, like Size (extracted from the Description field if present) and Duration and Height.  Finale 3D uses machine translation algorithms to translate the description from the original language into a standard pyrotechnics terminology called VDL (Visual Description Language), which consists of approximately 300 mostly English words.  After importing your file, the VDL column in the effects window shows the translation.

Usually, imported inventory files contain more than just the two columns in Table 1.  It is very common for the inventory file to contain its own Size column or Duration column, for example, as well as other properties like Price or Category.  To import these other columns, just make your column header match the Finale 3D column header in the effect window, exactly. For example, the Finale 3D column header for height is actually “Height Meters” so please make your column header be exactly “Height Meters”, not just “Height”.  You can unhide all the columns in the effects window from the gear menu on the right. By default, most of the columns are hidden.

The column headers in Finale 3D may change depending on what language setting you are using.  If you match the column headers that you are looking at, exactly, the import process will work.  But if you want the import process not to depend on the language setting, you can also change the column headers in the file that you are importing the Finale 3D’s Internal Column Name, which is an English word or phrase with no spaces.  The full list of possible columns, along with their Internal Column Names and explanations, is shown in Table 2.

Table 2 – Full list of columns that can be imported

Column Name Internal Column Name Explanation
Part Number partNumber The unique identifier for the effect, like CF10001 or 3LD253CK. This field is called the “Product ID” in Finale Inventory.
Description description A description of the effect, like “30mm Red Peony 75m” or “Bomba Roja Con Aro Azul” or “Синяя в красную хризантему”.  The description can be in any language, and can contain the size and height if that information is not in other columns. This field has a counterpart in Finale Inventory (Description).
Type partType One of these predefined English terms (exactly): cake, candle, single_shot, shell, ground, rocket, mine, comet, flame, other_effect, not_an_effect, rack, sfx, or light.  If the “Type” column is not present in the imported file or if the field is blank, Finale 3D will guess the type based on the description. The counterpart for this field in Finale Inventory is the “Choreography Tab”; and (regrettably) the counterpart in Finale Business and Finale Generic CSV is the “Category” field.  To handle these naming discrepancies, if the Type column is missing in the imported file and a Category or Choreography Tab column is present, the Category or Choreography Tab column will be imported as the Category.  If you are using Finale Inventory, please note: Finale Inventory’s Choreography Tab values are slightly different from Finale 3D’s Type values. When 3D connects to Finale Inventory, it translates between the names automatically. The corresponding names in Finale Inventory are Cakes, Candles, Single Shot, Shells, Ground, Rocket, Mines, Comets, Flame, Other, Not An Effect, Rack, Sfx, and Light. The special value Non-Choreographed in Finale Inventory causes the item not to be downloaded to 3D.  Please see Why is ‘Type’ so important? for an explanation of why this field is so important.
Size size The caliber of the effect, in inches or millimeters, e.g., 3” or 75mm.  This field determines the size of the visual simulation. If the Size column is not present in the imported file or if the field is blank, Finale 3D will extract the size from the Description field, if present.  This field has a counterpart in Finale Inventory (Caliber).
Prefire internalDelay The lift time, for shells, or the lift time of the first effect of a cake if it is a shell. This field is not the visco fuse delay on a cake. This field applies to the visual simulation.  If the column or field is not present in the imported file, Finale 3D will calculate a good default value based on the size and description.  Please see Cake and candle duration (and prefire). It is easiest to leave this field blank or zero for cakes and candles because the automatic default values are good.  This field has a counterpart in Finale Inventory (Prefire Time). Please see the compatibility notes below if you are importing a Finale Inventory and need to maintain compatibility with Finale Business.
Duration duration The lifetime of the stars, for aerial shells, or the duration of the continuous effect for gerbs or flares, or the duration from first launch to last break for cakes.  This field applies to the visual simulation. If the column or field is not present in the imported file, Finale 3D will calculate a good default value based on the size and description.  Please see Cake and candle duration (and prefire). This field has a counterpart in Finale Inventory (Duration).
Height Meters height The height in meters of the trajectory apex of an aerial shell, or of the spark plume for fountains and gerbs. This field determines the height of the visual simulation.  If the column or field is not present in the imported file, Finale 3D will calculate a good default value based on the size and description. This field has a counterpart in Finale Inventory (Effect Height).
Color color A user-defined field for the user’s convenience in searching or filtering the rows in the effect window. If the column or field is not present in the imported file, Finale 3D will extract colors from the description. This field has a counterpart in Finale Inventory (Effect Color).
Subtype subtype Like Color, Subtype is a user-defined field for the user’s convenience. If the column or field is not present in the imported file, Finale 3D will extract subtypes from the description. This field has a counterpart in Finale Inventory (Effect Subtype).
VDL vdl The description of the effect in standard pyrotechnics terminology (Visual Description Language). If the column or field is not present in the imported file, Finale 3D will calculate a good default value based on the description.  This field defines the visual simulation of the effect, along with a few other specifications like Size, Height Meters, and Duration. This field has a counterpart in Finale Inventory (VDL Description). Please see the compatibility notes below if you are importing a Finale Inventory and need to maintain compatibility with Finale Business.
Manufacturer Part Number manufacturerPartNumber This optional part number is available for your own convenience, and also to facilitate updating the VDL in your own effects files or Finale Inventory account by cross-referencing manufacturer effects lists with up-to-date VDL maintained and approved by the manufacturer. This field has a counterpart in Finale Inventory (Mfg Product Id).
Manufacturer manufacturer A user-defined field for the user’s convenience in searching or filtering the rows in the effect window. This field has a counterpart in Finale Inventory (Manufacturer).
Price stdPrice The price per-device of the item.  Finale 3D will display the price of a show based on these values in the lower right of the simulation view, and in the timeline if you select a time range of effects.  This field has an “Item Price” counterpart in Finale Inventory.
Storage Location stdLocation An optional fixed stock location for the effect in the picking facility or warehouse, such as a bin number.  This field can be used as a sort criterion in reports and labels. This field has a counterpart in Finale Inventory: Std Bin ID.
Hazard Default lockoutDefault An identifier used by various firing systems and exported in the firing system scripts for those systems, which allows the show operator to disable a section of the show based on real time conditions.  Since the hazard value may depend on an item’s placement in the shoot size, the value in the effect list is the “Default” value that is copied to the script when the item is inserted into the script. The user can subsequently change the value in the script, but since the value was copied and is not a reference, changing the value in the effect window will not affect existing effects in the show. This field has a counterpart in Finale Inventory (Hazard Default.  
Tubes numTubes This term applies to racks, not effects.  It is the number of tubes in the rack. This field has a counterpart in Finale Inventory (Rack Tubes).
Category category A user-defined field for the user’s convenience in searching or filtering the rows in the effect window.  Unlike the Type field, the category can be anything the user wants. This field is has an exact counterpart in Finale Inventory, by the same name, and is used for stock reports and and DSMT reports for stock management.  However, in Finale Inventory the field can only contain specific, pre-defined enumerated values.  As of Jan 17, 2020, this field is synchronized from Finale Inventory to Finale 3D but not in the other direction. 
Custom Part Field customPartField A user-defined field for the user’s convenience. This field has a counterpart in Finale Inventory (Custom Part Field).
Rack Type Default rackType This term applies both to racks and to effects.  It is a user-defined matching criterion between racks and the effects that are compatible with the racks.  For example, if the user has two types of single-shot racks for different caliber ranges, the user could assign LargeSS and SmallSS rack types to the effects and racks to cause them to match correctly.  Like Hazard Default, this field is copied to the script events when they are inserted into the show, not referenced, so you can change values of the items in the script according to circumstance (e.g., putting a fan of effects into a wagonwheel rack specifically even though other racks are also compatible).  Since the value is copied and is not a reference, changing the value in the effect window will not affect existing effects in the show. This field has a counterpart in Finale Inventory (Rack Type Default).
Notes partNotes A user-defined field for the user’s convenience.  This field is sometimes used in report, but other times the script notes field is used in the reports instead, depending on whether the notes apply intrinsically to the effect or apply contextually to the usage of the effect in the show. This field has a counterpart in Finale Inventory (Notes).
DMX Patch dmxPatch This field holds a small program or “patch” for controlling the DMX values associated with a special effect like a flame projector or moving stage light. This field has a counterpart in Finale Inventory (DMX Patch).
EX Number exNumber A field for the user’s convenience. This field is has an exact counterpart in Finale Inventory (EX Number) and is used in Finale Inventory for shipping documents.  This list can include a single EX number, or a comma separated list. As of Jan 17, 2020, this field is synchronized from Finale Inventory to Finale 3D but not in the other direction.
CE Number ceNumber A field for the user’s convenience. This field is has an exact counterpart in Finale Inventory (CE Number) and is used in Finale Inventory for shipping documents. As of Jan 17, 2020, this field is synchronized from Finale Inventory to Finale 3D but not in the other direction.
UN Number unNumber A field for the user’s convenience. This field is has an exact counterpart in Finale Inventory (Hazardous Material) and is used in Finale Inventory for shipping documents. This number must be in the format: UNXXXX, where XXXX is a four digit number like 0336 or 0337.  Example: UN0337. As of Jan 17, 2020, this field is synchronized from Finale Inventory to Finale 3D but not in the other direction.
Cost stdCost A field for the user’s convenience.  This field can be used in reports. This field has a “Standard Accounting Cost” counterpart in Finale Inventory.
Safety Distance Meters safetyDistance A field for the user’s convenience.  It may also be used by site layout safety report features in Finale 3D available in the future.  This field has a counterpart in Finale Inventory (Safety Distance).
Fuse Delay fuseDelay The visco fuse delay between the ignition of the device’s fuse and the first launch.  When an effect is inserted into the show, the fuse delay is copied to the the Delay field in the script.  Since the value is copied, not referenced, subsequent changes to the fuse delay in the effect window will not affect existing effects in the show.  This field has a counterpart in Finale Inventory (Fuse Delay).
Devices numDevices The number of devices in the chain, or 1 if the item is not a chain. This field has a counterpart in Finale Inventory (Chain Number Of Devices).
Available available The number of devices on hand in the stock facilities at any of the selected locations, minus those reserved for sales orders (shows), plus those on order but not yet received from suppliers.  Use the menu item “File > Finale Inventory > Selected locations” to choose what facility locations apply.
Weight weight The weight of one device (shell, cake, etc.). The “Basic Product List” report and other similar reports in Finale 3D will show the total weight for all items in the show.
NEQ neq The net explosive quantity of one device (shell, cake, etc.).  The “Basic Product List” report and other similar reports in Finale 3D will show the total NEQ for all items in the show.

The effects window also displays some special columns that are not intrinsic properties of the products.  These special columns, shown in Table 3, cannot be imported as part of the import inventory process.

Table 3 – Quantity columns  that cannot be imported as part of importing inventory

Column Name Internal Column Name Explanation
Used used A dynamic count of the number of devices used in the show.
Quota quota A static count of the number of devices allocated by the designer for use in the show.  The quotas can be imported with the menu item, “File > Import quotas”. Though the quota appears as a column in any collection selected into the effect window (Per-show effects, Generic effects, your Finale Inventory account, etc.), the values are actually stored in the quota column in the Per-show effects, and are therefore associated with and saved along with the show to which they apply.
On Hand qoh The number of devices on hand  in the stock facilities at any of the selected locations (use the menu item “File > Finale Inventory > Select locations” to choose what facility locations apply).
Remaining Quota remainingQuota The calculated value: Quota – Used.  This field can be used as a filter condition.  Please explore the table layout blueprints available in the effects window from the gear menu.
Remaining On Hand remainingQoh The calculated value: OnHand – Used.  This field can be used as a filter condition.  Please explore the table layout blueprints available in the effects window from the gear menu.
Remaining Available remainingAvailable The calculated value: Available – Used.  This field can be used as a filter condition.  Please explore the table layout blueprints available in the effects window from the gear menu.

 

If you are importing or modifying a Finale Inventory to use with Finale 3D while maintaining backward compatibility with Finale Business, you will need to give special consideration to three fields: Prefire, Type, and VDL.

  1. Prefire.  Finale Business and Finale 3D interpret the term “prefire” for aerial cakes differently, and action is required on your part to change the prefires in your inventory to a value that works for both.  The table below shows the options, but the best solution is: change the prefires of aerial cakes to blank.  The default prefire for cakes in Business is 0.3 seconds.  Unfortunately this value causes aerial cake shells in Finale 3D to break at 0.3 seconds on the way up, looking like a geyser or flowerpot.  Please change the value to blank, or one of the other good values in the table below. Please see Cake and candle duration (and prefire)
  2. Type.  Finale 3D and Finale Inventory support all the values of Finale Business, and a few more.  Thus if the Type values in your inventory are from Business, they’ll work fine in 3D.  But if you change them to values other than Cakes, Candles, Shells, Mines, Comets, Other, or Non-Choreographed, then they will no longer work in Business. (Type is called “Choreography Tab” in Inventory, and “Category” in Business.) Please see Why is ‘Type’ so important?.
  3. VDL. Finale 3D and Business both support VDL effect descriptions for simulations, but Business requires a strict form of VDL.  If you type or import VDL into Finale Inventory directly, it most likely will not work for Business because it will not be in the strict form (e.g., case-sensitive).  If you need backward compatible VDL then please copy/paste the VDL field from 3D after creating or editing the simulation via the dialog, which puts it into the strict form.

Table 4 shows four possible prefire values for a 3” aerial cake, and indicates whether the result is good or bad in Business and 3D.  You can see that 0.3 is bad, but the three other possibilities — blank, 0.0, and the lift time of the first aerial shell in the cake — are all good.  There are slight differences, but the blank value is the best choice because it works exactly the same way as 0.3 in Business, and it also works 3D, and it is simple.

Table 4Finale 3D/Business compatibility matrix for prefires of aerial cakes like “10 Shot 5s Red Peony Cake”

Prefire Finale Business Finale 3D
0.3 (GOOD) First launch at 0.0s; timeline blip at 0.3s; break at 2.8s (BAD) First launch at 0.0s; timeline blip at 0.3s; break at 0.3s (looks like a geyser)
(blank) (GOOD) Same as 0.3 (GOOD) First launch at 0.0s; timeline blip at 3.02s; break at 3.02s
0.0 (GOOD) Same as 2.8 (GOOD) First launch at 0.0s; timeline blip at 3.02s; break at 3.02s
2.8 (the default lift time for 3” shell in Finale Business) (GOOD) First launch at 0.0s; timeline blip at 0.3s; break at 2.8s (GOOD) First launch at 0.0s; timeline blip at 2.8s; break at 2.8s (a little early)

 

Table 5 – Template files

Download link Explanation
import_inventory_to_finale_3d_template.xlsx Template for importing into 3D (Excel)
import_inventory_to_finale_3d_template.txt Template for importing into 3D (UTF-16 text, saved from Excel)