Configure your development environment

To build an app in Optimizely Connect Platform (OCP), you need:

• An OCP developer account
• The OCP command-line interface (CLI)
• Your preferred integrated development environment (IDE)

To access the OCP CLI, you must have an OCP developer account. Then, you can use the OCP CLI to manage your app throughout the build process, from scaffolding the app structure to publishing the app to the Optimizely Data Platform (ODP) App Directory. Write the code for your app in TypeScript using your preferred IDE (for example, Visual Studio Code.

Request an OCP developer account

To begin working with OCP, sign up for an OCP developer account using one of the links below:

• Tech partner – Use this sign-up form if you are a company that has your own software that you want to integrate with ODP.
• Solution partner – Use this sign-up form if you want to create a third-party app in OCP.

During onboarding, you are given one of two roles:

• Developer – Allows you to run all commands in the OCP CLI except for those that let you publish your app to the public in the ODP App Directory.
• Publisher – Gives you all the same access as the developer role, with the addition of being able to publish apps to the public in the ODP App Directory.

Configure the OCP CLI

Develop, manage, and publish an OCP app using the OCP CLI. You can configure the OCP CLI on either a Mac/Linux machine or a Windows machine. Skip directly to the section that pertains to your environment.

Prerequisites

• An OCP developer account.
• The API key from your invitation email.
• Node.js 18 JavaScript runtime environment. Find your platform-specific installer here, or use your preferred Node version manager for the install.
• Yarn; find global install instructions for Yarn here. If you are on Windows, we suggest installing Yarn through Corepack, as described here.

  🚧

  Important

  OCP requires Yarn 1 (classic). Make sure you have the supported version installed (yarn -v).

• The OCP CLI requires Git to build an app. Find global install instructions for Git here.

  📘

  Note

  If you are not planning to build an app, you can skip the Git install.

Configure the OCP CLI for Mac/Linux

1. Run the following command to make a .ocp directory:

   Shell

   mkdir ~/.ocp (home dir)
   

2. Using the API key you received during onboarding, create the credentials file in the .ocp directory:

   Shell

   echo '{"apiKey": "<value-from-invitation>"}' > ~/.ocp/credentials.json
   

3. Run the following Yarn command to install the OCP CLI:

   Shell

   yarn global add @optimizely/ocp-cli
   

4. Set your PATH variable:

   Shell

   export PATH="$(yarn global bin):$PATH"
   

Configure the OCP CLI for Windows

📘

Note

The following instructions are for PowerShell.

1. Run the following command to make a .ocp directory:

   PowerShell

   New-Item -Path "~/.ocp" -Name "home dir" -ItemType "directory"
   

2. Using the API key you received during onboarding, create the credentials file in the .ocp directory:

   PowerShell

   Write-Output '{"apiKey": "<value-from-invitation>"}' | out-file "~/.ocp/credentials.json" -encoding utf8
   

3. Run the following Yarn command to install the OCP CLI:

   PowerShell

   yarn global add @optimizely/ocp-cli
   

4. Ensure the value returned from yarn global bin is on your path:

   PowerShell

   yarn global bin
   

   📘

   Note

   The output should look similar to the following:

   PowerShell

   C:\Users\[YOUR_USERNAME]\AppData\Local\Yarn\bin
   

   If it does not, follow these instructions to set your Path variable.

Test your OCP CLI configuration

Verify your OCP CLI configuration by running the following command:

ocp accounts whoami

The results should look similar to the following:

$ ocp accounts whoami
id: e1006b36-183e-4951-912c-416012f5a882
email: [email protected]
role: developer
githubUsername: jonhsmith
accounts:
  - 7b5d1518a0be
personal_apps: []
vendor: mycompany
vendor_apps: []

OCP CLI help command

Commands are grouped into namespaces:

$ ocp -h
Usage: ocp <command>

Namespaces: (`<namespace>` -h, --help for additional help)
  accounts       
  app            
  availability   
  directory      
  env            
  jobs           
  review

Run the help command, -h or --help, to list commands in a namespace, for example:

$ ocp app -h
Usage: ocp app <command>

Commands:
  init       Create a new app project                                            
  logs       Fetch app logs
  package    Prepare a package for manual upload                                 
  prepare    Validate, package, upload and build an app to prepare for publishing
  register   Register an app version                                             
  validate   Validate an app locally                                             

ocp <command> -h, --help for help on specific commands

Adding the help context on a command displays documentation for the command with all available options, for example:

$ ocp app prepare -h
Usage: ocp app prepare [<path>] [--noProgress | --no-progress] [--upgradeDeps | --upgrade-deps] [--publish] [--usePreviousAppEnvValues | --use-previous-app-env-values]
                [--bumpDevVersion | --bump-dev-version]

Parameters:
  path   The root directory of the app

Flags:
  --noProgress, --no-progress                                Don't display any progress indicators                                                                             
  --upgradeDeps, --upgrade-deps                              Automatically update dependencies                                                                                 
  --publish                                                  Automatically publish if the upload is successful                                                                 
  --usePreviousAppEnvValues, --use-previous-app-env-values   Use app env values (.env file) from the previous version of the app. Any values in local .env file will be ignored
  --bumpDevVersion, --bump-dev-version                       Bump dev version before building. Allows quickly testing dev versions

OCP CLI commands

The table below lists all available OCP CLI commands with their parameters and descriptions.

Additional flags/options for OCP CLI commands

You can append various flags/options for some of the OCP CLI commands, listed below.

ocp app logs

• --tail – Tails the logs.
• --appId
• --buildId
• --appVersion
• --trackerId
• --jobId
• --installId
• --from – A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m for 5 minutes). Default is 24h.
• --to – An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m for 5 minutes).
• --search – String to search for in log messages. Can be specified multiple times.
• --availability or -a – The availability region that will be targeted (default is US).

ocp app prepare

• --noProgress or --no-progress – Do not display any progress indicators.
• --upgradeDeps or --upgrade-deps – Automatically update dependencies.
• --publish – Automatically publish if the upload is successful.
• --usePreviousAppEnvValues or --use-previous-app-env-values – Use app env values (.env file) from the previous version of the app. Any values in the local .env file will be ignored.
• --bumpDevVersion or --bump-dev-version – Bump dev version before building. Allows you to quickly test dev versions.

ocp app validate

• --noProgress or --no-progress – Do not display any progress indicators.
• --upgradeDeps or --upgrade-deps – Automatically update dependencies.

ocp directory unpublish

• --force or -f
• --noProgress or --no-progress
• --availability or -a – The availability region that will be targeted (default is US).

ocp directory list

• --allStatuses – Includes all statuses. The stopped status is not included by default.
• --availability or -a – The availability region that will be targeted (default is US).

ocp directory upgrade

• --toVersion or -v – The desired version (for example, 1.0.0).
• --availability or -a – The availability region that will be targeted (default is US).

ocp jobs list

• --version – Specific versions to filter by.
• --trackerId – Specific Tracker IDs to filter by.
• --function – Specific job function to filter by.
• --status – Specific job status to filter by. Possible values: PENDING, SCHEDULED, RUNNING, COMPLETE, ERROR, TERMINATED.
• --minDuration – Show jobs that have been running longer than the given duration (for example, 5m = 5 minutes).
• --sortBy – Column to sort the jobs by. Possible values: id, function, trackerId, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default column to sort by is updatedAt.
• --sortDirection – Sort resulting jobs in ascending or descending order. Possible values: asc or desc. The default sort direction is asc.
• --limit – Number of jobs to list. The default is 50.
• --columns – Columns to display. Possible values: id, version, function, trackerId, trigger, status, error, createdAt, triggeredAt, scheduledAt, terminatedAt, updatedAt, duration. The default columns are id, version, function, trackerId, status, updatedAt.
• --from – A start time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes). The default time value is 24h.
• --to – An end time as an ISO string, an epoch timestamp, or relative string (for example, 5m = 5 minutes).
• --availability or -a – The availability region that will be targeted (default is US).

ocp jobs trigger

• --parameters – Parameters to pass to the job.
• --availability or -a – The availability region that will be targeted (default is US).