For SaaS environments, a Self-Service UI is provided that enables users to independently perform STEP updates. However, if extensions are configured on a STEP environment, failure to update these extensions before updating the STEP environment may lead to compatibility issues, causing the update to fail.
Updating Custom Extensions Developed using Extension API
To ensure a successful STEP environment update with patched extensions, custom extensions must be updated first.
To update extensions developed with the Extension API, it is required to first get the necessary SDK files that allows users to execute the extension update. These SDK files can be retrieved by updating an environment, or alternatively, by raising a support ticket and requesting those to be provided by Stibo Systems support.
Updating SaaS environments with compatible extensions
After updating the extensions, the process of updating other (higher-level) environments with the new extensions can be completed by the following steps:
-
Access the Remote System Administration Swagger UI and execute the PUT /step/extensions/ endpoint with the Compatible Extensions.
Important: Do not perform a restart at this point.
-
Navigate to the SaaS Self-Service UI and proceed with the STEP update. This ensures the STEP environment is updated and will start with the newly configured extensions.
Updating an environment when compatible extensions are not available
To update your development environment (or any other non-production environment) where the extensions are already configured, complete the following steps:
-
Remove all custom extensions from the STEP application using the Remote System Administration Swagger UI. Using the PUT /step/extensions request endpoint with a blank [ ] body will allow you to remove all the extensions configured on the environment. Restart the STEP environment for the changes to take effect. However, in this scenario, since the environment also restarts during the update process, an additional restart is not necessary at this point.
Note: If extension-specific configuration properties are configured on the environment, it is also important to have those removed as well, otherwise it could still lead to the STEP environment failing to start after the update due to unrecognized configuration properties. Raise a ticket with Stibo Systems support to have such configuration properties (temporarily) removed, if applicable.
If users prefer not to perform this action on the development environment, there are two options: request the SDK files by raising a support ticket or opt for using the Release Preview Sandbox that is available via the SaaS Self-Service UI. The Release Preview Sandbox allows you to replicate one of your 'sandbox' environments for a duration of seven days on the latest update. This functionality also facilitates the process around updating extensions.
-
Next, log into the SaaS Self-Service UI and update the (development) environment.
-
Use the development environment to download the SDK files required for the extensions, and update the extensions.
-
Configure the extensions on the development environment by following the instructions in Configuring Custom Extensions on SaaS Environments topic.
Updating Custom Extensions Developed by Stibo Systems
When utilizing extensions developed by Stibo Systems, support will handle the update of the extensions for you. Users can obtain the compatible extensions (recipes) by creating an issue in the Stibo Systems Service Portal. Once Stibo Systems makes the compatible extensions available, proceed with the steps outlined in Updating SaaS environments with compatible extensions section above.
Troubleshooting Issues Related to Extensions
If a scenario occurs in which a STEP environment fails to start due to an incompatible extension, it will automatically restart with the previous (working) state of the extension configuration. This means that the STEP environment becomes available again without the new extensions / versions being installed, and it will allow you to analyze the different log files available in the System Administration portal to understand what has caused the start-up failure. The Admin Portal is accessible by going directly to https://[customer]-[environment].mdm.stibosystems.com/adminportal/ or access the Admin Portal for your system via the Start Page using the System Administration link under Resources.