This is a reference for upgrading your endpoint(s) from the v1 to v2 payload schema. Outlined below are different options for preparing and executing this upgrade. The CMD will be used to facilitate the cutover, and ultimately, your system will need to be modified to accept the data sent by Stel in a new format.
The v2 schema exposes additional information related to the measurement (i.e. unique payload identifier, device make & model, transmission time, device time), aiding in troubleshooting efforts, offering better historical context, and supporting de-duplication logic.
The new schema also provides a schema version value to better track future schema updates made by Stel to make upgrading easier. This field does not exist in the v1 schema, and it is why this in-depth upgrade guide is required.
Eventually, the v1 schema will be deprecated in favor of the v2 schema. Even though an upgrade is not currently required, it may be helpful to get started now so that teams can have as much time as they need to cutover.
Two migration paths are outlined below. Both are valid choices, and each has its own pros and cons in regards to cutover speed and data loss prevention. You are welcome to go through your own process to upgrade your endpoint, however we recommend reading through the following recommended options to have a better understanding of the impact this change has.
<aside> 💡 Please note that you can test the new/upgraded endpoint in your sandbox before upgrading your endpoint in production. This is recommended as it can prevent issues when cutting over to production and is one of the intended use cases of the sandbox.
</aside>
Create a new endpoint in tandem with your current endpoint and cutover to the new one when you are ready. This path protects against data loss, as the current endpoint is available while the new one is being setup and deployed in production.
From your system, expose a new url that will accept data in the v2 format and process the measurement as normal. Create a new endpoint in the CMD pointing to the new url with the required authentication method.
<aside> 💡 Any new endpoints created in the CMD will use the v2 schema.
</aside>
After the new endpoint is ready for production, there are two options to set it up in the CMD:
Configure the new endpoint on the same hub group that has the current endpoint configured. New measurements will start sending to both endpoints. In case the new endpoint does not work properly, the current endpoint will still receive and process the measurement as desired.
<aside> 💡 Since both endpoints will receive new measurements, your system may need to identify and mitigate duplicates if it does not already.
</aside>
Once the new endpoint has been confirmed to work, the old endpoint can be removed from the hub group.