> ## Documentation Index
> Fetch the complete documentation index at: https://nectarclimate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Sphera
> Sphera integration for integrated sustainability and risk management.
Need help in this area? See [Data Export FAQ](/docs/platform/data-export/faq).
The Sphera integration connects Nectar to SpheraCloud Corporate Sustainability. Nectar pushes per-bill utility data into Sphera and reads stored values back to compare them against your Nectar data month by month.
Setup takes two passes: collect credentials in SpheraCloud, then paste them into Nectar's setup wizard.
## Channels
Sphera exchanges data over **channels**. Nectar uses two, and each has its own GUID, connection key, and connection secret.
| Channel | Type in Sphera | What Nectar uses it for | Required? |
| ------------------------- | ------------------ | -------------------------------------------------------------------------------- | ----------- |
| **Data Import (DI)** | `Data Import` | Pushing bill-level utility data into Sphera | Required |
| **Data Acquisition (DA)** | `Data Acquisition` | Reading values back for the monthly comparison and discovering your Sphera sites | Recommended |
You can run the integration with DI alone. Without DA, you lose site discovery, the monthly usage comparison, and the Push/Sync resolution actions.
You need a SpheraCloud user with access to **Management > Connection Center**. If that menu item is not visible, ask your Sphera administrator to grant Connection Center permissions, or to create the channels and send you the values.
## Step 1: Get your Sphera credentials
Sign in to SpheraCloud at your company host (for example `https://yourcompany.cs.spheracloud.net`) and confirm the product switcher is on **Corporate Sustainability**. In the left navigation, expand **Management** and click **Connection Center**, then expand the **Channels** section.
The Channels table lists every channel with its **Type**, **Name**, **Online** checkbox, and **Auth Type**. Nectar uses `WSSE`, which is Sphera's default.
Look for a row where **Type** is `Data Import`. If your administrator already created one for Nectar, open it and skip to the next step.
To create one, click the **+** dropdown at the top right, choose **New Channel**, and set:
* **Type** — **Data Import**
* **Name** — anything recognizable, for example `Nectar upload channel`
* **Online** — leave checked. An unchecked channel rejects incoming data.
* **Save on behalf of** — a Sphera user with write access to every site Nectar will push to. Imported data is written under that user's permissions.
* **Mapping** — the Sphera import mapping that matches Nectar's CSV column names. Create it under **Mappings** first if none exists.
* **Transformer** — leave blank. Nectar sends a flat CSV that needs no transposition.
**Mapping** is required on Data Import channels. A mismatch between the mapping's expected columns and Nectar's CSV headers is the most common cause of failed imports — see [Column names](#column-names).
Repeat for a row where **Type** is `Data Acquisition`. This channel is read-only, so it has no **Mapping** or **Transformer** field. Set **Save on behalf of** to a user who can *read* the sites and questionnaire data you want to compare.
Open a channel to show its detail panel. At the top of the **Info** tab is a bordered box labelled *"Click to copy connection parameters to send them to the sending system."* Click it once to copy the whole block:
```
Endpoint:
https://yourcompany.cs.spheracloud.net/api/di
Full URL (with channel UUID):
https://yourcompany.cs.spheracloud.net/api/di/00000000-0000-0000-0000-000000000000
Connection key:
<32-character hex string>
Connection secret:
<64-character hex string>
```
The same values are listed individually further down the Info tab as **URL**, **Endpoint URL**, **Connection key**, and **Connection secret**.
Do the DI channel and the DA channel separately. Their GUIDs, keys, and secrets are all different, and the endpoint path differs (`/api/di` vs `/api/da`). Pasting DI credentials into the DA fields is the most common setup mistake — the connection test fails with an authentication error.
### Map Sphera values to Nectar fields
| Sphera value | Nectar field | Notes |
| --------------------------------- | --------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Last path segment of **Full URL** | **Channel GUID** | The UUID after `/api/di/` or `/api/da/` |
| **Endpoint** host | **Sphera host** | For example `yourcompany.cs.spheracloud.net` — no `https://`, no trailing path |
| **Endpoint** path | **API route** | `api` on most SpheraCloud instances; `ws/rest.php` on self-hosted installations. Nectar appends `/di` and `/da`. |
| **Connection key** | **Connection key** | 32-character hex string |
| **Connection secret** | **Connection secret** | 64-character hex string |
## Step 2: Connect Nectar to Sphera
Go to [**Data Export > Integrations > Sphera**](https://dash.nectarclimate.com/data-export/integrations/sphera) and start the setup wizard. If the integration already exists, edit it from [**Settings > Company > Integrations > Sphera**](https://dash.nectarclimate.com/settings/company/integrations/sphera) instead.
1. **Channels** — Enter your Sphera host and API route, and turn on the **Data Acquisition (DA) channel** toggle if you have one.
2. **Credentials** — Paste the GUID, connection key, and connection secret for each channel. **Verify & continue** tests every channel against the live Sphera API, saves the configuration, and discovers your Sphera sites through the DA channel. Site discovery can take a minute.
3. **Site mapping** — Match each Nectar [site](/docs/platform/glossary#site) to its Sphera site. **Smart match** suggests pairings by name, and you can exclude sites you never want pushed. On the same step, pick the Sphera **questionnaire template** that holds each commodity's data — Nectar pre-fills these from the discovered template names.
4. **Review** — Confirm the host, channels, mapped and excluded site counts, and configured commodities, then **Finish setup**.
Steps 3 and 4 need the DA channel. With DI alone you can skip site mapping — the push export still works, but Nectar cannot read values back.
## Integration hub
The Sphera integration page at [**Data Export > Integrations > Sphera**](https://dash.nectarclimate.com/data-export/integrations/sphera) is a single-page layout:
* **Page header** — **Archive** (deactivate the integration) and **Settings** (credentials, site mapping, questionnaires, column names)
* **Warning banners** — Legacy push-only configuration, or sites not yet mapped to a Sphera site
* **Status card** — **DI + DA connected**, **DI only (push)**, **Legacy config (push only)**, or **Not configured**, with an **Export** button
* **Recent syncs & downloads** — Your latest Sphera exports and DI pushes. Use [**Data Export > History**](https://dash.nectarclimate.com/data-export/history) for the full cross-integration log.
* **Monthly usage comparison** — When the DA channel is configured, a per-site Nectar vs Sphera comparison
Unmapped and excluded sites are skipped when pushing to Sphera via API. Map or exclude every site so the push covers what you expect.
### Exporting
Click **Export** to open the export dialog:
| Field | Description |
| ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| **Export name** | A label for this export (appears in Export History) |
| **Date range** | Start and end dates for the billing periods to include |
| **Utility types** | Electricity, natural gas, fuel, water, sewer, waste, and district / steam. Leave empty for all. |
| **Sites** | Scope the export to specific sites. Leave empty for all. |
| **Filter by** | Whether dates refer to **Service Period Dates**, **Bill Dates**, or **Created Date** |
| **File type** | **Excel (.xlsx)** or **CSV (.csv)** |
| **Upload to Sphera API** | Push the data to the DI channel in addition to downloading the file. Unavailable until the DI channel is configured. |
| **Include bills with unresolved issues** | Include bills held for [data quality issues](/docs/platform/glossary#data-quality-issue) |
The export is recorded in your [Export History](/docs/platform/data-export/export-history).
Sphera DI imports **append** — re-pushing a period does not overwrite the previous rows. To correct data already in Sphera, delete the affected entries in Sphera first, then re-push. Nectar shows this reminder before every re-push.
### Monthly usage comparison
When the DA channel is configured, the comparison section reads the values stored in Sphera and diffs them against Nectar's calendarized monthly usage. Use it to confirm Sphera holds the right numbers and to re-push the ones it does not.
1. **Set the scope with the filters:**
* **Site** (pinned) — One mapped Sphera site at a time. Only sites mapped through the DA channel appear.
* **Commodity** — The utility type to compare. Only commodities with a configured questionnaire template appear.
* **Months** (required) — The month range to compare; clearing it resets to the current year.
2. **Read the usage chart** — Nectar's calendarized monthly usage and the values stored in Sphera are plotted side by side.
3. **Scan the monthly comparison table** — Each row shows the month, Nectar value, Sphera value, the percentage difference, and a status. **Expand a month** to list the bills that make up Nectar's total; click a bill to open it, or open the matching bills in [Data Inventory](/docs/platform/data-inventory/overview).
**Statuses:**
* **Synced** — Sphera matches your data for that month
* **Diff** — Both sides have data but the values differ
* **Not on Sphera** — Nectar has data Sphera never received
* **Missing in Nectar** — Sphera holds a value your data no longer produces
**Resolving discrepancies:**
* **Per row** — Click **Push** (for *Not on Sphera*) or **Sync** (for *Diff*) to re-push that month.
* **In bulk** — Click **Resync N discrepancies** above the table to re-push every drifted or not-on-Sphera month at once.
Because DI imports append, delete the existing entries for those months in Sphera before re-pushing, or the data is duplicated. If Sphera's data collection is **locked** through a cutoff date, months in the locked range are skipped and Nectar tells you which ones.
Sphera processes each import asynchronously, so re-pushed values can take a few minutes to appear. If a month is wrong on the Nectar side, fix the bills in [Data Inventory](/docs/platform/data-inventory/overview) before re-pushing.
## Settings
Manage the integration in [**Settings > Company > Integrations > Sphera**](https://dash.nectarclimate.com/settings/company/integrations/sphera):
* **Connection** — Sphera host, API route, and the GUID, connection key, and secret for each channel. Saving always verifies the credentials first, so invalid ones never reach the stored configuration. Leave a secret blank to keep the stored value.
* **Site mapping** — Nectar sites mapped to the Sphera sites discovered through the DA channel, with exclusions. **Refresh sites** re-discovers sites after you add them in Sphera.
* **Questionnaires** — The Sphera questionnaire template that holds each commodity's data. The same template applies to every site.
* **Column names** — Header names for the CSV that Nectar pushes to the DI channel.
### Column names
Each exported row is one bill, carrying the bill's account, meter, invoice, and audit-link metadata so values can be traced back to their source. Most headers are fixed, but these eight are configurable so they can match your Sphera import mapping:
| Column | Default header | Example |
| ------------------------ | ------------------- | --------------------------------- |
| Usage (bill units) | `usage` | 12,960 |
| Usage units (bill units) | `usage units` | kWh |
| Converted usage | `converted usage` | 12,960 |
| Converted units | `converted units` | kWh |
| Service start date | `start date` | 2026-10-01 |
| Service end date | `end date` | 2026-10-15 |
| Sphera site ID | `site external id` | 2.000000 |
| Audit trail link | `nectar audit link` | A link back to the bill in Nectar |
## Rotating credentials
Open the channel in the Connection Center, click **More** (`···`) in the detail panel header, and choose **Reset the API credentials** (the circular-arrow icon). Copy the new key and secret into [**Settings > Company > Integrations > Sphera**](https://dash.nectarclimate.com/settings/company/integrations/sphera) and save.
Resetting invalidates the old key and secret immediately. Nectar pushes and reads fail until you update the credentials in Nectar. Reset one channel at a time.
## Troubleshooting
| Symptom | Likely cause |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Connection test fails with an authentication error | Key or secret swapped between the DI and DA channels, or whitespace copied along with the value |
| Connection test fails with "not found" | Wrong channel GUID, or the host or API route is wrong (check for a trailing slash) |
| Test passes but pushes are rejected | The channel's **Online** checkbox is unchecked, or the DI channel's **Mapping** does not match Nectar's [column names](#column-names) |
| Site mapping finds no Sphera sites | DA channel missing or offline, or its **Save on behalf of** user cannot see those sites |
| Push succeeds but no data appears | Check the channel's **Log** tab in the Connection Center for per-import results and failed-row reasons |
The **Log** tab on each channel is the authoritative record of what Sphera received. Sphera 8.19+ also offers a downloadable error report listing failed rows with per-row reasons.
Still stuck? Email [support@nectarclimate.com](mailto:support@nectarclimate.com).
## FAQ
In SpheraCloud, go to **Management > Connection Center**, expand **Channels**, and click the channel. The **Info** tab shows a "Click to copy connection parameters" box containing the endpoint, the full URL with the channel UUID (that UUID is the GUID), the connection key, and the connection secret. Do this once for the Data Import channel and once for the Data Acquisition channel.
Connection Center sits under **Management** in the Corporate Sustainability app and requires administrator permissions. Ask your Sphera administrator to grant access, or to create the DI and DA channels and send you the GUID, key, and secret for each.
The Data Import (DI) channel receives data — it is how Nectar pushes bills into Sphera. The Data Acquisition (DA) channel is read-only — Nectar uses it to discover your Sphera sites and read stored values back for the monthly comparison. You can run the integration with DI alone, but the comparison requires DA credentials.
Electricity, natural gas, fuel, water, sewer, waste, and district / steam. The options you see depend on your Nectar data and Sphera configuration.
Most SpheraCloud instances use `api`. Self-hosted installations typically use `ws/rest.php`. The value is the URL prefix before the channel path in your **Endpoint** URL — Nectar appends `/di` and `/da` itself.
First delete the affected entries in Sphera — DI imports append, so re-pushing without deleting duplicates the data. Then use the **Push**, **Sync**, or **Resync** action on the monthly comparison to re-push the corrected values.
Open [**Settings > Company > Integrations > Sphera**](https://dash.nectarclimate.com/settings/company/integrations/sphera) and click **Refresh sites** on the site mapping card. Nectar re-discovers sites through the DA channel.
Yes. Go to [Export History](/docs/platform/data-export/export-history), find the export, and click to open the detail sheet. A **Download** button is available if the file is still within the 90-day retention period.