Lifecycle

The basics

The Lifecycle is how you manage all the stages of an app:

Install
Settings
Form submission
Upgrades
Uninstalls

Form submission

One of the core components in creating your app is interacting with the settings.yml. Handling the actions and being able to validate keys or communicate toasts back into the OCP application.

Here is a sample settings.yml and the associated onSettingsForm from the Lifecycle that handles the interactions from it.

settings.yml

sections:
  - key: auth
    label: Authenticate
    properties:
      - authConfirmed
    elements:
    - type: secret
      key: client_id
      label: Client ID
      help: Get your Client ID from Vendor
    - type: secret
      key: client_secret
      label: Client Secret
      help: Get your Client Secret from Vendor
    - type: button
      label: Authorize
      style: primary
      action: authorize #<-- action passed in
      disabled:
        key: advertiser_id
        empty: true
  - key: config
    label: Configuration
    properties:
      - canImport
    disabled:
      key: auth.authConfirmed
      equals: false
    elements:
    - type: toggle
      key: winback
      defaultValue: true
      label: Winback
      help: Toggle to send Winback segment to Vendor (engaged, winback, churned)
    - type: toggle
      key: order_likelihood
      defaultValue: true
      label: Order Likelihood
      help: Toggle to send Order Likelihood segment to Vendor (Extremely Likely, Very Likely, Likely, Unlikely)
    - type: toggle
      key: discount_affinity
      defaultValue: true
      label: Discount Affinity
      help: Toggle to send Discount Affinity segment to Vendor (Always, Sometimes, Never)
    - type: button
      label: Save
      action: save #<-- action passed in
      style: primary
    - type: button
      label: Start Initial Import
      action: import #<-- action passed in
      disabled:
        key: canImport
        equals: false

`onSettingsForm`

Each time the form is submitted you can handle interactions with the form and also set variables for use in the forms for enabling new sections.

import {vendor} from '../lib/Vendor.js'
  
  ...
  
  public async onSettingsForm(
    section: string, action: string, formData: App.SubmittedFormData
  ): Promise<App.LifecycleSettingsResult> {
    const result = new App.LifecycleSettingsResult();
    const vendor = new Vendor();
    try {
      switch (action) {
        case 'authorize': //<-- switching on the action from above
          try {
            await vendor.validateAuth();
            formData.authConfirmed = true; //<-- setting a variable for use in settings.yml
            await storage.settings.put(section, formData); //<-- saving form data
            result.addToast('success', 'Authorized');
          } catch (e) {
            logger.error('issue authenticating', e);
            result.addToast('warning', 'Could not Authenticate, please validate your information is correct');
          }
          break;
        case 'save':
          try {
            await vendor.createObjects(formData);
            formData.canImport = true;
            await storage.settings.put(section, formData);
            result.addToast('success', 'Ready to Import');
          } catch (e) {
            logger.error('Issue creating objects', e);
            result.addToast('warning', 'Could not create audiences');
          }
          break;
        case 'import':
          logger.info('Starting Job');
          await App.jobs.trigger('nightly_export', {}); //<-- starting a Job
          result.addToast('info', 'Sync Started');
          break;
      }
      return result;
    } catch (e) {
      logger.error('Issue:', e);
      return result.addToast('danger', 'Sorry, an unexpected error occurred. Please try again in a moment.');
    }
  }