Collect input from an app-bar action

Add a button that collects a file before invoking an app function. You need a scaffolded app, a sandbox installation, and permissions for any records the handler will read or update.

Declare the button and handler together

For the current CLI layout, put this in src/app/appbars/upload-cv.js:

export const manifest = {
  appBars: [{
    name: 'upload_cv',
    location: 'RECORD_OVERVIEW',
    label: 'Upload CV',
    actionLabel: 'Upload',
    settingsSchema: [{
      name: 'cv_file', type: 'FILE', label: 'CV', required: true,
    }],
  }],
};

export const handler = async (req, res) => {
  const body = req.body || {};
  const file = body.appBarSettingsValues?.cv_file;
  if (!file) return res.status(400).json({ message: 'Select a CV first.' });
  return res.status(200).json({ message: 'File received.' });
};

This example acknowledges the selected file. It does not parse a CV or save it to a record. Add that work using the runtime’s scoped installation token and verify the resulting record before reporting it as saved.

Read the right settings

The dialog’s values arrive in appBarSettingsValues, and its schema in appBarSettingsSchema. The top-level settingsSchema still describes the installation settings. Keep these separate when a handler needs both.

The envelope also identifies the location and available context, such as recordUuid, object, viewId, and trait. Context depends on where the user clicked; a toolbar action may not have a current record.

For a stored file key, use GET {caraerApiBase}/v2/files/?key=<key> with the installation token. Treat an already absolute file URL according to its declared file value shape; avoid inventing storage URLs.

Deploy and exercise the actual button

caraer apps validate
caraer apps push --deploy
caraer apps status

Open the sandbox installation, enable visibility in the intended location, click the button, and choose a file. Confirm the dialog, handler response, and any record changes. A ready runtime alone does not verify the button’s behaviour.

Common mistakes

Reading installation settings as dialog input, assuming every action has a record UUID, and deleting a shared bar to hide it in one installation cause confusing behaviour. Keep the bar name stable and use installation visibility to control where it appears.

See app-bar locations and iframes for other placements.