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.
The first change that you will need to make is to the
ops.yml. Add the line
to the command definition, alongside the
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
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
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
In SDK 2.0, the primary function for outputting to the user is
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
ux.print calls, keeping in mind that
ux.print takes a single formatted string rather than arbitrary arguments.
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.
These changes apply to all or most of the prompt definition types.
In the 1.x SDK, the
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
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.
afterMessage property is not used by SDK 2.0 at launch. You can replace this with a
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 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.
In SDK 1.x, the
list prompt type can take a
This applies to the
checkbox prompt types as well.
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.
The date/time prompt is substantially changed from the form in SDK 1.x. The name of the prompt has changed from
datetime. Rather than needing a format for the date and/or time to be requested, there is a
variant field that can be
For full details, check the prompt API documentation.
The following functions change from plain functions to
async functions in SDK 2.0:
The following SDK 1.x functions have been removed from SDK 2.0:
sdk.isContainer- the new SDK does not support containerless ops
sdk.user- this information is now kept within the SDK daemon
sdk.yargs- the SDK daemon now parses arguments. If
yargsis necessary you can just depend on it directly.
sdk.inquirer- we no longer use Inquirer in the SDK.