Hosting Opal Tools on Optimizely Connect Platform (OCP)

The Optimizely Connect Platform (OCP) is Optimizely's native environment specifically designed for extending its products. It offers a highly integrated and managed hosting solution for your custom Opal Tools, simplifying deployment and ensuring seamless interaction with the broader Optimizely ecosystem. OCP also allows you to publish your app in the directory, allowing Optimizely customers to easily install and use.

By the end of this module, you will be able to:

• Understand and leverage OCP as a managed hosting platform for Opal tools
• Set up and configure an OCP application
• Deploy, publish, and register Opal tools

Important Note on Hosting Flexibility: While this module focuses on the Optimizely Connect Platform (OCP) as a robust and integrated hosting solution, it's crucial to understand that your Opal Tool can be hosted anywhere you choose, as long as it has a publicly discoverable URL that Optimizely Opal can access. This includes cloud platforms like Vercel, Netlify, AWS, Azure, GCP, or even your own self-managed servers. The key requirement is that your tool's /discovery endpoint is publicly accessible.
To follow along with this walkthrough, please refer to the sample application code available in this GitHub repository: https://github.com/ZaiusInc/opal-tool-sample-app

Understanding OCP for Opal Tools

Opal Tools are implemented as OCP Functions. These functions are event-driven, meaning they are invoked by HTTP requests, typically from the Opal AI Assistant. OCP manages the underlying infrastructure, allowing you to focus solely on your tool's business logic.

Prerequisites for OCP Deployment

Before you begin, ensure you have:

• An OCP developer account.
• A configured OCP development environment, including the OCP Command Line Interface (CLI). Detailed setup instructions can be found in the OCP documentation.
• Your Opal Tool project must be initialized as a Git repository. If you downloaded a ZIP file, run git init in your app folder.

Initial Project Setup and Configuration

Get Source Code: Start by cloning the provided sample repository or downloading its ZIP file.

Register Your App in OCP: Use the OCP CLI to register your application

ocp app register

You will be prompted to provide:

• A unique App ID (use snake_case, no spaces).
• A Display Name for your app.
• Select Connect Platform as the target product.
• Choose No for the private app question if you intend to share it within your organization.

Configure app.yml: This file defines your OCP application and its functions.

• Open app.yml in your project's root directory.
• Update meta/app_id and meta/display_name to match the values you provided during registration.
• Set meta/vendor (you can find your vendor ID using ocp accounts whoami).
• Add meta/summary, meta/support_url, and meta/contact_email for the OCP App Directory listing.

Define your Opal Tool function under the functions section:

functions:
opal_tool: # This is a unique key for your function
entry_point: OpalToolFunction # The name of the class implementing your tool
description: Opal tool function # A brief description of this function

• The entry_point should be the name of the class (e.g., OpalToolFunction) that contains your Opal Tool logic. This class must extend the Function class from @zaiusinc/app-sdk (for TypeScript/JavaScript projects).
• The perform() method within your entry_point class will handle requests from Opal, including /discovery for tool metadata and specific tool execution endpoints (e.g., /tools/greeting).
• OCP functions support standard parameter types like string, integer, number, boolean, array, object.

Validate Your App: After configuring app.yml, run the validation command:

ocp app validate

This confirms your settings are correct before deployment.

Exposing the Tool Registry URL

Opal needs to know where to find your tool's discovery endpoint. This is managed through OCP's lifecycle events and settings:

• Define a configuration property (e.g., opal_tool_url) in your forms/settings.yml file.
• In your src/lifecycle/Lifecycle.ts (or equivalent for other languages), use the App.functions.getEndpoints() method during the onInstall and onUpdate lifecycle events. This retrieves the dynamically generated endpoint for your OCP function and stores it in the settings, making the URL available for Opal to consume.

Managing Multiple Tool Registries (Optional)

If your OCP app hosts multiple Opal Tools:

• Declare each new tool registry function in app.yml under the functions section.
• Implement each tool function in a separate .ts file (e.g., src/functions/MyOtherToolFunction.ts).
• Expose each registry's URL by adding corresponding parameters to forms/settings.yml and setting them in src/lifecycle/Lifecycle.ts.

Custom Configuration and Authorization (OCP-Specific)

OCP provides secure ways to handle app-specific settings and authentication:

• Custom Settings: Define custom input fields in forms/settings.xml to allow users to configure your tool within the OCP App Directory UI.
• Authentication:
  • Username/Password: Declare input fields (e.g., email, api_key) and an authorize button in forms/settings.xml. Implement validation in the onFormSubmit method of src/lifecycle/Lifecycle.ts. Access stored credentials via storage.settings.get().
  • OAuth: Add an oauth_button to forms/settings.xml. Implement onAuthorizationRequest and onAuthorizationGrant in your Lifecycle class to manage the OAuth flow. Access tokens should be stored and retrieved from OCP's secure secret storage using storage.secrets.get().

OCP Storage and Secrets

OCP offers various storage types for your app:

• Secrets store: For sensitive information (API keys, database credentials) that should not be exposed in settings forms.
• Settings store: Backs the settings form, suitable for non-sensitive configuration data.
• Key value store: General-purpose storage for simple data structures (lists, sets), high throughput, up to 400 KB per record.
• Shared key value store: To share common data between app components. Refer to OCP storage documentation for more details.

Custom Dependencies

You can add external libraries to your OCP app using your language's package manager (e.g., npm install axios for Node.js).

Logging and Notifications

• Use the logger from @zaiusinc/app-sdk for logging events (info, warn, debug). Logs are accessible in the OCP App Directory's Troubleshooting tab or via the ocp app logs command. Log levels can be changed with ocp app set-log-level.
• Use notifications from @zaiusinc/app-sdk to send notifications to the OCP Activity Log.

Customizing App Overview and Assets

• Customize your app's presentation in the OCP App Directory by editing directory/overview.md.
• Replace assets/logo.svg with your own icon (recommended size: 150 x 50 px).

Deployment to OCP

• Build and Publish: Before deploying, prepare your app for publication:

ocp app prepare --bump-dev-version --publish

The --bump-dev-version flag increases the app version in app.yml for upgrades.

• Install to Sandbox OCP Account:

ocp app install <your_app_id>@<your_app_version> <public_api_key>

• <your_app_id> and <your_app_version> are from your app.yml or the ocp app prepare output.
• <public_api_key> can be found in your OCP UI (Settings -> APIs) or via ocp accounts whoami.
• OCP handles auto-upgrades based on semantic versioning, so installation is usually a one-time step.

Registering Your Tool in Optimizely Opal

Once your OCP app is deployed and running:

• Go to your OCP account in the Optimizely UI.
• Navigate to Data Setup -> App Directory, and find your deployed app.
• In the Settings tab of your app, copy the Opal Tool URL.
• In your Optimizely Opal account, go to Tools -> Registries.
• Click Add tool registry.
• Provide a Registry Name and paste the copied Opal Tool URL into the Discovery URL field.
• Leave Bearer Token (Optional) empty unless you've configured custom bearer token authentication for your tool.
• Click Save. Your Opal Tools should now be discovered and available for use within Optimizely.
• Important: After making changes to your tool's manifest (e.g., adding new parameters or tools) and publishing a new OCP app version, remember to hit the Sync button in Opal's tool registry UI to update the configurations.