Metadata-Version: 2.4
Name: NEMO-bulk-upload
Version: 1.1.0
Summary: Plugin for NEMO that lets staff bulk-create records from Excel or CSV using friendly names, with Check for errors before Create records.
Author-email: Alex Denton <alexdenton998@gmail.com>
License: # NIST Software Licensing Statement
        NIST-developed software is provided by NIST as a public service. You may use, copy, and distribute copies of the software in any medium, provided that you keep intact this entire notice. You may improve, modify, and create derivative works of the software or any portion of the software, and you may copy and distribute such modifications or works. Modified works should carry a notice stating that you changed the software and should note the date and nature of any such change. Please explicitly acknowledge the National Institute of Standards and Technology as the source of the software.
        
        NIST-developed software is expressly provided "AS IS." NIST MAKES NO WARRANTY OF ANY KIND, EXPRESS, IMPLIED, IN FACT, OR ARISING BY OPERATION OF LAW, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR WARRANTS THAT THE OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY, RELIABILITY, OR USEFULNESS OF THE SOFTWARE.
        
        You are solely responsible for determining the appropriateness of using and distributing the software and you assume all risks associated with its use, including but not limited to the risks and costs of program errors, compliance with applicable laws, damage to or loss of data, programs or equipment, and the unavailability or interruption of operation. This software is not intended to be used in any situation where a failure could cause risk of injury or damage to property. The software developed by NIST employees is not subject to copyright protection within the United States.
        
Project-URL: Homepage, https://github.com/alexanderenrique/NEMO-bulk-upload
Project-URL: Issues, https://github.com/alexanderenrique/NEMO-bulk-upload/issues
Keywords: NEMO,bulk-upload,spreadsheet,billing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: License :: Public Domain
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Framework :: Django :: 4.2
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: django
Requires-Dist: openpyxl
Provides-Extra: nemo-ce
Requires-Dist: NEMO-CE>=7.3.0; extra == "nemo-ce"
Provides-Extra: nemo
Requires-Dist: NEMO>=7.3.0; extra == "nemo"
Provides-Extra: nemo-billing
Requires-Dist: NEMO-billing; extra == "nemo-billing"
Provides-Extra: dev-tools
Requires-Dist: pre-commit; extra == "dev-tools"
Requires-Dist: djlint; extra == "dev-tools"
Requires-Dist: black; extra == "dev-tools"
Dynamic: license-file

# NEMO Bulk Upload

[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

Plugin for [NEMO](https://github.com/usnistgov/NEMO) (and NEMO-CE) that lets billing staff and facility managers **bulk-create records from Excel or CSV** using friendly names (not IDs). Staff pick a record type, drop a spreadsheet, click **Check for errors**, fix anything red, then click **Create records**.

Requires **NEMO or NEMO-CE ≥ 7.3.0** and **Python ≥ 3.10**.

## Features (v1.1)

- **Tool usage** (`UsageEvent`) uploads: username, tool name, project / PTA, start, end, note.
- **Billing rates** (`NEMO_billing.rates.Rate`) uploads when [NEMO-billing](https://pypi.org/project/NEMO-billing/) is installed: rate type, item, category, amount, effective date (for annual FY changes). Creates new dated rates; does not overwrite older ones.
- Header aliases (`User` → Username, `Tool` → Tool name / Item, `Project` / `PTA` → Project / PTA).
- First sheet of an `.xlsx` is used (no need to rename it to "Data").
- Extra columns are **warned and ignored** (e.g. display Name, Charge check).
- Missing or blank **Project / PTA** defaults to the user's **first active project**, with a warning that names the PTA.
- Datetimes accept ISO text (`2026-08-10 15:30:00`), Excel serials, and site `DATETIME_INPUT_FORMATS`.
- Create stays locked until the current file passes Check with zero errors (warnings are OK).
- Create-only: an `id` column is rejected.
- Optional Excel / CSV template download and **Download errors** spreadsheet.

## Install

```bash
pip install NEMO-bulk-upload
# or in Docker: NEMO_EXTRA_PIP_PACKAGES="NEMO-bulk-upload"
```

In site `settings.py`, list the plugin **before** `NEMO` so the navbar override wins:

```python
INSTALLED_APPS = [
    "NEMO_bulk_upload.apps.BulkUploadConfig",  # before NEMO
    "NEMO",
    ...
]
```

Then:

```bash
python manage.py migrate bulk_upload
```

### Optional: billing rates

To enable **Billing rates** on the picker, install NEMO-billing and add its apps **before** `NEMO`:

```bash
pip install NEMO-billing
```

```python
INSTALLED_APPS = [
    "NEMO_bulk_upload.apps.BulkUploadConfig",
    "NEMO_billing",
    "NEMO_billing.rates",
    # "NEMO_billing.invoices",  # optional
    "NEMO",
    ...
]
```

Without billing installed, only **Tool usage** appears (same as v1.0).

### Permissions

Grant on the user or group (Detailed Admin → Users / Groups):

- `bulk_upload | Can use bulk upload` — open the page and run Check / Create
- `NEMO | Can add usage event` — required to Create tool usage rows
- `rates | Can add rate` — required to Create billing rate rows (when NEMO-billing is installed)

### Landing page icon

Detailed Admin → Landing page choices → add an entry with URL `/bulk_upload/` and a 128×128 image.

### Navbar

When the plugin is installed before `NEMO`, **Bulk upload** appears under Administration for users with `use_bulk_upload`.

## Usage

### Tool usage

1. Open **Bulk upload** (`/bulk_upload/`).
2. Choose **Tool usage**.
3. Optionally download the Excel template (or keep using your existing workbook).
4. Drop `.xlsx` or `.csv` and click **Check for errors**.
5. Review warnings (extra columns, defaulted PTAs) and fix any red cells in Excel, then drop again.
6. When Check passes, click **Create records** and confirm.

### Billing rates (annual FY change)

One spreadsheet row creates one new `Rate` with an **Effective date**. Older rates for earlier dates stay in place for historical invoices.

| Column | Required? | Notes |
|--------|-----------|--------|
| Rate type | Yes | `Tool usage`, `TOOL_USAGE`, `Consumable/Supply`, `Staff charge`, … |
| Item | When type is item-specific | Tool, area, or consumable name (`Tool` / `Area` / `Consumable` aliases OK) |
| Category | When type is category-specific | e.g. Local, Industry |
| Amount | Yes | `55`, `55.00`, or `$55` |
| Effective date | Yes | e.g. `2026-09-01` or `9/1/2026` |
| Flat / Daily / Schedule / Minimum charge / Service fee | No | |

Example:

```csv
Rate type,Item,Category,Amount,Effective date,Flat
Tool usage,AIX200,Local,55.00,2026-09-01,No
Tool usage,AIX200,Industry,150.00,2026-09-01,No
Consumable/Supply,Acetone,,33.00,2026-09-01,Yes
```

Staff charge rates leave **Item** blank. Consumable rates must be **Flat = Yes**.

## Development

```bash
./scripts/dev_reinstall.sh -n /path/to/nemo-ce
python run_tests.py
```

Rate tests are skipped automatically if `NEMO_billing.rates` is not in `INSTALLED_APPS`.

## License

NIST public-domain statement (see `LICENSE`).
