Senet to ThingPark API wrapper legacy deprecated

This documentation defines how the Senet to ThingPark API wrapper can be used to manage devices and base stations provisioned in ThingPark, using the legacy Senet signature.

Important note

The Senet APIs are now deprecated, this wrapper provides customers with a temporary backward-compatible approach. Nevertheless, Netmore strongly recommends integrating with the native ThingPark APIs as soon as possible.

Domain mapping

To use the API wrapper, the Senet endpoint path should be preceded by the ThingPark hostname.
For instance, in North America, the ThingPark hostname is thingparkenterprise.us.actility.com, so the full endpoint path to retrieve the list of base stations becomes GET https://thingparkenterprise.us.actility.com/rest/integration/bstn/details.

Authentication

Clients authenticate with the wrapper through API keys, then the wrapper internally maps the customer API key to the ThingPark service account.

caution

New keys should be issued after the migration from Senet to ThingPark. Contact the Netmore support team if you have not yet received your new API keys.

Base station management

To allow backward compatibility when deploying base stations (for example when setting the location or name or querying the BS list by API, the wrapper supports the following endpoints from the legacy Senet API:

• POST /rest/integration/bstn/deploy
• GET /rest/integration/bstn/details

All the other legacy network management endpoints supported by Senet are not supported in this wrapper.

note

Any endpoint used to provision new base stations is out of scope for this wrapper. The native ThingPark APIs should be used in this case. For more information, see the Tutorial.

Mapping POST /rest/integration/bstn/deploy

The wrapper supports updating the base station metadata in ThingPark, such as the name, location and static address.
The legacy Senet endpoint is documented here.

However, due to data model differences, the mapping of this endpoint has the following limitations:

• radius information cannot be stored in ThingPark.
• height is stored as adminAlt in ThingPark, this field indicates the height above the sea level, not the height above ground. The wrapper manages the unit conversion between feet and meters.

Mapping GET /rest/integration/bstn/details

The wrapper supports retrieving the list of base stations registered under the customer account.
The legacy Senet endpoint is documented here.

Notes about query mapping

Senet query	Notes
status=any	Returns all base stations under the customer account.
status=alert	Returns base stations with at least one uncleared, unacknowledged alarm.
status=connIssue	Returns base stations with backhaul connection issues. RF_ERROR is not included.

Notes about response mapping

Senet field	Transformation
alertLevel	No reliable mapping is defined: alertLevel describes alert configuration, not current alarm severity. The field is not returned.
location	{ latitude, longitude } from the administrative location. Null when locationType != 1.
gpsLocation	Null when locationType != 2, meaning that no embedded GNSS location is available from the base station.
gpsAltitude	Null when locationType != 2, meaning that no embedded GNSS altitude is available from the base station.
height	Altitude above sea level. The value set through POST /rest/integration/bstn/deploy is returned as-is.
deltaTime	No equivalent clock-delta information is available in ThingPark. The field is returned as 0, or null according to the applicable response policy.

The following fields are omitted from the response because they do not have an exact match in the ThingPark data model:

• radius
• antennaHeight, because the related ThingPark field is associated with the antenna object rather than with the base station itself
• channelConfig, because the channel configuration is defined by the RF Region in ThingPark

Device management

The wrapper supports legacy Senet device-management operations for sending downlinks, exporting devices, registering and activating devices, updating device information, deactivating devices, and checking the status of bulk operations.

The following endpoints are supported:

• POST /rest/integration/device/sendmsg
• GET /rest/integration/device/csvExport
• GET /rest/integration/device/jsonExport
• POST /rest/integration/device/register
• POST /rest/integration/device/registerandactivate
• POST /rest/integration/device/activate
• POST /rest/integration/device/deactivate
• POST /rest/integration/device/update
• GET /rest/integration/device/status

The following legacy endpoints are not supported:

• GET /rest/integration/mcastStatus
• POST /rest/integration/device/activateOne
• POST /rest/integration/device/deactivateOne
• GET /rest/integration/device/getmsgs
• POST /rest/integration/device/clearmsgs
• POST /rest/integration/device/exportAbp

Mapping POST /rest/integration/device/sendmsg

The POST /rest/integration/device/sendmsg endpoint enqueues an application downlink for one LoRaWAN device.

The wrapper supports:

• confirmed and unconfirmed downlinks
• LoRaWAN application ports from 1 to 225
• clearing the existing device downlink queue before adding the new message, using clear=true
• message validity configured through timeoutMinutes

The payload supplied in pdu must be hexadecimal. It is passed to ThingPark for transmission to the device.

Due to platform differences, the following limitations apply:

• Ports from 226 to 254 are rejected with HTTP 400 because ThingPark supports application ports only from 1 to 225.
• The per-request class parameter is ignored. Downlink scheduling uses the class defined by the device profile in ThingPark.
• The per-request immediate parameter is ignored. Equivalent downlink timing behavior, when required, is configured on the device's network subscription and cannot be changed for an individual request.
• The returned msgId is provided for response compatibility only. It cannot be used with getmsgs or clearmsgs, which are not supported by this wrapper.

Mapping GET /rest/integration/device/csvExport

The GET /rest/integration/device/csvExport endpoint exports all matching devices as CSV. The wrapper retrieves the complete result set, including results that span multiple ThingPark pages.

The following filters are supported:

Senet query parameter	Behavior
fields	Selects and orders the output columns.
state	Filters devices by the supported lifecycle state. Use ALL to disable state filtering.
contractId	Filters devices by the corresponding network subscription.
devEuis	Filters by a comma-separated list of DevEUIs.
appEui	The customer account is determined by the API key. A supplied value does not select another customer account.
psrDays	Ignored because equivalent per-day packet success rate history is not available through this mapping.

If fields is omitted, the default columns are devEui, contract, tags, state, lastHeardFrom, and joinEui.

The supported device states are:

• REGISTERED
• DEACTIVATED
• ACTIVATED
• JOINED

The following export limitations apply:

• activationDate and deactivationDate are returned empty because equivalent timestamps are not available through this mapping.
• Packet success rate fields requested through psrDays are returned empty.
• Requested fields for which no equivalent ThingPark value exists are returned empty.

Mapping GET /rest/integration/device/jsonExport

The GET /rest/integration/device/jsonExport endpoint provides the same device selection, filtering, lifecycle-state handling, and limitations as csvExport, but serializes the result as JSON.

The response contains metadata describing the export request and a data array containing the exported devices. Device tags are returned as an array. Fields without an equivalent ThingPark value, including activationDate and deactivationDate, are returned as null.

Mapping POST /rest/integration/device/register

The POST /rest/integration/device/register endpoint creates OTAA or ABP devices without activating their network subscription. The resulting devices remain suspended until they are activated.

For OTAA devices, the wrapper supports:

• devEui
• appKey
• device-profile selection through profId and the supplied device information
• optional joinEui
• latitude and longitude
• metadata
• tags

For ABP devices, the wrapper supports:

• devEui
• devAddr
• nwkSKey
• optional appSKey
• device-profile selection
• latitude and longitude
• metadata
• tags

caution

For ABP registration, both devAddr and nwkSKey are mandatory. A request missing either value is rejected with HTTP 400.

A supplied contractId is not applied during registration. The network subscription is attached when the device is activated.

Mapping POST /rest/integration/device/registerandactivate

The POST /rest/integration/device/registerandactivate endpoint creates OTAA or ABP devices and immediately attaches their network subscription.

The supported device fields and ABP requirements are the same as for register. In addition, contractId must identify a valid network subscription. If it is missing or cannot be resolved, the request is rejected with HTTP 400.

Mapping POST /rest/integration/device/activate

The POST /rest/integration/device/activate endpoint activates an existing registered or deactivated device by attaching the network subscription identified by contractId.

The wrapper assumes OTAA by default. To activate an ABP device, the caller must supply the undocumented actType=ABP query parameter.

The request may also update the following information during activation:

• device-profile assignment, when applicable
• latitude and longitude
• metadata
• tags

The device must already exist, and contractId must identify a valid network subscription. Otherwise, the request fails with HTTP 404 or 400, respectively.

Mapping POST /rest/integration/device/deactivate

The POST /rest/integration/device/deactivate endpoint deactivates an existing device by detaching its network subscription. Once suspended in ThingPark, packets from the device are ignored by the network server.

The wrapper assumes OTAA by default. To deactivate an ABP device, the caller must supply the undocumented actType=ABP query parameter.

The device must already exist. Parameters that are not required to identify the device, including appEui, joinEui, contractId, and profId, do not affect the deactivation.

Mapping POST /rest/integration/device/update

The POST /rest/integration/device/update endpoint updates supported mutable attributes of existing devices. The update does not change the device's activation state or network subscription.

The wrapper assumes OTAA by default. To update an ABP device, the caller must supply the undocumented actType=ABP query parameter.

The wrapper supports updating:

• OTAA appKey
• OTAA nwkKey, when applicable to the device configuration
• latitude and longitude
• metadata
• tags

Device-profile-related values supplied through profId, devType, devClass, or fwVer are not applied by this endpoint.

Key updates through this endpoint apply only to OTAA devices. The endpoint does not expose the ABP session-key fields required to update an ABP device's keys.

Tag operations

When tags are supplied, tagsOperation is required and supports the following values:

tagsOperation	Behavior
REPLACE	Replaces the complete tag set with the supplied tags. An empty set clears all tags.
APPEND	Adds the supplied tags to the device's current tag set.
DELETE	Removes the supplied tags from the device's current tag set.

The effective supplied set combines device-level tags and request-level tags.

Mapping GET /rest/integration/device/status

Device registration, activation, deactivation, and update operations are processed asynchronously. Their initial responses provide a reqId. Use the GET /rest/integration/device/status endpoint to poll the corresponding job.

The wrapper can return the following job states:

• QUEUED
• RUNNING
• DONE_SUCCESS
• DONE_FAILED

The response includes completion percentage, operation counters, and available per-device error messages.

Some legacy Senet job states have no equivalent in ThingPark and are not returned. These include setup, paused, resumed, canceled, and removed states.

note

Job status remains available only while the corresponding ThingPark notification is retained. Poll the status endpoint after submitting a bulk operation and store any result required for later reference.

Asynchronous operations and error handling

The following endpoints use asynchronous processing:

• register
• registerandactivate
• activate
• deactivate
• update

After an accepted request, use the returned reqId with GET /rest/integration/device/status to retrieve progress and per-device results.

caution

The callback field is not supported: the wrapper never pushes job completion to a caller-supplied URL. Poll GET /rest/integration/device/status to obtain the job outcome.

The wrapper uses the following general HTTP status mapping:

HTTP status	Meaning
400	Invalid request or unsupported field value.
403	Authentication or authorization failure.
404	Requested device or job not found.
501	The requested operation or semantic mapping is not supported.
500	Internal processing error.

For bulk requests, validation or processing errors can be reported at job level through the status response rather than in the initial acceptance response.