Terminal
Terminal/Skill
Generates buildAction.json files that configure Capacitor plugin builds for Android and iOS in OutSystems Developer Cloud.
By Ionic
Works with
npx skills add ionic-team/capacitor-skills --skill build-actions-generatorGenerates buildAction.json for ODC Mobile Libraries (Capacitor and Cordova plugins) and ODC apps targeting Android and iOS via MABS 12+.
✅ Use this skill when:
buildAction.json file for an ODC Mobile Library (Capacitor or Cordova plugin).buildAction.json file for an ODC app that requires native build configuration.AndroidManifest.xml, Gradle files, or XML resources for Android.Info.plist, entitlements, or display name for iOS.❌ Do NOT use this skill for:
This skill handles Step 1 only. Steps 2–4 require manual action.
| Step | Owner | What |
|---|---|---|
| 1. Generate JSON | This skill | Create buildAction.json with all required platform actions |
| 2. Upload JSON | Developer | Add the file to the plugin/library in ODC Studio → Resources, and then reference it Extensibility tab, creating Extensibility Settings for any variables. |
| 3. Link in Portal | Developer | If the build action has parameters, provide values in ODC Portal → Mobile Distribution tab → Extensibility settings |
| 4. Publish & test | Developer | Test a mobile build using MABS 12 (Capacitor) or later |
Output location: Two files are written to the build-actions/ folder at
the plugin root:
build-actions/buildAction.json — the build action configurationbuild-actions/README.md — human-readable documentation (see Generation Guidelines step 5)Always create build-actions/ at the top level of the directory provided
(or the current working directory if no path argument was given). Never
create it inside a subdirectory such as plugin/, android/, or ios/,
even when scanning source files that live in those subdirectories. If the
plugin repo has a nested structure (e.g. plugin/android/, plugin/ios/),
the output still goes at the repo root: build-actions/buildAction.json.
{
"variables": { }, // optional — input parameters for the build action
"platforms": {
"android": { }, // optional — Android-specific actions
"ios": { } // optional — iOS-specific actions
}
}
File naming: Use camelCase without spaces.
✅ buildAction.json, pushNotifications.json, cameraPlugin.json
❌ build action.json, Build_Action.json
At least one of android or ios must be present under platforms.
If the build action uses variables or conditions, read references/variables-and-conditions.md for full syntax and examples.
"variables" key) — typed inputs (string, number, boolean) declared by the plugin developer; consuming apps supply values via the extensibility configuration parameters block. Always include a default unless the value is genuinely required; without one the build fails if unset._ANDROID and _IOS suffixes (e.g. ADMOB_APP_ID_ANDROID, ADMOB_APP_ID_IOS). Do not merge them into a single shared variable — the developer must be able to configure each platform independently.condition field to any action entry (except displayName, productName, and appName) to conditionally skip it; for syntax and operators, see the reference file.If variables are defined, read
references/extensibility-configuration.mdfor howparametersin the extensibility configuration supplies values for variables declared inbuildAction.json. When a library and its consuming app both define build actions, the library's runs first.
If targeting Android, read references/android-build-actions.md for full action schemas and examples.
Available actions:
appName — Set the Android app name (string, no condition support)manifest — Modify AndroidManifest.xml (set attributes, merge or inject XML)gradle — Patch Gradle build files (insert or replace at target DSL path)res — Create resource files under the res/ folderjson — Modify JSON files (set or merge)xml — Modify arbitrary XML resource filescopy — Copy files, directories, or URLs into the projectcode — Add or patch native Android (Java/Kotlin) source files (source+targetDir, file+target+replace, or file+patchFile)tar — Apply tar operations on project filesIf targeting iOS, read references/ios-build-actions.md for full action schemas and examples.
Available actions:
displayName — Set app display name shown on the home screen (no condition support)productName — Set product name shown in App Store (no condition support)buildSettings — Set Xcode build settings as key-value pairsbuildPhases — Add or replace custom shell script build phasesplist — Modify Info.plist or other plist files (replace or merge entries)xcprivacy — Update PrivacyInfo.xcprivacyentitlements — Add or modify entitlements (object, not array)frameworks — Add system or custom frameworks to the Xcode projectjson — Modify JSON files (set or merge)xml — Modify arbitrary XML filescopy — Copy files, directories, or URLs into the projectstrings — Update .strings localization filesxcconfig — Update .xcconfig build configuration filescode — Add or patch native iOS (Swift/Objective-C) source files (source+compilerFlags, file+target+replace, or file+patchFile)tar — Apply tar operations on project filesPlugin root is the path argument if one was given, otherwise the current directory. Before asking the developer any questions, check for existing signals in the plugin:
input-contract.yaml exists at the plugin root, read it against the full
capacitor-plugin-generator/references/input-contract.md schema and extract
the following relevant sections:
migration.hooks (tier_1 / tier_2 / tier_3) — hook classification
for build-action derivation.dependencies.android.gradle and
dependencies.ios.{cocoapods,spm,system_frameworks} — dependency-based
actions (Gradle patches, framework entries).permissions.android and permissions.ios — permission actions
(manifest <uses-permission>, plist usage descriptions).plugin.name — for the README title.api.methods, api.types, api.events, etc.) are
irrelevant — ignore silently.plugin.xml — read references/cordova-plugin-scanning.md for the full element-to-action mapping and hook classification guide.package.json, and native source files (Java/Kotlin and Swift/Objective-C) — read references/capacitor-plugin-scanning.md for the full scanning guide.cordova-plugin-migrator ODC flow (Phase 11a),
the output (build-actions/) is written to the Capacitor plugin
directory, not the Cordova source tree. The cordova-plugin-migrator
supplies the Capacitor plugin path as the working directory or argument.Ask the developer (or infer from context):
| Native requirement | Android action | iOS action |
|---|---|---|
| Runtime permission | manifest inject <uses-permission> | plist usage description key |
| Custom URL scheme | manifest merge intent-filter | plist CFBundleURLTypes |
| Custom app attribute | manifest attrs | — |
| Native dependency | gradle replace | — |
| Push notifications | manifest merge + gradle | entitlements aps-environment |
| App groups | — | entitlements com.apple.security.application-groups |
| Custom display name | — | displayName |
| Custom native code | code inject/replace | code inject/replace |
If a hook or element does not map clearly to any action listed above, read
references/common-scenarios.mdfor patterns that appear unmappable but have correct build action equivalents.
buildAction.json)$VAR_NAME substitution for developer-controlled valuesdefault on variables unless the value is genuinely required — without one, the build fails if neither the plugin library nor the consuming app supplies the variable value in the extensibility configuration parameterscondition only when an action should be conditionally skippedmerge over inject in manifest to avoid duplicate entriescode action has platform-specific file path conventions — iOS targets
Swift/Objective-C files (e.g., App/AppDelegate.swift); Android targets
Java/Kotlin files (e.g., app/src/main/java/com/example/App.java). Do not
mix conventions between platforms.code — manifest, gradle, plist,
xml, and entitlements cover most native requirements without touching
source files. Only generate a code action when no config-level alternative
exists. If you do, use file+target+replace; never use patchFile — it
is unreliable in ODC builds. If the change cannot be expressed as a simple
string replacement, briefly tell the user the approach is not reliable in ODC
and suggest a Capacitor hook as the alternative (out of scope for this skill).
Do not explain ODC internals.tar and copy when the source file is user-supplied at runtime —
these actions are only reliable with hardcoded paths inside the plugin bundle
or external URLs. If the use case requires user-provided files, briefly tell
the user to consider a Capacitor hook instead. Do not explain ODC internals.After writing the JSON file, validate its syntax before proceeding:
python3 -m json.tool build-actions/buildAction.json > /dev/null — use
this if python3 is available.python3 is not available, try jq empty build-actions/buildAction.json.manifest/plist
entries where quotes must be escaped as \").Generate build-actions/README.md alongside the JSON. It serves as
source-control documentation for the plugin and as the primary reference for
the developer setting up ODC. Read references/readme-template.md for
the required structure, then follow the authoring rules below.
README authoring rules:
### Android or ### iOS section if that platform has no actions.## What requires additional setup entirely if all input signals were
mapped to build actions. Include it only when hooks or elements were found
that could not be mapped.## Variables section entirely if there are no variables.## ODC Setup) if the plugin has no variables — the parameters key is absent in that case and the instructions have no context.## Variables table, set Required to yes if there is no default,
no if a default exists. Leave Default as — when Required is yes.## ODC Setup should reflect actual variable names
from the generated JSON, not placeholder VAR_NAME.## What requires additional setup, set Recommended approach to:
Capacitor hook for script-type hooks — describe concretely what the hook must doODC resource for user-supplied files — tell the developer to add the file as an ODC resource in ODC Studio (Deploy Action: Deploy to Target Directory)Not supported in ODC for blockers — ODC developers have no access to the native project, so there is no manual fallback; briefly state why rework would be neededpluginConfigurations.permissions in the README if (a) the developer explicitly asked about extensibility configurations, or (b) every generated build action is exclusively a manifest <uses-permission> entry and/or a plist iOS usage description entry — meaning the entire buildAction.json could be replaced by the permissions block in the library extensibility configuration. In all other cases omit it; the reference is in references/extensibility-configuration.md.Terminal output after generating both files:
buildAction.json contents — the file write already
displays them.build-actions/. This is a candidate — review build-actions/buildAction.json before use, then validate with a MABS 12+ build and functional tests against a real mobile app. See build-actions/README.md for a summary of what this configures and ODC setup instructions."## What requires additional setup was written to the README, add one
additional line: "Some hooks or elements could not be mapped to build
actions — see build-actions/README.md for details."