Skip to content

SolarUser Cloud Integrations API

Jump to bottom Edit New page
Matt Magoffin edited this page Oct 22, 2024 · 42 revisions

The SolarUser Cloud Integrations API provides methods to manage integrations with external cloud services. All requests must provide a valid user authentication token. See SolarNet API authentication for information on how to use authentication tokens.

For general information about Cloud Integrations support in SolarNetwork see the Cloud Integrations guide.

API Endpoints

The following endpoint paths are all relative to the base path /solaruser/api/v1/sec/user/c2c.

Service discovery endpoints

The Services group of endpoints provide details on the types of cloud integration services SolarNetwork supports.

Verb Endpoint Description
GET /services/integrations List integration services
GET /services/datum-streams List datum stream services
GET /services/datum-streams/data-filters List the data filters available for a given datum stream service

Cloud Integration entity endpoints

The Cloud Integration entity represents a connection to an external cloud service.

Verb Endpoint Description
POST /integrations Create integration
GET /integrations List integrations
GET /integrations/{integrationId} View integration
PUT /integrations/{integrationId} Update integration
DELETE /integrations/{integrationId} Delete integration
POST /integrations/{integrationId}/enabled/{enabled} Update integration enabled status
GET /integrations/{integrationId}/validate Validate integration connectivity

Datum Stream data values endpoint

The Datum Stream data values endpoint exposes the Data Value hierachy supported by a configured Cloud Integration entity.

Verb Endpoint Description
GET /integrations/{integrationId}/data-values List data values

Cloud Datum Stream Mapping entity endpoints

The Cloud Datum Stream Mapping entity represents a group of Cloud Datum Stream Mapping Property entities that map a set of cloud data values to a complete SolarNetwork datum stream.

Verb Endpoint Description
POST /datum-stream-mappings Create datum stream mapping
GET /datum-stream-mappings List datum stream mappings
GET /datum-stream-mappings/{datumStreamMappingId} View datum stream mapping
PUT /datum-stream-mappings/{datumStreamMappingId} Update datum stream mapping
DELETE /datum-stream-mappings/{datumStreamMappingId} Delete datum stream mapping

Cloud Datum Stream Mapping Property entity endpoints

The Cloud Datum Stream Mapping Property entity represents a mapping of a single cloud data value to a SolarNetwork datum stream property.

Verb Endpoint Description
POST /datum-stream-mappings/{datumStreamMappingId}/properties Create datum stream mapping properties
GET /datum-stream-mappings/{datumStreamMappingId}/properties List datum stream mapping properties
PUT /datum-stream-mappings/{datumStreamMappingId}/properties/{index} Save datum stream mapping property
DELETE /datum-stream-mappings/{datumStreamMappingId}/properties/{index} Delete datum stream mapping property
POST /datum-stream-mappings/{datumStreamMappingId}/properties/{index}/enabled/{enabled} Update datum stream mapping property enabled status

Cloud Datum Stream entity endpoints

The Cloud Datum Stream entity represents a mapping of cloud data values to a SolarNetwork datum stream. The serviceIdentifier property is configured with the identifier of a supported Cloud Datum Stream Service. The supported services can be listed with the Datum Stream Services list endpoint.

Verb Endpoint Description
POST /datum-streams Create datum stream
GET /datum-streams List datum streams
GET /datum-streams/{datumStreamId} View datum stream
PUT /datum-streams/{datumStreamId} Update datum stream
DELETE /datum-streams/{datumStreamId} Delete datum stream
POST /datum-streams/{datumStreamId}/enabled/{enabled} Update datum stream enabled status

Cloud Datum Stream Poll Task entity endpoints

The Cloud Datum Stream Poll Task entity represents the runtime state of a datum stream poll task, specific to a Cloud Datum Stream.

Verb Endpoint Description
GET /datum-stream-poll-tasks List datum streams
PUT /datum-stream-poll-tasks/{datumStreamId} Save datum stream poll task
DELETE /datum-stream-poll-tasks/{datumStreamId} Delete datum stream poll task
POST /datum-stream-poll-tasks/{datumStreamId}/state Update datum stream poll task state (start/stop)

Services

The following endpoints provide details on the types of cloud integration services SolarNetwork supports.

Integration Services list

This method will list the Cloud Integration services supported by SolarNetwork, and the configurable service properties that are supported for those services.

GET /solaruser/api/v1/sec/user/c2c/services/integrations

Integration Services list response

The response will be a list of localized service description objects:

Property Type Description
id String The integration service identifier.
locale String The locale of the response information.
settingSpecifiers SettingSpecifier[] List of setting specifier objects that define the available service properties for the integration service.
localizedName String A localized name for the integration service.
localizedInfoMessages Map Localized messages for all setting specifiers.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "s10k.c2c.i9n.locus",
      "locale": "en-US",
      "settingSpecifiers": [
        {
          "key": "oauthClientId",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "oauthClientSecret",
          "markup": false,
          "secureTextEntry": true,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "username",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "password",
          "markup": false,
          "secureTextEntry": true,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "partnerId",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        },
        {
          "key": "baseUrl",
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.TextFieldSettingSpecifier"
        }
      ],
      "localizedName": "Locus Energy",
      "localizedInfoMessages": {
        "title": "Locus Energy",
        "oauthClientId.key": "OAuth Client ID",
        "oauthClientId.desc": "The OAuth client identifier.",
        "oauthClientSecret.key": "OAuth Client Secret",
        "oauthClientSecret.desc": "The OAuth client secret.",
        "username.key": "Username",
        "username.desc": "The user login name.",
        "password.key": "Password",
        "password.desc": "The user login password.",
        "partnerId.key": "Partner ID",
        "partnerId.desc": "The partner identifier.",
        "baseUrl.key": "Base URL",
        "baseUrl.desc": "An alternate URL to use to access the cloud service."
      }
    }
  ]
}

Cloud Integration services

SolarNetwork supports the following integration services:

Service Identifier Description
Locus Energy (AlsoEnergy) s10k.c2c.i9n.locus Integrate with the Locus Energy API.
SolrenView s10k.c2c.i9n.solrenview Integrate with the SolrenView API.

Each service can support one or more Cloud Datum Stream Service.

Locus Energy Integration service

The Locus Energy integration service identifier is s10k.c2c.i9n.locus. The following service properties are supported:

Property Description
oauthClientId The OAuth client identifier to use for authentication.
oauthClientSecret The OAuth client secret to use for authentication.
username The user login name to use for authentication.
password The user login password to use for authentication.
partnerId The partner identifier of the Locus Energy account.
baseUrl An optional alternate URL to use to access the cloud service.

Locus Energy Datum Stream services

The Locus Energy integration supports the following Cloud Datum Stream Service implementations:

Service Identifier Description
Locus Energy (AlsoEnergy) s10k.c2c.ds.locus Polling datum stream using the Locus Energy API.

Locus Energy Datum Stream Service

The Locus Energy datum stream service identifier is s10k.c2c.ds.locus. The following service properties are supported:

Property Description
granularity The resolution of the data to request. One of 1min, 5min, 15min, hourly, daily, monthly, yearly
placeholders An optional Map of placeholder names with asscoiated values, to make available to Datum Stream Mapping Property value references

The following placeholders are supported on the placeholders service property:

Placeholder Description
siteId A single Locus Energy site ID value to associate with the datum stream
componentId A single Locus Energy component ID value to associate with the datum stream

The following Data Filters are supported:

Filter Key Description
siteId A Locus Energy site ID value
componentId A Locus Energy component ID value

Locus Energy Datum Stream data value metadata

The Locus Energy integration uses the following data value cloud-speicifc metadata keys:

Key Description
aggregation Aggregation for this value. Options are min, max, avg, and sum
application Use of component. Options are: GENERATION or NET-GRID
generationType Type of generation. Options are: SOLAR, WIND, THERMAL, OTHER, NET-GRID, or EVSE
nodeId Unique MAC address of the physical device that this component represents, for example OB.001EC6666666.11
nodeType Type of comopnent, for example METER
source Type of data. This can be Measured, Modeled, or Expected

SolrenView Integration service

The SolrenView integration service identifier is s10k.c2c.i9n.solrenview. The following service properties are supported:

Property Description
baseUrl An optional alternate URL to use to access the cloud service.

SolrenView Datum Stream services

The SolrenView integration supports the following Cloud Datum Stream Service implementations:

Service Identifier Description
SolrenView s10k.c2c.ds.solrenview Polling datum stream using the SolrenView API.

SolrenView Datum Stream Service

The SolrenView datum stream service identifier is s10k.c2c.ds.solrenview. The following service properties are supported:

Property Description
granularity The resolution of the data to request. One of 1min, 5min, 10min ,15min, 20min, 30min, hourly, daily, monthly, yearly
placeholders An optional Map of placeholder names with asscoiated values, to make available to Datum Stream Mapping Property value references
sourceIdMap A map or comma-delimited mapping list of component IDs to associated source ID values. For example in JSON, an object {"12345":"INV/1","23456":"INV/2"} or a string "12345=INV/1,23456=INV/2". See source ID mapping for more information.

The following placeholders are supported on the placeholders service property:

Placeholder Description
siteId A single SolrenView site ID to associate with the datum stream

The following Data Filters are supported:

Filter Key Description
siteId A SolrenView site ID value (required)

⚠️ Note the SolrenView service does not offer a top-level Data Value hierarchy discovery option to find a list of available siteId values. You must know the ID of the site you want to use, and provide that as query parameter.

SolrenView Datum Stream source ID mapping

The SolrenView API returns data for all devices within a site, and as such the Datum Stream Service can generate SolarNetwork datum streams for multiple devices at once, if desired. To do so, the valueReference for a Datum Stream Mapping Property can use a * wildcard for the 2nd-level identifier. This can be combined with the {siteId} placeholder. SolarNetework will then take the sourceId defined on the Datum Stream and append /X to each device in the site, where X is a number: the offset of the device within the site, starting from 1.

For example, imagine the Data Values method returned the devices 1111111111111 and 2222222222222 for site 1111 like this:

{
  "success": true,
  "data": [
    {
      "name": "My Solar Site",
      "identifiers": [
        "1111"
      ],
      "metadata": {
        "street": "123 Main Street",
        "l": "Anytown",
        "st": "CT",
        "postalCode": "06825",
        "tz": "-4:00"
      },
      "children": [
        {
          "name": "1111111111111",
          "identifiers": [
            "1111",
            "1111111111111"
          ],
          "children": [
            {
              "name": "WHL",
              "reference": "/1111/1111111111111/WHL",
              "identifiers": [
                "1111",
                "1111111111111",
                "WHL"
              ]
            },
            {
              "name": "W",
              "reference": "/1111/1111111111111/W",
              "identifiers": [
                "1111",
                "1111111111111",
                "W"
              ]
            }
          ]
        },
        {
          "name": "2222222222222",
          "identifiers": [
            "1111",
            "2222222222222"
          ],
          "children": [
            {
              "name": "WHL",
              "reference": "/1111/2222222222222/WHL",
              "identifiers": [
                "1111",
                "2222222222222",
                "WHL"
              ]
            },
            {
              "name": "W",
              "reference": "/1111/2222222222222/W",
              "identifiers": [
                "1111",
                "2222222222222",
                "W"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Assuming your Datum Stream was configured with a sourceId of INV, you could configure two mapping properties like this:

Value Reference SolarNetwork Property Property Type
/{siteId}/*/W watts i
/{siteId}/*/WHL wattHours a

Then SolarNetwork would generate 2 datum streams: INV/1 and INV/2, both with watts and wattHours properties.

You can also configure a sourceIdMap service property on the Datum Stream to define an explicit mapping of device identifiers to associated source IDs. For example the Datum Stream could be created like this:

{
  "enabled": true,
  "name": "SolrenView Example",
  "serviceIdentifier": "s10k.c2c.ds.solrenview",
  "integrationId": 1,
  "schedule": "300",
  "kind": "n",
  "objectId": "123",
  "sourceId": "unused",
  "serviceProperties": {
    "granularity": "5min",
    "siteId": 1111,
    "sourceIdMap": {
      "1111111111111": "S1/INV/01",
      "2222222222222": "S1/INV/02",
    }
  }
}

Here the generated datum streams would be S1/INV/01 and S1/INV/02 because of the sourceIdMap setting. The unused sourceId setting would not be used.

☝️ When sourceIdMap is configured, only the devices explicitly included will be generated into datum streams, and all other devices will be ignored.

Datum Stream Services list

This method will list the Cloud Datum Stream services supported by a given Cloud Integration Service, and the configurable service properties that are supported for those services.

GET /solaruser/api/v1/sec/user/c2c/services/datum-streams
identifier The id of the Cloud Integration to list the datum stream services for

Datum Stream Services list response

The response will be a list of localized service description objects:

Property Type Description
id String The datum stream service identifier.
locale String The locale of the response information.
settingSpecifiers SettingSpecifier[] List of setting specifier objects that define the available service properties for the integration service.
localizedName String A localized name for the integration service.
localizedInfoMessages Map Localized messages for all setting specifiers.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "s10k.c2c.ds.locus",
      "locale": "en-US",
      "settingSpecifiers": [
        {
          "key": "granularity",
          "defaultValue": "latest",
          "valueTitles": {
            "latest": "latest",
            "1min": "1min",
            "5min": "5min",
            "15min": "15min",
            "hourly": "hourly",
            "daily": "daily",
            "monthly": "monthly",
            "yearly": "yearly"
          },
          "markup": false,
          "secureTextEntry": false,
          "transient": false,
          "type": "net.solarnetwork.settings.MultiValueSettingSpecifier"
        }
      ],
      "localizedName": "Locus Energy Datum Stream",
      "localizedInfoMessages": {
        "title": "Locus Energy Datum Stream",
        "granularity.key": "Granularity",
        "granularity.desc": "The resolution of the data to request.",
        "granularity.latest": "Latest",
        "granularity.1min": "1 minute",
        "granularity.5min": "5 minute",
        "granularity.15min": "15 minute",
        "granularity.hourly": "Hourly",
        "granularity.daily": "Daily",
        "granularity.monthly": "Monthly",
        "granularity.yearly": "Yearly"
      }
    }
  ]
}

Datum Stream Data Filters list

This method will list the data filters supported by a given Cloud Datum Stream service. The data filters are used to discover the possible data mappings a given cloud integration supports, and work like a hierarchical query filter to "drill down" into the data exposed by the cloud service.

GET /solaruser/api/v1/sec/user/c2c/services/datum-streams/data-filters
identifier The id of the Cloud Datum Stream to list the data filters for.
any Any additional id key (as returned by this API) and associated filter value to narrow the results to.

Datum Stream Data Filters response

The response will be a list of localized service information objects:

Property Type Description
id String The data filter identifier. This defines a possible additional query parameter that can be provided to this API to "drill down" into the data hierarchy of the cloud service.
locale String The locale of the response information.
localizedName String A localized name for the data filter.
localizedDescription String Localized description of the data filter.

An example response looks like:

{
  "success": true,
  "data": [
    {
      "id": "siteId",
      "locale": "en-US",
      "localizedName": "Site ID",
      "localizedDescription": "The site identifier to restrict the results to."
    },
    {
      "id": "componentId",
      "locale": "en-US",
      "localizedName": "Component ID",
      "localizedDescription": "The component identifier to restrict the results to."
    }
  ]
}

Datum Stream data values

This API provides a way to discover the "data values" that are supported by a cloud integration, that can be mapped onto a SolarNetwork datum stream. The Datum Stream Data Filters list API will provide you with the list of possible data filters you can use to "drill down" into the data hierarchy supported by the cloud integration.

GET /solaruser/api/v1/sec/user/c2c/datum-streams/{integrationId}/data-values
integrationId The configId of the Cloud Integration to list the data values for
datumStreamServiceIdentifier The serviceIdentifier of the Cloud Datum Stream Service to use. Can omit to use the first-available service supported by the Cloud Integration Service configured on the given Cloud Integration
any Any additional id key as returned by the Datum Stream Data Filters list API and associated filter value to narrow the results to

Datum Stream data values response

The response will be a list of Data Value objects, which conceptually exist as a tree structure that reflects the hierarchy of data presented by the cloud service. The leaf nodes within the tree represent data points that can be mapped onto SolarNetwork datum stream properties by including their reference property value on Coud Datum Stream Mapping Property entities.

Each Data Value object has the following properties:

Property Type Description
name String A display name for the value.
reference String A unique identifier that, for leaf nodes, can be included on Coud Datum Stream Mapping Property entities.
identifiers String[] A list of data value hiearchy identifiers used to uniquely identify the value.
metadata Map<String, any> Cloud service-specific metadata to help identify the value. Some standard keys are defined.

An example response looks like this:

{
  "success": true,
  "data": [
    {
      "name": "Acme Solar Plant",
      "identifiers": [
        "1122334"
      ],
      "metadata": {
        "street": "123 Main Street",
        "l": "Anytown",
        "st": "California",
        "postalCode": "90731",
        "c": "US",
        "tz": "America/Los_Angeles"
      }
    }
  ]
}

Datum Stream data value metadata

The metadata property on Data Value objects holds extra details provided by the cloud service that can be helpful for locating the values you want to map onto SolarNetwork datum streams. The example response shown in the previous section hints at the type of information that might be included.

Although the exact metadata provided depends on the cloud service, SolarNetwork defines the following standard keys that cloud integrations will provide if possible:

Key Description
c A postal location country name or code, for example US.
l A postal location locality (city) name or code, for example Anytown.
manufacturer A device manufacturer name.
model A device model name.
postalCode A postal code, for example 90731.
serial A device serial number.
st A postal location state or province name, for example California.
street A postal location street address, for example 123 Main Street.
tz A time zone identifier, for example America/Los_Angeles.
unit A unit of measure name.

Note that the keys listed here may or may not be provided, and other cloud service-specific values may be provided. See the docuemntation on a given Cloud Integration Service for more details.

Datum Stream data values API usage

To use this API, first make a request with just the datumStreamId path variable and no query parameters, to discover what top-level data values are available. You can use the identifiers provided in that response to then make additional requests that provide specific identifiers as additional query parameters, until you reach the "bottom" of the hierarchy where specific cloud data values are available for mapping into a SolarNetwork datum stream.

For example, imagine GET /services/datum-streams/data-filters returned the example shown above, which means the following filters are available:

  • siteId - a site identifier
  • componentId - a component identifier

The initial request would be without any query parameters:

/datum-streams/1/data-values

This will return the available "sites" with their site identifiers. For example:

{
  "success": true,
  "data": [
    {
      "name": "Acme Solar Plant",
      "identifiers": [
        "1122334"
      ],
      "metadata": {
        "street": "123 Main Street",
        "l": "Anytown",
        "st": "California",
        "postalCode": "90731",
        "c": "US",
        "tz": "America/Los_Angeles"
      }
    }
  ]
}

Here there was one site named Acme Solar Plant with the identifier 1122334. Given that initial response, you can "drill down" into Acme Solar Plant by calling the API again, but with a siteId=1122334 query parameter, this is:

/services/datum-streams/data-filters?siteId=1122334

This will return the next layer in the data hierarchy: a list of "components" for the given site. Imagine that returned the following:

{
  "success": true,
  "data": [
    {
      "name": "Elkor RGM",
      "identifiers": [
        "1122334",
        "5555566"
      ],
      "metadata": {
        "manufacturer": "Elkor",
        "model": "WattsOn - Mark II",
        "nodeId": "OB.001EC111111.11",
        "nodeType": "METER",
        "application": "GENERATION",
        "generationType": "SOLAR"
      }
    },
    {
      "name": "Inverter 01",
      "identifiers": [
        "1122334",
        "6677777"
      ],
      "metadata": {
        "manufacturer": "Ginlong",
        "model": "Solis-60K-US",
        "nodeId": "OB.001EC1111111.22",
        "nodeType": "INVERTER",
        "application": "GENERATION",
        "generationType": "SOLAR"
      }
    }
  ]
}

The response includes two components, an Elkor WattsOn meter and a Ginlong Solis solar inverter. You can drill down into the Elkor meter by adding a componentId=5555566 to the API, like this:

/services/datum-streams/data-filters?siteId=1122334&componentId=5555566

This will return the next layer in the data hierarchy: a list of values for the given site and component. For example:

{
  "success": true,
  "data": [
    {
      "name": "AC Power",
      "reference": "/4116250/2794394/W",
      "identifiers": [
        "1122334",
        "5555566",
        "W"
      ],
      "metadata": {
        "source": "Measured",
        "unit": "W"
      },
      "children": [
        {
          "name": "AC Power avg",
          "reference": "/4116250/2794394/W/W_avg",
          "identifiers": [
            "1122334",
            "5555566",
            "W",
            "W_avg"
          ],
          "metadata": {
            "aggregation": "avg"
          }
        },
        {
          "name": "AC Power max",
          "reference": "/4116250/2794394/W/W_max",
          "identifiers": [
            "1122334",
            "5555566",
            "W",
            "W_max"
          ],
          "metadata": {
            "aggregation": "max"
          }
        }
      ]
    }
  ]
}

Notice that this response includes two more levels in the hierarchy, as the first AC Power object has a children property with AC Power avg, AC Power max, and AC Power min objects included. These children objects are leaf nodes so their reference value can be used as a valueReference on a Coud Datum Stream Mapping Property.

Note that even though the AC Power Data Value has a reference property it can not be used as a valueReference property of a Coud Datum Stream Mapping Property, because AC Power has a children property and is thus not a leaf node in the data values hierarchy.

Cloud Integration

The Cloud Integration entity represents a connection to an external cloud service. Use these endpoints to manage integration entities.

Cloud Integration create

This method creates a new Cloud Integration entity. An application/json request body must be provided with the integration details to create.

POST /solaruser/api/v1/sec/user/c2c/integrations

The request body accepts a Cloud Integration JSON object with the following properties:

Property Type Description
enabled Boolean The desired enabled state of the entity.
name String A display name.
serviceIdentifier String The Service ID of the Cloud Integration Service to use.
serviceProperties Object Cloud Integration Service-specific settings to use.

For example:

{
  "enabled": true,
  "name": "Locus Energy Meter Example",
  "serviceIdentifier": "s10k.c2c.i9n.locus",
  "serviceProperties": {
    "username": "foo",
    "password": "bar",
    "oauthClientId": "abc",
    "oauthClientSecret": "02ffffffff3333333777777777777777",
    "partnerId": 12345
  }
}

The response will be a Cloud Integration entity object that provides the ID assigned. See Cloud Integration view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/c2c/integrations/1

Cloud Integration list

This method returns a list of Cloud Integration entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/integrations

The URL accepts the following search filter query parameters:

Property Type Description
integrationId Number The ID of a integration to match.
integrationIds Number[] A comma-delimited list of integration IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a [paged results][paged-results] list of Cloud Integration entity objects. See the Cloud Integration view response for details.

Cloud Integration view

This method returns a Cloud Integration entity.

GET /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}
integrationId The ID of the Cloud Integration to view.

Cloud Integration view response

The response will be a Cloud Integration entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
configId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
enabled Boolean Enabled status indicator.
name String The display name.
serviceIdentifier String The Service ID of the Cloud Integration Service to use.
serviceProperties Object Cloud Integration Service-specific settings to use.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "configId": 4,
    "created": "2024-10-12 03:50:55.90895Z",
    "modified": "2024-10-12 03:51:20.525542Z",
    "enabled": true,
    "name": "Locus Energy Meter Example",
    "serviceIdentifier": "s10k.c2c.i9n.locus",
    "serviceProperties": {
      "password": "{AES}ABCD_XmAofK0b-scoU",
      "username": "foo",
      "partnerId": "12345",
      "oauthClientId": "02ffffffff3333333777777777777777",
      "oauthClientSecret": "{AES}abcd_ceNmf1sVp08U3XCN3w"
    }
  }
}

☝️ Note that sensitive setting values like password will be encrypted by SolarNetwork.

Cloud Integration update

This method updates an existing Cloud Integration entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}
integrationId The ID of the Cloud Integration to update.

The request body accepts a Cloud Integration JSON object as specified in the Cloud Integration create method. The response will be the updated entity as specified in the Cloud Integration view method.

Cloud Integration delete

This method deletes a Cloud Integration entity. ⚠️ All entities associated with the entity will be deleted as well.

DELETE /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}
integrationId The ID of the Cloud Integration to delete.

The response will be a simple success or failure message.

Cloud Integration update enabled

This method updates the enabled status of a Cloud Integration entity.

POST /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}/enabled/{enabled}
integrationId The ID of the Cloud Integration to update.
enabled The desired enabled state to set.

The response will be a simple success or failure message.

Cloud Integration validate

This method validates the connectivity between SolarNetwork and the cloud service, for example using the configured credentials.

GET /solaruser/api/v1/sec/user/c2c/integrations/{integrationId}/validate
integrationId The ID of the Cloud Integration to validate.

The response will be a simple success or failure message.

Cloud Datum Stream Mapping

The Cloud Datum Stream Mapping entity represents a group of Cloud Datum Stream Mapping Property entities that map a set of cloud data values to a complete SolarNetwork datum stream.

Cloud Datum Stream Mapping create

This method creates a new Cloud Datum Stream Mapping entity. An application/json request body must be provided with the details to create.

POST /solaruser/api/v1/sec/user/c2c/datum-stream-mappings

The request body accepts a Cloud Datum Stream Mapping JSON object with the following properties:

Property Type Description
name String A display name.
integrationId Number The ID of the Cloud Integration entity to use.

For example:

{
  "name": "Locus Energy Meter",
  "integrationId": 1
}

The response will be a Cloud Datum Stream Mapping entity object that provides the ID assigned. See Cloud Datum Stream Mapping view response for more information. In addition a Location HTTP header will be returned with the path to view the entity, for example:

Location: /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/1

Cloud Datum Stream Mapping list

This method returns a list of Cloud Datum Stream Mapping entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-mappings

The URL accepts the following search filter query parameters:

Property Type Description
datumStreamMappingId Number The ID of a datum stream mapping to match.
datumStreamMappingIds Number[] A comma-delimited list of datum stream mapping IDs to match (logical OR).
integrationId Number The ID of a integration to match.
integrationIds Number[] A comma-delimited list of integration IDs to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

The response will be a [paged results][paged-results] list of Cloud Datum Stream Mapping entity objects. See the Cloud Datum Stream Mapping view response for details.

Cloud Datum Stream Mapping view

This method returns a Cloud Datum Stream Mapping entity.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping to view.

Cloud Datum Stream Mapping view response

The response will be a Cloud Datum Stream Mapping entity object with the following properties:

Property Type Description
userId Number The SolarNetwork account ID that owns the entity.
configId Number A unique ID assigned to the entity.
created String The creation date.
modified String The modification date.
name String The display name.
integrationId Number The ID of the associated Cloud Integration entity.

An example response looks like:

{
  "success": true,
  "data": {
    "userId": 123,
    "configId": 1,
    "created": "2024-10-15 22:35:52.39096Z",
    "modified": "2024-10-15 22:40:58.17154Z",
    "name": "Locus Energy Meter",
    "integrationId": 1
  }
}

Cloud Datum Stream Mapping update

This method updates an existing Cloud Datum Stream Mapping entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping to update.

The request body accepts a Cloud Datum Stream Mapping JSON object as specified in the Cloud Datum Stream Mapping create method. The response will be the updated entity as specified in the Cloud Datum Stream Mapping view method.

Cloud Datum Stream Mapping delete

This method deletes a Cloud Datum Stream Mapping entity. ⚠️ All associated Cloud Datum Stream Mapping Property entities will be deleted as well.

DELETE /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping to delete.

The response will be a simple success or failure message.

Cloud Datum Stream Mapping Property

The Cloud Datum Stream Mapping Property entity represents a mapping of a single cloud data value to a SolarNetwork datum stream property.

Cloud Datum Stream Mapping Property create

This method creates a set of Cloud Datum Stream Mapping Property entities. An application/json request body must be provided with the details to create.

POST /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties

The request body accepts a JSON array of Cloud Datum Stream Mapping Property JSON objects, each with the following properties:

Property Type Description
enabled Boolean Enabled status indicator.
multiplier Number An optional number to multiply the cloud service data values by when saving to the SolarNetwork datum stream.
propertyType String The SolarNetwork datum property classification, one of i, a, or s for instantaneous, accumulating, or status.
propertyName String The SolarNetwork datum property name.
scale Number An optional number of decimal places to round the cloud service data value to. Can omit or specify as -1 for no rounding.
valueType String The value reference, one of r or s for reference or Spel Expression. Defaults to r.
valueReference String The value reference, as discovered using the Data Values method. Datum Stream Service-specific placeholder values are supported, configured on the placeholder property of the Cloud Datum Stream associated with the mapping associated with this property. Some services also support a special * wildcard character. See the documentation for the Cloud Datum Stream Service for more information.

Here is an example that uses siteId and componentId placeholders, as well as an expression to derive a voltage property out of phase-specific voltage_* properties:

[
  {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "watts",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/W/W_avg"
  },
    {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage_a",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/PhVphA/PhVphA_avg"
    },
    {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage_b",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/PhVphB/PhVphB_avg"
    },
    {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage_c",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/PhVphC/PhVphC_avg"
    },
    {
    "enabled": true,
    "propertyType": "i",
    "propertyName": "voltage",
    "valueType": "s",
    "valueReference": "round(rms({voltage_a, voltage_b, voltage_c}), 1)"
    },
  {
    "enabled": true,
    "propertyType": "a",
    "propertyName": "wattHours",
    "valueType": "r",
    "valueReference": "/{siteId}/{componentId}/TotWhExp/TotWhExp_max"
  }
]

The response will be a list of Cloud Datum Stream Mapping Property entity objects. See Cloud Datum Stream Mapping Property list response for more information.

Cloud Datum Stream Mapping Property list

This method returns a list of Cloud Datum Stream Mapping Property entities matching an optional search filter.

GET /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties

The URL accepts the following search filter query parameters:

Property Type Description
index Number The index of a datum stream mapping property to match.
indexes Number[] A comma-delimited list of datum stream mapping property index values to match (logical OR).
offset Number Optional starting result offset. Defaults to 0.
max Number Optional maximum result count, or unlimited if not provided.

Cloud Datum Stream Mapping Property list response

The response will be a [paged results][paged-results] list of Cloud Datum Stream Mapping Property entity objects, as specified in the save method.

An example response looks like:

{
  "success": true,
  "data": {
    "totalResults": 17,
    "startingOffset": 0,
    "returnedResultCount": 17,
    "results": [
      {
        "userId": 123,
        "datumStreamMappingId": 1,
        "index": 0,
        "created": "2024-10-14 03:27:54.859495Z",
        "modified": "2024-10-14 03:27:54.859495Z",
        "enabled": true,
        "propertyType": "i",
        "propertyName": "watts",
        "valueType": "r",
        "valueReference": "/{siteId}/{componentId}/W/W_avg"
      },
      {
        "userId": 123,
        "datumStreamMappingId": 1,
        "index": 1,
        "created": "2024-10-14 03:27:54.859495Z",
        "modified": "2024-10-14 03:27:54.859495Z",
        "enabled": true,
        "propertyType": "a",
        "propertyName": "wattHours",
        "valueType": "r",
        "valueReference": "/{siteId}/{componentId}/TotWhExp/TotWhExp_max"
      }
    ]
  }
}

Cloud Datum Stream Mapping Property save

This method creates or updates a single Cloud Datum Stream Mapping Property entity. An application/json request body must be provided with the complete entity details to save.

PUT /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties/{index}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping Property to save.
index The index of the Cloud Datum Stream Mapping Property to save.

The request body accepts a Cloud Datum Stream Mapping Property JSON object with the following properties:

Property Type Description
enabled Boolean Enabled status indicator.
multiplier Number An optional number to multiply the cloud service data values by when saving to the SolarNetwork datum stream.
propertyType String The SolarNetwork datum property classification, one of i, a, or s for instantaneous, accumulating, or status.
propertyName String The SolarNetwork datum property name.
scale Number An optional number of decimal places to round the cloud service data value to. Can omit or specify as -1 for no rounding.
valueType String The value reference, one of r or s for reference or Spel Expression. Defaults to r.
valueReference String The value reference, as discovered using the Data Values method. Datum Stream Service-specific placeholder values are supported, configured on the placeholder property of the Cloud Datum Stream associated with the mapping associated with this property. Some services also support a special * wildcard character. See the documentation for the Cloud Datum Stream Service for more information.

For example:

{
  "enabled": true,
  "propertyType": "i",
  "propertyName": "watts",
  "valueReference": "/{siteId}/{componentId}/mW/mW_avg",
  "multiplier": 0.001,
  "scale": 3
}

The response will be the saved Cloud Datum Stream Mapping Property entity.

Cloud Datum Stream Mapping Property delete

This method deletes a Cloud Datum Stream Mapping Property entity.

DELETE /solaruser/api/v1/sec/user/c2c/datum-stream-mappings/{datumStreamMappingId}/properties/{index}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping Property to delete.
index The index of the Cloud Datum Stream Mapping Property to delete.

The response will be a simple success or failure message.

Cloud Datum Stream Mapping Property update enabled

This method updates the enabled status of a Cloud Datum Stream Mapping Property entity.

POST /solaruser/api/v1/sec/user/c2c/integrations/{datumStreamMappingId}/properties/{index}/enabled/{enabled}
datumStreamMappingId The ID of the Cloud Datum Stream Mapping Property to update.
index The index of the Cloud Datum Stream Mapping Property to delete.
enabled The desired enabled state to set.

The response will be a simple success or failure message.

Cloud Datum Stream

TODO

Cloud Datum Stream Poll Task

TODO

Add a custom footer

Clone this wiki locally