Sensly
Export parsed IMSURGE data into Sensly organisations and projects.
Setup Instructions
1. Prerequisites
Before creating your Sensly integration, ensure you have:
- Access to the Sensly portal.
- Your API Key, found under My Profile.
To retrieve your API key:
- Log in to the Sensly portal.
- Click the profile icon in the top-right and select My Profile.
- Your API Key is listed under your profile. Click the eye icon to reveal it, then copy the key.
2. Creating the Credentials
When adding your Sensly integration, you will be prompted to create or select a set of Credentials. To create them, enter:
- API Key – your Sensly API token.
3. Creating the Integration
After creating or selecting your Credentials, IMSURGE will automatically query the Sensly API to retrieve the list of resources available to the API key. You will be prompted to choose:
- Organisation – select from organisations associated with the API key.
- Project – select a project within the chosen organisation to receive the exported data.
After saving the integration, test it to confirm access and verify that data can be delivered successfully.
Blueprint Behavior
Sensly uses blueprints to define the structure of incoming data. When exporting data from IMSURGE, blueprints are created and reused based on the structure of the data being delivered. Understanding this behavior is important, as changes in metric structure or naming can result in additional blueprints being generated.
Multi-Dimensional Sensors
IMSURGE supports multi-dimensional sensors, where a single physical device may expose multiple logical sensors, each with multiple metrics. A common example is a total station, which is one device with many sensors, each reporting multiple measurements.
When exporting this data to Sensly:
- A separate Sensly sensor is created for each logical sensor identified by the source device.
- A Sensly blueprint is created for each unique set of metrics produced by those sensors.
If multiple sensors output the exact same set of metrics, IMSURGE will reuse the same blueprint and create multiple sensors that reference it. This is typical for devices like total stations, where each prism reports an identical set of outputs.
Blueprint Matching Rules
Blueprint reuse is determined by an exact match on:
- Manufacturer name – set by IMSURGE and derived from the source integration type
- Input (metric) names
All inputs must match exactly. Any difference will result in a new blueprint being created.
This includes:
- Sensors using identical hardware but with different enabled or disabled outputs.
- Sensors that emit a different set of metrics over time.
- Differences in input naming, including casing or formatting.
Naming and Configuration Considerations
Some source systems allow users to rename input names. IMSURGE passes these values through exactly as provided by the source.
Because of this:
- Renaming inputs at the source can cause new blueprints to be generated for otherwise identical sensors.
- Inconsistent naming across sensors can lead to a cluttered blueprint list in Sensly.
- Maintaining consistent naming conventions at the source helps ensure blueprint reuse.
The Manufacturer name used for blueprint matching is controlled by IMSURGE and is based on the source integration type.
Even if the manufacturer name appears generic or unexpected, it should not be renamed in Sensly. Renaming the manufacturer will cause IMSURGE to treat future data as a different sensor type and generate new blueprints.
It is safe to rename:
- Sensly blueprints
- Sensly sensors
These changes do not affect how future data is matched.
Renaming input names at the source or renaming the manufacturer in Sensly should be done carefully, as it may have unintended consequences for blueprint creation.
Why This Matters
Some devices do not explicitly distinguish between different logical sensors and instead emit readings as a single stream. In these cases, IMSURGE relies entirely on the reported metric structure to determine how data should be modeled in Sensly.
This behavior ensures data integrity and prevents incompatible data from being written into the same sensor or blueprint, even if it results in additional blueprints when metric structures change.
Reference
Tips
API keys are tied to individual user accounts. For security and maintainability, it is recommended to create a dedicated user specifically for API access.
Concerns & Limitations
- Permissions – your API key must have write access to the organisation and project. If no projects appear, check the scope of your key.
- Data formats – Sensly accepts numeric time series data. Ensure your IMSURGE columns are numeric and match expected units.
- No metadata export – descriptive metadata is not included; only data values are written.