Skip to main content

HTTP V1 Integration

note

HTTP is a legacy V1 integration type. We recommend HTTP_V2 for every new integration: see HTTP Integration. To move an existing HTTP integration, see Migrate from V1 to V2.

Overview​

Configure a legacy HTTP integration in TEKTELIC KONA Core Network Server. The integration sends the uplinks of an application to your server as HTTP requests, and accepts downlinks from your server. Use this guide to maintain an existing V1 setup, or when your server can only read the V1 format.

KONA Core still lists HTTP in the Type list of the Add Integration dialog, without a deprecation mark. confirm the official deprecation status of the V1 integration types and any end-of-support date. The UI shows no deprecation mark, and Swagger doesn't mark the V1 downlink operation as deprecated.

Before you start​

  • Role: Customer administrator, or Sub-Customer administrator for an application assigned to your Sub-Customer. User roles open integrations read-only. See Users, Roles & Permissions.
  • Subscription plan: room for 1 more integration. See Subscription Plans & Limits.
  • Application: an application with the devices whose data you want to forward. See Manage Applications.
  • V1 data converter: a data converter of a V1 type: Custom or a preset type, such as Tektelic Home Sensor. A Custom v2 converter doesn't work with HTTP. See Payload Converters Overview.
  • Your server: an HTTP endpoint that accepts requests from KONA Core, reachable from the internet. It receives HTTP POST requests with JSON containing payloadMetaData and the converter's payload.

Steps​

  1. In the side menu, select Applications.

  2. In your application's row, select the Manage integrations icon. You can also select the application and then Manage integrations in its details panel. The application's integrations page opens, titled with the application name and Integrations.

  3. Select Add Integration (the + icon). The Add Integration dialog opens.

  4. Enter a Name. The name is required.

  5. In Type, select HTTP. The HTTP fields appear, with Port set to 8080, Base path set to / and Authentication method set to No authentication.

  6. In Data converter, select your V1 converter. The list shows only V1 converters, such as the preset types.

    Data converter list of an HTTP integration, with V1 preset converters

  7. Leave HTTP URL path as it is. The field is read-only and shows /api/v1/integration/http/. It is the path to which your server sends downlinks. KONA Core generates the integration-specific key when you create the integration. Copy the complete path from its details.

  8. Enter the Application address (IP or name without http or https prefix): the IP address or domain name of your server, for example app.example.com. Don't enter http:// or https://.

  9. Enter the Port of your server, from 0 to 65535. The default is 8080.

  10. Enter the Base path: the path of your endpoint on the server. The default is /.

  11. Select Enable HTTPS. We recommend HTTPS, so the data is encrypted on its way to your server. Leave it cleared only for a server without TLS in a closed test network.

    Add Integration dialog with the HTTP type and example values

  12. In Authentication method, select how KONA Core signs in to your server. We recommend Basic authentication for a server on the internet. Then enter the Username and Password that your server expects. No authentication is the default.

  13. Optional: under Request headers, select Add for each header that your server needs. Enter its Key and Value, for example an API token header.

  14. Optional: under CA certificate, Client certificate and Client private key, select Upload certificate from file to add certificates. Add them only if your server uses its own CA, or requires a client certificate. confirm the accepted certificate file formats.

  15. Leave Send empty payload cleared, unless your server needs uplinks without data, for example to track that a device is alive.

  16. Under Allow messages with ports, keep Allow all ports selected. To forward only some ports (FPort), clear Allow all ports and enter each port from 0 to 255.

  17. Under Retry scheme, keep the default delays 5 min, 30 min and 1 h. Select more steps, up to 48 h, if your server can be offline for longer. The delays apply after a failed delivery, and changing them doesn't cancel retries that are already scheduled.

    Lower part of the Add Integration dialog, with certificates, filters and Retry scheme

  18. Select Add. The integration appears in the list, with HTTP in the Type column.

Your server sends a downlink as an HTTP POST request to KONA Core, at the HTTP URL path of the integration. The V1 request body has these fields:

FieldContent
devEUIThe DevEUI of the target device.
dataA JSON-encoded string for the V1 encoder. The default encoder expects an object with params.data (Base64 payload) and params.port inside this string.
confirmedtrue for a confirmed downlink.
msgIdYour downlink identifier, shown in the device's Downlink queue.

The integration's data converter runs its encoder and adds the downlink to the device's downlink queue. For the request and its responses, see Process downlink v1 in the API Reference.

Check the result​

  1. On the application's integrations page, check that the integration shows HTTP in the Type column and your converter in the Data converter column.
  2. Select the integration. In the Integration details panel, check that HTTP URL path ends with the routing key.
  3. Wait for the next uplink of a device in the application. Check that your server receives a request at the Base path you entered.
  4. In the integration's row, select Show UL delivery statistics. The Delivered count grows with each uplink that your server accepts. For the other statistics, see Integration Monitoring.

Troubleshooting​

SymptomLikely causeWhat to do
Your converter isn't in the Data converter list.The converter is a Custom v2 converter. HTTP lists only V1 converters.Use HTTP_V2 with the v2 converter: see HTTP Integration.
Your server receives nothing.Application address (IP or name without http or https prefix) starts with http://, or the Port or Base path is wrong. Or your server rejects the request, for example because of Basic authentication or Enable HTTPS.Check each field against your server. Check your server's log for requests from KONA Core. Select Show retry statistics to see deliveries waiting for a retry.
Data arrives minutes or hours late.Your server didn't accept an earlier delivery, so KONA Core retries by the Retry scheme.Check that your server answers each request. See Integration Monitoring.

Still stuck? A Sub-Customer contacts their Customer, a Customer contacts their Provider, and a Provider contacts TEKTELIC Support. Send the application and integration names, the DevEUI of an affected device, the time in UTC, the exact error message and a screenshot.