Lifecycle of an app in OCP
The lifecycle is how you manage all the stages of an app. It includes the following:
App templates generated by ocp app init contains a skeleton of lifecycle methods. Add any logic your application needs there.
App installation
When an app is installed in an OCP account, the onInstall method is called. The method should contain any logic that is required to initialize the app, for example
- Initialization of key value storage.
- Registering webhooks in third-party services.
- Performing dynamic OCP schema amendments through the API (declarative schema changes are performed automatically by OCP before the method is called).
Settings form submission
One of the core components in creating your app is interacting with the settings.yml, which involves handling the actions and being able to validate keys or communicate toasts back into the OCP application.
The following is a sample settings.yml and the associated onSettingsForm from the app 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: client_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: falseonSettingsForm
Each time the form is submitted, you can handle interactions with the form and also set variables for use in the form to enable new sections.
import {Vendor} from '../lib/Vendor';
...
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);
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.');
}
}Authentication
onAuthorizationRequest and onAuthorizationGrant are called as part of the authorization process initialized by clicking an OAuth button element type in the app settings form. See OAuth authentication for details.
App upgrades
When an app is upgraded to a new version, by an auto-upgrade or a manual upgrade, OCP calls the following three lifecycle methods:
- onUpgrade – This method is called after declarative schema changes are performed by OCP. Use it to perform dynamic schema changes through the API.
- onFinalizeUpgrade – This method is called after webhook URLs are created for all new functions in the version. Use it to register webhooks in a third-party service if needed.
- onAfterUpgrade – This method is called after the upgrade is completed. Use it to trigger any required one-off jobs.
Keep in mind the upgrade is not necessarily from the previous most recent version. The previous version of the app is provided in the onUpgrade method attribute.
App uninstallation
When an app is uninstalled from an OCP account, OCP calls the onUninstall lifecycle method. The method should contain the logic to clean up after the app is uninstalled.
This might include invalidating authentication tokens in third-party services, removing resources from third-party services, and so on.