Skip to main content

Atrius CSV

Updated yesterday

👍 This article will help you:

  • Set up and configure your Atrius CSV integration

  • Understand formatting requirements and data flow

  • Push CSV data manually or automate with VBScript

  • Map discovered points to buildings

  • Troubleshoot your Atrius CSV integration

Overview

The Atrius CSV integration allows building systems to push trend data to Atrius on a recurring basis. This integration supports systems that export data in CSV format and can transmit files using different methods based on your requirements.

To view your current Atrius CSV integration details and status, go to Settings on the left side menu, select Integrations, then select Atrius CSV.

Integration Methods

This article covers the Encrypted CSV Push Method, which transmits CSV files via encrypted HTTPS without requiring authentication credentials. This method is suitable for systems that can push data directly via HTTPS requests.

Looking for a different method?

  • Authenticated sFTP Push Method - For organizations requiring credential-based authentication

Setup Process Overview

⚠️ Important: The order of steps is critical for successful integration. You must push data three times at specific stages before readings will appear in Atrius.
​

Step-by-step workflow:

  1. First Data Push - Push your CSV file using Postman or cURL to create the initial data stream

  2. Create Gateway - Add the CSV integration in Atrius and create your gateway

  3. Verify Gateway - Confirm your gateway name appears on the Atrius CSV integrations page

  4. Second Data Push - Push your CSV file again using the same gateway name

  5. Discover Points - Navigate to Point Discovery, filter by your gateway, and view newly discovered points

  6. Connect Points - Connect each point to a building and add required metadata (Building Name, Data Type, Source Unit, Display Unit, Reading Type)

  7. Third Data Push - Push your CSV file one final time to populate actual readings

  8. Verify Readings - Refresh your browser to see time series data on newly connected points

  9. Automate Data Pushes - Configure the VBScript and Windows Task Manager

Each of these steps is detailed in the sections below.

Encrypted CSV Push Method

This method uses encrypted HTTPS transmission to push CSV files to Atrius without requiring authentication credentials. A Visual Basic script is provided for Windows-based servers. When used with Microsoft Task Scheduler, this script monitors a local directory and automatically transmits CSV files via secure HTTPS requests to Atrius. Automating your data pushes to Atrius is recommended, but optional.

When to use this method:

  • Your organization allows HTTPS outbound connections (port 443)

  • You want a simple setup process without credential management

  • You're using Windows-based systems for automation

Prerequisites

Before beginning, ensure you have the following:

  • Gateway ID (format: bos://buildingos-csv/YOUR-SOURCE)

    • Your gateway ID should be a unique identifier for the data that will be pushed within the gateway.

  • Network or local access on PC folder directory that will be populated with CSV files

  • Outbound HTTPS access (port 443)

  • A properly formatted CSV file (see formatting requirements below)

  • The following tools:

    • Postman application (download here) for manual data push

    • Windows environment with Task Scheduler (for automation)

    • cURL command line tool (optional)

CSV File Format Requirements

Atrius can generate points from two types of CSV schemas, to reflect the two most common formats found in existing building automation exports.

Understanding the Atrius ID:

  • The Atrius ID is the field that uniquely identifies the point to Atrius. It can be the point name from your building automation system or a name you choose, provided it’s unique.

  • When the point is connected to Atrius, you will be able to assign it a more intuitive Point Name

  • For example, an Atrius ID of flr_3_lightingkWh could be displayed as “Third Floor Lighting” in Atrius

  • The Atrius ID for an existing point in Atrius can be found on the point profile

Your CSV file must meet these specifications:

  • Plain text format only (no Excel formulas or formatting)

  • Date & Time must be in the same column

  • Date & Time must be in order of oldest to newest (ascending)

  • ISO timestamp format where applicable (ex. September 27, 2025 at 6 p.m. is represented as 09/27/2025 18:00:00)

  • If you are pushing data for existing points, the Atrius IDs in the header (header-based) or first column (tuple-based) must match existing Atrius IDs

⚠️ Important: CSV files with text values ("none"), null values ("null"), or blank values (" ") will be interpreted as offline data points.

Standard CSV Format (Header-based)

  • The header row consists of Timestamp, followed by the unique identifier for each point (Atrius ID)

  • The first column contains the timestamps, ordered from oldest to newest

  • Each subsequent column contains the data for the unique identifier in the column header

Timestamp

Unique_Meter_ID1

Unique_Meter_ID2

6/2/2025 0:15

4

8.72

6/2/2025 0:30

5

9.53

6/2/2025 0:45

6

10.24

Alternative CSV Format (Tuple-based)

If your data is not available in the Standard CSV Format, you may alternatively use the Tuple Format, however it requires some additional configuration on the Gateway profile. Note, the header row displayed below should not be included in the data push.

Meter

Time

kWh

Unique_Meter_ID1

6/2/2025 0:15

8.72

Unique_Meter_ID1

6/2/2025 0:30

8.24

Unique_Meter_ID2

6/2/2025 0:15

3

Each row contains the Atrius ID, timestamp and value, ordered from oldest to newest (ascending). Data for multiple Atrius IDs can be pushed in the same file.
​

⚠️ This should only be used for special circumstances where your system cannot produce the standard header-based format.

Configuring the gateway for Tuple-based format:

  1. Navigate to the Atrius CSV gateway profile

  2. Under Configuration, add the appropriate parsing parameters:

    • advancelines: Number of header rows to skip

    • timestamp: Column index for timestamps (0-based)

    • channel: Column index for meter/point identifier

    • value: Column index for the reading value

  3. Save the configuration and push your CSV again

advancelines=1;timestamp=1;channel=0;value=2;

Manual Data Push Methods

You may use Postman or cURL Command to push data to Atrius.

Option 1: Data Push via Postman

  1. Open Postman

  2. Set the request method to POST

  3. Enter the API Endpoint URL:

    https://rest.buildingos.com/dsv/push/?datasource=bos://buildingos-csv/YourUniqueGatewayName

    ⚠️ Replace YourUniqueGatewayName with your specific gateway ID

  4. Navigate to the Body tab

  5. Select form-data

  6. Add a new key:

    • Key: file

    • Type: File

    • Value: Select your CSV file

  7. Click Send

  8. Verify the data push by checking for the "OK 200" message in Postman, then proceed to the Setting Up Your CSV Gateway section below

Option 2: Data Push via cURL Command

For command line environments:

curl --location --request POST 'https://rest.buildingos.com/dsv/push/?datasource=bos://buildingos-csv/YourUniqueGatewayName' \ --form 'file=@"/path/to/your/file.csv"'

⚠️ Replace path and gateway name with your specific values.

After pushing data via cURL, proceed to the Setting Up Your CSV Gateway section below.

Setting Up Your CSV Gateway

⚠️ Important: You must push data at least once before setting up your gateway in Atrius. Complete the Manual Data Push Methods section above first.
​

Step 1: Obtain Your Gateway ID

Your Gateway ID is the YourUniqueGatewayName portion of the API Endpoint URL you created for the first data push.
​

Step 2: Add the Integration in Atrius

  1. Navigate to Settings > Integrations

  2. Click Add an Integration

  3. Select Atrius CSV from the list of available integrations

  4. Enter your Gateway ID, YourUniqueGatewayName, in the CSV Gateway ID field

  5. Click Connect

Your gateway is now configured. Return to Postman and select "Send" again to push data for the second time.

You can locate your API Endpoint URL anytime by navigating to Settings > Integrations > Atrius CSV. All API Endpoint URLs will be displayed at the top of the page.

Connecting Discovered Points

After pushing your CSV file for the second time, you need to map discovered data points to buildings in Atrius.
​

Step 1: View Discovered Points

This step is to locate the points you would like to connect.

  1. Navigate to Integrations > Atrius CSV

  2. Click Point Discovery

  3. Use the Filter button to view points under your specific gateway

Step 2: Connect and Configure Points

This step is to connect points and configure the point profiles. It is expected that readings will not appear on the data manager yet.

For each point you want to add to Atrius:

  1. Click the Connect button next to the point

  2. Provide the required information:

  • Building Name: Select the building where this meter is located

  • Data Type: Select the type of data (e.g., electricity, gas, water)

  • Source Unit: The unit of measurement in your CSV file

  • Display Unit: The unit you want displayed in the Atrius data manager

  • Reading Type: Select the appropriate reading type

    • Learn more about Reading Types here

⚠️ Note: Reading Type is critical for proper data interpretation. The reading type should match the configuration at the source. You may need to test different options to find the correct setting.
​

3. Click Connect to save the point profile configuration

Push Time Series Data

This step is to push the actual time series data to the recently connected points in Atrius.

  1. Once you have connected the desired points and completed the point profile configuration, click "Send" in Postman one last time

  2. Navigate to the Source tab of each recently connected Point to verify your data is being received correctly

Now, readings will be available on the data manager of the recently connected points in Atrius.

Easily access the recently connected points by navigating to Settings > Integrations > Atrius CSV > Gateways > select the desired gateway > select the Points tab.

Automated Data Push with VBScript

Automating your data push is optional, but recommended. For scheduled, automated CSV data push on Windows systems, Atrius provides a VBScript solution.

Setting Up the VBScript

  1. Create a folder: C:\AtriusCSV

  2. Save the provided VBScript file (atrius_push.vbs) in this location

  3. Rename the VBScript file to match your Atrius Gateway ID

    • Example: YourUniqueGatewayName.vbs

    • Use your organization's specific gateway ID

  4. Run the script once to generate the required folders:

    • Outbox: Place CSV files here for automatic data push

    • Archive: Successfully pushed files are stored here (if enabled)

    • Debug: Log files are stored here (if enabled)

Key Configuration Variables

The VBScript includes several configurable variables:

  • srcDir: Directory where CSV files are placed for data push (default: Outbox subfolder)

  • archive: Set to True to save pushed files; False to delete them after data push

  • debug: Set to True to enable logging; False to disable

  • Gateway ID: Automatically generated from the script filename

If you need to override defaults, edit these variables in the script using Notepad

Scheduling with Windows Task Scheduler

To run the script automatically every 5 minutes:

  1. Open Task Scheduler (search in Windows Start menu)

  2. Click Create Task in the right panel

  3. General Tab:

    • Name: Atrius CSV Push

    • Select: "Run whether user is logged on or not"

    • Check: "Run with highest privileges"

  4. Triggers Tab:

    • Click New

    • Set to repeat every 5 minutes

    • Duration: Indefinitely

  5. Actions Tab:

    • Click New

    • Action: Start a program

    • Program/script: Browse to your .vbs file

  6. Settings Tab:

    • Check "Allow task to be run on demand"

    • Check "If the task fails, restart every: 1 minute"

  7. Click OK to save

Best Practices for Automating your Data Push

  • File Management: Enable archiving to maintain a record of pushed files

  • Logging: Enable debug logging during initial setup and troubleshooting

  • Validation: Always validate CSV formatting before data push to avoid errors

  • Automation: Use Task Scheduler for hands-off, reliable data push operations

  • Testing: Test with a small sample file before processing large datasets

  • Regular Monitoring: Periodically check that scheduled data push operations are running successfully

Troubleshooting

Common Error Codes

400 Error - Bad Request

  • Check your CSV file format

  • Verify your Gateway ID is correct

  • Ensure the datasource parameter in your URL matches your Gateway ID

500 Error - Server Error

  • Server-side issue; try again later

If all Atrius CSV points are offline

  • Reboot the dedicated server that is generating the CSV data file(s)

  • Verify that port 443 outbound is enabled for HTTPS

  • Verify any scheduled tasks that either generate or deliver the CSV data file

  • Verify and/or correct any recent formatting changes to the CSV data file, including:

    • Timestamp format

    • Header formatting

    • Atrius ID (Point ID) Names

⚠️ Important: For existing points, Atrius IDs in your CSV file must match Atrius IDs on the point profile. See "CSV File Format Requirements" for Point ID best practices.

If only a partial list of Atrius CSV points are offline

  • Ensure individual Atrius IDs and Point Values exist within your CSV data file

  • Verify that CSV cells do not contain text ("none"), null values ("null"), or blank values (" ")

  • Verify that the individual metering hardware/devices are reporting expected values

If any Atrius CSV points are flatlined

  • Verify that the individual metering hardware/devices are reporting expected values

  • Check that new data is being written to your CSV files on the expected schedule

Points Not Appearing

  • Verify the CSV file was successfully pushed (check for error messages in Postman)

  • Ensure new points are not filtered out in the discovery view

  • Refresh your browser after data push

Incorrect Time Values

If timestamps in Atrius don't match your source data:

  1. Navigate to Settings > Integrations > Atrius CSV or: https://buildingos.com/gateways/service/30

  2. Select your CSV gateway

  3. Toggle the Convert Time to UTC setting

  4. Push your CSV file again to verify the timestamps are correct

Additional Resources

  • A Facilities or Controls point of contact can determine if individual metering hardware/devices have lost power or network connectivity

  • A Network or IT point of contact can determine if the dedicated CSV server is down, or if it's impacted by network/firewall settings changes or network hardware changes

🚧 Forward to Additional Contacts

Please forward this information to any additional Facilities, Controls, Network or IT points of contact at your organization for on-site support.

Frequently Asked Questions

Q: Can I push multiple CSV files at once?
A: Yes. When using the VBScript with automation, place multiple CSV files in the Outbox folder. The script will process each file sequentially.

Q: Why did I receive an error message when creating my Atrius CSV gateway?

A: The gateway ID must match the YourUniqueGatewayName portion of the API Endpoint URL you pushed data to the first time.

Q: Where do I find my Gateway name?
A: Navigate to https://buildingos.com/gateways/service/30 and click on your gateway to view the full Gateway ID.

Q: What happens if I push a malformed CSV?
A: You will receive a 400 error. Review the CSV format requirements and adjust your driver configuration if needed, or contact Customer Support for assistance.

Q: How often should I schedule data push operations?
A: This depends on your data frequency requirements. Most customers schedule data push operations every 5-15 minutes for near-real-time data.

👍 Contact Customer Support

For additional questions regarding your integration with Atrius, please contact Customer Support.

Attachment icon
Atrius CSV Connector_customer.pdf
Related Articles
Batch Point Data Upload
eGauge
Kodaro Niagara CSV
Obvius AcquiSuite (Leviton Energy Management Hub)
Siemens
Did this answer your question?