BERdata 1.0.1.17 - Mac

INSTALL ONLY AFTER SYS DEV HAS PUBLISHED VERSION 1.0.1.17 TO THE BER SITE.
This folder is the installer; the add-in code itself loads from the hosted site.

1. Extract the whole Mac ZIP. Keep Install.command, Uninstall.command,
   manifest.xml, BERdata.xlsx and README.txt together.
2. Quit Excel completely with Command-Q.
3. Double-click Install.command. It opens a versioned starter workbook in Excel.
4. If macOS cannot verify Install.command or its developer, and you downloaded
   the package from BER: dismiss the warning, open System Settings > Privacy &
   Security, find the Install.command message, choose Open Anyway, then confirm
   Open. This allows that file only. If it says damaged or will damage your
   computer, stop and contact support instead.
5. Open BERdata Settings on the Home ribbon, save your BER API key and choose
   Test connection. In A1 enter =BERDATA.GETDATA("KBP7096B").
6. Save your own workbooks in your normal Documents/shared work folder.

The installer copies the manifest into
~/Library/Containers/com.microsoft.Excel/Data/Documents/wef/
as 1faa3c9e-9caf-4b88-a47e-8f83f462827e.manifest.xml. It opens the starter at
~/Library/Application Support/BERdata/BERdata-1.0.1.17.xlsx, creating it if absent.
Older starter workbooks and an existing edited 1.0.1.17 starter are not overwritten.
To repeat a clean check after registration, open BERdata.xlsx in this extracted
folder and save a copy in Documents. The workbook contains no macros.
The installer does not alter macro settings, certificate trust or global security.

Manual alternative: quit Excel, use Finder > Go > Go to Folder to open the wef
folder above (create it if absent), copy manifest.xml there under the ID-based
filename above, then open BERdata.xlsx. This avoids running Install.command.

UNINSTALL / REMOVE STALE BERDATA VERSIONS
Quit Excel, then double-click Uninstall.command. It removes the four known
BERdata manual registrations and only their ID-specific Office cache entries,
moving them into a recovery backup under
~/Library/Application Support/BERdata-removal-backup-* . It retains all your
workbooks, shared Office browser storage/API credentials and other add-ins.
To preview targets, run ./Uninstall.command -Preview from this folder in Terminal.
This does not remove a store/organisation-managed installation or edit embedded
add-in references in old workbooks. Keep the backup if you need targeted recovery.

Microsoft Mac instructions:
https://learn.microsoft.com/en-us/office/dev/add-ins/testing/sideload-an-office-add-in-on-mac
Apple's Open Anyway instructions:
https://support.apple.com/en-us/102445

FORMULAS AND DATES
  =BERDATA.GETDATA("P0141-CPS00000")
  =BERDATA.GETDATA("KBP6006D","1996-01-01")
  =BERDATA.GETDATA("KBP6006D","KBP6007D","1996-01-01")
  =BERDATA.GETVALUES("P3041.2-MPI30000",A10)

Use your own key for codes other than the TEST CPI demo. GETDATA accepts up to
20 unique series codes/ranges. Put the optional start date last; omit it for all
history. The cutoff is inclusive and dates use YYYY-MM-DD text or an Excel date.

With GETDATA in A1, rows 1-7 are Time series code, Description, Category, Unit,
Source, Frequency, Classification. Row 8 is blank; row 9 has Date/code headings;
observations start at A10. On supported Excel, dates are numeric and formatted
as yyyy-mm-dd (Excel may label the format Custom). Other values are not formatted.

GETVALUES: start beside the TOP metadata row (for example D1), and click the
first observation date in GETDATA as the final argument (A10 in this example).
It matches values to the exact existing dates and retains their row positions:
- Same frequency: matching observations, with blanks for missing dates.
- Lower frequency on a higher-frequency table: values on matching dates only;
  other dates stay blank. No interpolation, aggregation or forward filling.
- Higher frequency on a lower-frequency table: #VALUE! in the formula cell and
  "Build your table with the higher frequency first." immediately below it.
The message needs one empty cell below the formula. Other validation errors
remain Excel errors. If several series are requested, all must fit the base grid.

A typed start date or no date can use a single GETDATA table to the left on the
same formula row. With more than one candidate table, click a date cell to choose.
A later requested start date leaves earlier base rows blank to preserve alignment.
Old date-first GETVALUES inputs remain recognised; the recommended syntax is
codes first and the date cell last. Unknown/irregular frequencies are not guessed.
Dates/frequency changes in the base table trigger a linked refresh after Excel
finishes calculating. Browser preview fetches data but cannot check worksheet links.
Use GETDATA to build a whole table; use GETVALUES when adding to an existing one.

Current Microsoft 365 desktop Excel is recommended. Table matching needs
ExcelApi 1.12 and CustomFunctionsRuntime 1.3. Numeric rich dates need ExcelApi
1.16+; earlier supported clients retain ISO text dates. Standard 1900 date system
only; legacy 1904 workbooks still need a separate compatibility check.

SWITCHING FROM TEST VERSIONS
Only one installed add-in may own BERDATA formula names. Remove BERdata Local
Test or the Netlify beta before installing this BER-hosted release. Both can
use BERDATA under different add-in IDs. Older BERDATATEST workbooks need their
formulas changed to BERDATA in a saved copy, followed by a check of the results.
Opening old workbooks can bring back their embedded add-in references; use the
new starter workbook for the first check and retain your old workbook copies.

DATA HANDLING AND REQUIREMENTS
Use supported desktop Excel (Microsoft 365 recommended), internet access and
your own BER API key. No Node.js, local server, development certificate, Copilot
subscription or administrator elevation is requested. Organisation policy may
still block manual add-ins/scripts; ask IT rather than disabling protections.

No key is embedded in these files. Excel saves your key in OfficeRuntime shared
storage until you choose Clear saved key. Browser preview uses separate tab
storage. Requests send the key and series codes over HTTPS through BER's relay
at excel.beranalytics.co.za/api/getdata to api.beranalytics.co.za. BER's API
supports usage logging. This version does not route requests through Netlify.

This is manual team distribution, not Microsoft store certification. IT-managed
or store installations need to be removed through their own distribution route.

Local preview BERLOCAL formulas belong to a separate test add-in. For a clean
production check, quit Excel and remove that preview with its own uninstaller.
Save a copy of test workbooks before replacing BERLOCAL. with BERDATA. in formulas.
The production key is saved separately; save your key in BERdata Settings again.

Site: https://excel.beranalytics.co.za/
Manifest: https://excel.beranalytics.co.za/manifest.xml
Help: https://excel.beranalytics.co.za/help.html
Version: 1.0.1.17
Add-in ID: 1faa3c9e-9caf-4b88-a47e-8f83f462827e
Name / ribbon: BERdata / BERdata Settings

First use: TEST is the default public demo key. It returns up to 10 CPI observations
for =BERDATA.GETDATA("P0141-CPS00000"). Save your own API key for other series.
