Build an app

The Optimizely Connect Platform (OCP) app development lifecycle begins in the OCP CLI, where you register and scaffold the app and then prepare your development environment.

Next, you can use the OCP CLI to validate your app configuration, prepare your app for publishing, and finally publish and install the app to your OCP account. At this point, your app displays in the OCP App Directory, and you can view the data schema it created in the Objects & Fields page of the OCP UI.

Now, you can write the code for your app, which involves defining the app settings form that anyone who installs the app uses to connect and configure the app for their needs.

You can iterate on your app build and continue to publish versions of your app to the OCP App Directory so you can see how the settings form displays and functions, and you can test the app to ensure it works as expected.

Register and scaffold the app

1. Register your app and complete the prompts to give your app a unique app ID and name, define OCP as the target product, and mark the app as shareable with other developers in your organization.

   🚧

   Important

   Ensure you choose Connect Platform as the app's target product. Your app ID must be in snake case, meaning each word is in lowercase and spaces are replaced with underscores.

   ocp app register
   

   This command returns the following prompts that you must complete:

   The app id to reserve: YOUR_APP_ID
   The display name of the app: YOUR APP DISPLAY NAME
   Target product for the app: Connect Platform
   Keep this app private and not share it with other developers in your organization? No
   

2. Scaffold the app and initialize the App Directory. The Basic Sample template contains example code to get you started (including functions and jobs), and the Empty Project template is a basic app without example code. If you use the Basic Sample template, you must replace the event examples with objects you intend to update in your OCP account. It also includes src/schema/customers.yml, which you must replace with the schema definition of the object you want to update, like src/schema/commerce_products.yml. See App versioning for help with how to version your app.

   🚧

   Important

   Do not select any of the following categories:

   • Loyalty & Rewards
   • Reviews & Ratings
   • Commerce Platform
   • Content Management
   • Offers

   ocp app init
   

   This command returns the following prompts that you must complete:

   Name of your app (e.g., My App): YOUR APP DISPLAY NAME
   ID of your app [ocp_quickstart]: YOUR_APP_ID
   Version [1.0.0-dev.1]: 1.0.0-dev.1
   App Summary (brief): YOUR APP SUMMARY
   Support URL: YOUR SUPPORT URL
   Contact email address: YOUR SUPPORT EMAIL
   Select the category for the app: YOUR APP CATEGORY
   Select a template project: Empty Project
   

3. Open it in your preferred editor and run git init to prepare the environment.

4. src/schema/my_app_commerce_product_categories.yml

   name: my_app_commerce_product_categories
   display_name: My App Commerce Product Categories
   fields:
    - name: commerce_product_category_id
       display_name: Commerce Product Category ID
       type: string
       primary: true
     - name: commerce_product_id
       display_name: Commerce Product ID
       type: string
     - name: category_name
       display_name: Category Name
       type: string
   relations:
     - name: product
       display_name: Product
       child_object: my_app_commerce_products
   
       join_fields:
         - parent: commerce_product_id
           child: commerce_product_id
   

Validate, prepare, publish, and install the app

1. Validate your app configuration by running ocp app validate in the CLI.

2. Run ocp app prepare to prepare your app for publishing.

3. Publish the app to your OCP App Directory by running ocp directory publish [email protected]. See App versioning for help with how to version your app.

4. Run ocp directory install [email protected] TRACKER_ID to install the app to your OCP account. Replace TRACKER_ID with your OCP account Tracker ID, which you can find in Data Setup > Integrations in the OCP UI. For example, ocp directory install [email protected] Z6jCndly_E2WzpvDkcKBKA.

   

   At this point, you can view your app listing in your OCP app directory (only you can view it). The app does not run any code yet, but you can view the app schema in Data Setup > Objects & Fields in the OCP UI.

Define the app settings form

OCP apps include a settings tab, which is accessible after a user installs the app. The settings tab is where you define how you want users to connect and use your app.

OCP apps support several types of authentication, including OAuth, tokens, username and password, and API keys.

The following image shows an example settings tab for an OCP app.

Manage your app settings in the src/forms/settings.yml file, which is already created as a placeholder form after you complete the previous steps. Your settings form consists of the following:

• Sections – You can have multiple sections in your form where the first section is expanded in the UI by default, and users can expand subsequent sections. You can organize sections in the forms/ folder. The following is an example of a settings form with two sections, where the second section only displays after a successful login in the first section.

  YAML

  sections:
  - key: login
    label: Login
    properties:
      - successful
    elements:
      - ...
  - key: lists
    label: Import Lists
    visible:
      key: login.successful
      equals: true
    elements:
      - ...
  

• Form elements – The different UI elements users interact with in your settings form. See Form elements for a list of form elements you can add to your settings area.

App review process

📘

Note

The app review process typically takes one to two business days to complete.

When you are ready to release your app publicly to the OCP App Directory, you must submit it to Optimizely for review.

The Optimizely App Review team invites you to a GitHub repository with the app code. When you accept the invitation, you can see the pull request and feedback from Optimizely engineers as they review your code.

📘

Note

GitHub notifies you by email about any activity on your app review's GitHub repository.

If Optimizely determines that changes are required, Optimizely submits a GitHub pull request. After you make the requested changes, run ocp app prepare in the OCP CLI again with the same version. This updates the pull request with the latest code from your app.

This review ensures your app meets design guidelines, content guidelines, and security requirements so that customers can safely use your app.

Best practices

Your app should meet the following guidelines before submitting it for review.

Security

• Your app cannot contain any secrets or credentials (access secrets in environment variables and store outside of Github in .env file).
• Your app cannot log secrets or credentials.
• The .env file cannot be part of the repository.
• Your app cannot import PII data.
• Your app cannot scan the engine code or invoke internal engine code other than through the API defined in the App SDK.
• Your app cannot execute any OS commands directly.
• Your app cannot gather, log, or send any information on how the runtime is built (OS version, folder structure, networking, ports, and so on).

app.yml

• Your app must accurately identify itself in the metadata section (app_id, display_name , and summary should clearly identify the app and its purpose).
• All URLs you define in the metadata must be valid, functioning URLs.
• Define the partner developing the app in the vendor field.

Jobs

• The perform method should perform a small amount of work (less than 60 seconds).
• The prepare method should handle initializing and resuming the job.

Logging

• Use logger for logging, not console.

src/schema

• Prefix all objects and fields that are unique to the app with the app ID.

Storage

• Your app can not store data outside of OCP (use available storage instead).
• Only store secrets in the secrets store.

Submit your app for review

Up till this point, you were working with the dev version of your app (your app version has a -dev tag). To submit your app for review, remove the -dev tag and prepare your app for publishing:

1. Change the version of your app in app.yml to a full release version by removing the -dev tag. For example, if your app version during testing was 0.0.1-dev.1, change it to 0.0.1.
2. Run the following command to create a git repository for your app review:
   Shell

   git init
   

3. Run the following command to prepare your app for publishing:
   Shell

   ocp app prepare
   

4. Enter yes to begin the app review process or no to exit in response to the following confirmation message:
   Text

   You are uploading a release version of the app. This will start a review process and the app can't be published until it is approved. Are you sure?
   

The OCP CLI starts preparing your app for publishing to the app review process. You can leave this process running in the background. When complete, the following message displays:

Build complete. Ready to be published. Your app has been sent to review. 
Once approved, use opti directory publish <appId@appVersion> to publish and release your app

Track your app review in GitHub

When you submit your app for review, you should receive an email from GitHub, inviting you to your app's repository in Optimizely-Connector-Platform-AppReview. Accept the invitation to participate in the review and receive email notifications each time Optimizely comments on your app review or requests changes.

You can communicate directly with the reviewers in GitHub throughout the review process.

Check review status in the OCP CLI

In addition to monitoring the review in GitHub, you can view your app's review status by running the following command in the OCP CLI:

ocp directory status <appReviewId@appVersion>

Open GitHub review from the OCP CLI

Run the following command in the OCP CLI to open the GitHub review in a browser window:

ocp review open <appReviewId@appVersion>

Change requests during app review

During the review, Optimizely may submit a request through GitHub for you to make changes to your app. To make the requested changes:

1. Change the version of your app in app.yml back to a dev version by adding the -dev tag. For example, if the app version you submitted for review was 0.0.1, change it to 0.0.1-dev.1.

   📘

   Note

   Maintain the same version number (for example, 0.0.1) throughout the review.

   Changing the version number creates a new review repository.

2. Make the requested changes, then test your app internally (with the -dev tag).
3. Remove the -dev tag from the version in app.yml.
4. Run the following command in the OCP CLI to resubmit your app to the existing review:
   Shell

   ocp app prepare
   

Continue monitoring the review in GitHub and making the requested changes until your app is approved.

Release your app publicly

When Optimizely approves your app, run the following command in the OCP CLI to release your app publicly:

ocp directory publish [email protected]

Now, your app is available in the OCP App Directory for all Optimizely customers.

🚧

Important

Do not run opti app prepare after your app is approved. This prepares a new version of your app which requires another review.