SDK 2 Migration
Introduction
The release of SDK 2.0 adds many capabilities to the Ops Platform, but requires the Op developer to update their code to use its new API. This document will guide you through the steps necessary to convert an Op using SDK 1.x to SDK 2.0.
ops.yml and Dockerfile changes
The first change that you will need to make is to the ops.yml. Add the line
to the command definition, alongside the run key. This will signal to the Ops CLI that your Op is expecting the SDK 2.0 environment. Second, you must change the final base image in your Dockerfile; it must be one of the Ops base images provided by CTO.ai. If you’re using the JavaScript SDK, use registry.cto.ai/official_images/node:latest, otherwise use registry.cto.ai/official_images/base:latest. If you are unfamiliar with Dockerfiles, this must go on the line beginning with FROM that does not have a suffix of AS <identifier>.
The official CTO.ai images for SDK 2.0 are based on a slim install of Debian, so additional external packages are available through apt-get. The 1.x templates generated a Dockerfile that creates an Alpine image, so any custom apk commands must be replaced by their corresponding commands using apt-get.
Type Definition Changes for Typescript Users
The 1.x SDK used type definitions from the underlying user interface library, inquirer. As SDK 2.0 no longer uses Inquirer for its interface, it now incorporates these types into the SDK itself. Typescript code using SDK 1.x will need to change type imports from Inquirer into imports from @cto.ai/sdk.
User Output Changes
In SDK 2.0, the primary function for outputting to the user is ux.print. ux.print relays its argument to the user’s interface, regardless of whether the interface is a local terminal or a remote interface such as Slack. We recommend that you change as many uses as possible of sdk.log and console.log to ux.print calls, keeping in mind that ux.print takes a single formatted string rather than arbitrary arguments.
Prompt Changes
A variety of changes to the prompt API are required since the new architecture requires the prompt definitions to be JSON-serializable. These will be categorized into general changes and changes that affect only specific prompt types.
General Prompt Changes
These changes apply to all or most of the prompt definition types.
No Optional Callbacks
In the 1.x SDK, the message, default, and choices properties are allowed to be functions of the set of previous answers, rather than explicit values. To port to SDK 2.0, you’ll need to replace these functions with code outside the prompt call if you’re using them. Similarly, the when callback for conditionally executing prompts is removed in SDK 2.0
No Validation Or Transformations
The 1.x SDK permits passing validation and filter functions that check or modify the user input inside the prompt logic before returning. These are not available in SDK 2.0, but may return in a different form in later versions if needed.
No afterMessage
The afterMessage property is not used by SDK 2.0 at launch. You can replace this with a ux.print call.
Input Prompt Changes
In SDK 1.x, the input prompt type accepts empty input by default. In SDK 2 this default is switched to disallowing empty input. Set the allowEmpty field in the prompt to true if empty input makes sense.
Password Prompt Changes
The password prompt type in SDK 1.x takes a mask character to replace the typed text in the prompt. In SDK 2.0 this is unnecessary and ignored, and passwords are concealed invisibly.
List Prompt Changes
In SDK 1.x, the list prompt type can take a choices array containing Javascript objects allowing the list rows to have metadata. This is not available in SDK 2.0, but may return in a different form in later versions if needed. In SDK 2.0 it must be an array of strings.
This applies to the autocomplete and checkbox prompt types as well.
Autocomplete Prompt Changes
Earlier versions of SDK 1.x required a manual autocomplete function to be supplied to this prompt type as the source property. This is no longer available in SDK 2.0. Instead, the autocomplete functionality is built in, so you just need to pass the array of possibilities as the choices property, in the same way as in a list prompt type.
If the prompt uses the autocomplete property to pass the array, you do not need to change the prompt. This variation is supported for compatibility.
Datetime Prompt Changes
The date/time prompt is substantially changed from the form in SDK 1.x. The name of the prompt has changed from datepicker to datetime. Rather than needing a format for the date and/or time to be requested, there is a variant field that can be 'date', 'time', or 'datetime'.
For full details, check the prompt API documentation.
New async Functions
The following functions change from plain functions to async functions in SDK 2.0:
ux.spinner.startux.spinner.stopux.tableux.tree().display()
Removed Functions and Objects
The following SDK 1.x functions have been removed from SDK 2.0:
sdk.isContainer- the new SDK does not support containerless opssdk.user- this information is now kept within the SDK daemonsdk.yargs- the SDK daemon now parses arguments. Ifyargsis necessary you can just depend on it directly.sdk.inquirer- we no longer use Inquirer in the SDK.