Skip to main content

Device Onboarding

In order to onboard a customer to Residential Flex (formerly known as SmartFlex), they must register a device with Kraken.

📣 Note: SmartFlex Onboarding does not handle tariff switching. If you want the customer to be on a specific tariff, you will need to handle this separately.

Residential Flex's onboarding journey is implemented as an "onboarding wizard". Once an onboarding wizard has been started (using the mutation startSmartFlexOnboardingWizard which is explained further below), it should be continuously fetched to retrieve the currentStep. The currentStep will indicate what the user needs to do (if anything) in order to proceed to the next step of the onboarding journey.

The onboarding journey is considered "complete" when the currentStep returns null.

Onboarding Wizard​

To onboard a device, the user must progress through the onboarding wizard by fetching and completing the current onboarding step until the current step returns null, signifying a successful onboarding.

Start onboarding wizard​

To begin a new onboarding journey, you can use the following mutation:

Start a re-authentication wizard​

If a device needs to be re-authenticated, you can start a re-authentication wizard using the following mutation:

Cancel onboarding wizard​

To cancel an onboarding journey, you can use the following mutation:

📣 Note: cancelling an onboarding wizard will not delete a device that has already been registered. If you want to delete a device, you will need to use the DeauthenticateDevice mutation.

If you don't want to cancel an onboarding wizard, you can also reverse the onboarding step by calling the mutation for that step with a new selection. This will set the new option as the selected option and reset the current step to that step. Note: not all steps are reversible, so this won't work for all steps.

Fetch onboarding wizard(s)​

This is useful for:

  • Polling the current step, e.g. in the case of waiting for DeviceRegistration or WaitForTransition to complete.
  • Returning a user to an onboarding wizard if they leave it.

Onboarding Step​

The step order is dynamic, so when fetching the current step the query must be ready to accept any step type.

A few important points:

  • The currentStep field in the smartflexOnboardingWizards query will return the current step of the onboarding journey.
  • If you want to go back to the previous step (reversing a step) and select a different option, you should call the mutation for that step with the new selection. This will set the new option as the selected option and reset the current step to that step. For example, if you have already selected a vehicle make and you are now at the SelectVehicleVariant step, but you want to change the vehicle make, you should call the selectVehicleMakeForSmartFlexOnboarding mutation with the new make. This will reset the current step to the SelectVehicleMake step and set the given option as the selected make. You will now get a new instance of the SelectVehicleVariant step with the variants filtered to only those that match the selected make.
  • Not all onboarding steps are reversible. For example, device registration step is not reversible.

An example of how this could look is as follows (note: this example does not include all possible step types):

Most steps have their own mutation that must be called in order to complete the step and enable the user to move to the next step.

Proceed to the Device Type pages for more detailed information on the individual onboarding steps.