app.yml

The app.yml file includes the definition of your app—including store details, runtime, and functions and jobs that your app will use.

Understanding the META Section of app.yml

The META section of the app.yml describes the basic elements of your app. It includes the app id, app name, version, support info, and the deployment model for the app.

Here we use an example of a data integration app between Optimizely and Klavio. Here is the app.yml for this integration:

meta:
  app_id: klaviyo_collect
  display_name: Klaviyo Collect
  version: 0.1.0
  vendor: zaius
  summary: Collect Data From Klaviyo
  support_url: https://www.optimizely.com
  contact_email: [email protected]
  categories:
    - Marketing
  availabiity:
   - us

app_id – This is the unique identifier of your application in the OCP platform.
display_name – This is how your app's name will be displayed in the App Directory.
version – This is the version of your app that will be displayed in the App Detail page.
vendor – This is the display name of your firm or company that will be displayed on the App Detail page.
summary – This is the description of your app that will be displayed in the App Directory.
support_url – This is the support url for your app or company that is provided in the App Detail page.
contact_email – This is the email to use for questions or issues with the app.
categories – This is used to tag the app for display sorting in the app directory.
availability – This identifies where the app is going to be deployed on a global basis. The deployment options are:

##This deploys to the US only:
availability:
- us

##This deploys to both US and EU:
availability:
- us
- eu

##This deploys the app to all current available and future deployment regions:
availability:
- all

us is a required deployment target. It is not possible to deploy to other regions without also including us in your list of availability zones.

This is how the options above are displayed on the app identifier card:

Example

Below is a complete example of an app.yml file:

meta:
  app_id: sample_app
  display_name: Sample App
  version: 1.0.0
  vendor: optimizely
  summary: A sample app
  support_url: https://www.optimizely.com
  contact_email: [email protected]
  legal_url: https://optimizely.com/privacy_policy
  categories:
    - Accounting & Finance
  availabiity:
   - all

runtime: node18

environment:
  - APP_ENV_GLOBAL_SECRET

functions:
  handle_event:
    entry_point: HandleEvent
    description: Transforms incoming data into ODP events

jobs:
  historical_import:
    entry_point: HistoricalImport
    description: Performs a one-time historical import when triggered

  nightly_import:
    entry_point: NightlyImport
    # runs at midnight every night
    cron: 0 0 0 ? * *
    description: Performs a nightly import for data that isn't provided or needed in real time
    
liquid_extensions:
  generate_coupon:
    entry_point: GenerateCoupon
    description: Generates a unique coupon code
    input:
      rule:
        type: string
        required: true
        description: The coupon rule to create the coupon from
      email:
        type: string
        required: false
        description: Email address to tie the coupon code to
        
channel:
  grouping: messenger
  targeting:
    - identifier: sample_app_messenger_id
  options:
    prepare: true

Example Data Integration

This app pulls data from an ESP. The Import job can handle both the historical import and hourly pulls. The GetEspLists function allows for listing the Lists that exist in the ESP that you can import.

meta:
  app_id: esp_collect
  display_name: ESP Collection App
  version: 1.0.0
  vendor: optimizely
  summary: An app that imports contacts and activity
  support_url: https://www.optimizely.com
  support_email: [email protected]
  categories:
    - Marketing Automation

runtime: node18

functions:
  get_esp_lists:
    entry_point: GetEspLists
    description: Pulls the lists from the ESP to select which ones you want imported

jobs:
  import:
    entry_point: Import
    description: Performs a one-time historical import when triggered
    # Runs every hour
    cron: 0 0 * * * ?

Example Channel Integration

This app integrates into an SMS vendor for sending. It has the SmsCallbackHandler that gets the webhook activity that comes from the vendor. It also has all of the details about the channel, how reachability is handled and what type of identifiers are supported.

meta:
  app_id: sms
  display_name: SMS
  version: 1.0.0
  vendor: optimizely
  summary: Deliver transactional and promotional messages over SMS from any ODP campaign
  support_url: https://apps.optimizely.com/sms
  contact_email: [email protected]
  categories:
    - Channel

runtime: node18

functions:
  sms_callback:
    entry_point: SmsCallbackHandler
    description: Handles incoming messages and events about message delivery

channel:
  type: sms
  targeting:
    - identifier: phone
  options:
    prepare: false
  events:
    send: true
    delivery: true
    delivery_unknown: true
    hard_bounce: true
    soft_bounce: true
    spam_report: false
    active_actions:
      - engage
      - disengage