Set up WSO2 Open Banking Accelerator on:
- WSO2 Identity Server (IS)
- WSO2 API Manager (APIM) (required for OB3, optional for OB4)
- Optional WSO2 Streaming Integrator (SI) (OB3 data publishing only)
Rules:
- Collect all inputs first.
- Run steps in order.
- Stop on first failed check/command.
- Use skip logic for optional components.
- Use idempotent checks before destructive actions.
Guardrails
- Confirm before destructive actions (scripts, keystores/truststores, overwriting configs).
- Do not ask the user to paste secrets.
- Change only the files listed in this workflow.
- Run commands one by one (do not combine all commands into one script).
Execution contract
- Do not execute any command until all required non-secret inputs are collected.
- During input collection, ask one question at a time.
- For secret values, require environment variables only (never ask to paste raw secrets).
- When a pre-check fails, stop immediately and report the exact failed check.
- For optional components (APIM/SI), skip all related steps explicitly and log the skip reason.
- Always print resolved paths before running commands there.
Input contract (collect first)
If missing, use defaults.
OB_VERSION:OB3orOB4(default:OB4)
Version-specific inputs
- If
OB_VERSION=OB3, use OB3 inputs. - If
OB_VERSION=OB4, use OB4 inputs.
Host inputs
IS_HOST: defaulthttps://localhost:9446APIM_HOST: defaulthttps://localhost:9443(required only when APIM is selected)SI_HOST: defaulthttps://localhost:9444(required only when SI is selected)
Database host inputs
DB_HOST: defaultlocalhostDB_PORT: default3306
Workspace input
WORK_DIR: absolute path used to create the setup directory (default:$pwd)
Primary workflow (do not reorder)
1. Prerequisites
- Run preflight checks:
java -version
command -v mysql
command -v curl
command -v keytool
command -v unzip
- Stop if any required tools are missing.
2. Install accelerators into base products
-
Create
<WORK_DIR>/wso2-open-banking-acceleratorandcdinto it. -
Resolve and record canonical paths after extraction:
<IS_HOME><APIM_HOME>(ifIS+APIM)<SI_HOME>(if OB3 data publishing requested)<OB_IAM_ACCELERATOR_HOME>inside<IS_HOME><OB_AM_ACCELERATOR_HOME>inside<APIM_HOME>(ifIS+APIM)<OB_SI_ACCELERATOR_HOME>inside<SI_HOME>(if OB3 data publishing)
-
A zip source is a URL if it starts with
https://; otherwise treat it as a local path. Download only for URLs. -
Extract base product zips into the current directory.
-
Unzip accelerators into corresponding base product directories.
-
Path resolution rule:
<IS_HOME>: extracted dir name starts withwso2is-and containsbin.<APIM_HOME>: extracted dir name starts withwso2am-and containsbin.<SI_HOME>: extracted dir name starts withwso2si-and containsbin.<OB_IAM_ACCELERATOR_HOME>: dir under<IS_HOME>containingrepository/conf/configure.properties.<OB_AM_ACCELERATOR_HOME>: dir under<APIM_HOME>containingrepository/conf/configure.properties.<OB_SI_ACCELERATOR_HOME>: dir under<SI_HOME>containingrepository/conf/configure.properties.
-
Verify path existence before continuing:
<IS_HOME>/bin<OB_IAM_ACCELERATOR_HOME>/bin<APIM_HOME>/binand<OB_AM_ACCELERATOR_HOME>/binonly ifIS+APIM
-
Version-specific branch:
- If
OB3, run set up IS connector. - If OB3 data publishing requested, run set up data publishing.
- If
3. Update base products and accelerators
-
Select relevant update binary by OS:
- macOS:
wso2update_darwin - Linux:
wso2update_linux - Windows:
wso2update_windows.exe
- macOS:
-
Verify the OS-specific update tool exists in each directory below.
<IS_HOME>/bin<OB_IAM_ACCELERATOR_HOME>/bin<APIM_HOME>/bin(ifIS+APIM)<OB_AM_ACCELERATOR_HOME>/bin(ifIS+APIM)<SI_HOME>/bin(if OB3 data publishing)<OB_SI_ACCELERATOR_HOME>/bin(if OB3 data publishing)
-
If missing, check for
update_tool_setup.sh(macOS/Linux) orupdate_tool_setup.ps1(Windows) in the samebindirectory. If found, run it to download the update binary, then re-verify the binary exists before continuing.
./update_tool_setup.sh
-
If the setup script is also missing, stop and tell the user their WSO2 subscription is likely missing. Ask them to contact WSO2 Online Support System to download the product or skip updates.
-
Verify the required environment variables for the update tool are set. Stop if missing:
test -n "$OB_AGENT_UPDATE_TOOL_USERNAME"
test -n "$OB_AGENT_UPDATE_TOOL_PASSWORD"
- Run the update tool in each directory:
./<WSO2UPDATE_BINARY> --username "$OB_AGENT_UPDATE_TOOL_USERNAME" --password "$OB_AGENT_UPDATE_TOOL_PASSWORD"
4. Configure MySQL database
-
Verify MySQL >= 8.0 available, stop if not.
-
Verify DB credentials are provided via environment variables. Stop if missing:
test -n "$OB_AGENT_DATABASE_USERNAME"
test -n "$OB_AGENT_DATABASE_PASSWORD"
- Verify DB credentials by connecting to the DB. Stop if invalid.
MySQL check example:
MYSQL_PWD="$OB_AGENT_DATABASE_PASSWORD" mysql -h "$DB_HOST" -P "$DB_PORT" -u "$OB_AGENT_DATABASE_USERNAME" -e "SELECT 1;"
- Download compatible JDBC driver (MySQL 8 example):
curl -L "https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/9.6.0/mysql-connector-j-9.6.0.jar" -o mysql-connector-j-9.6.0.jar
-
Place the JDBC driver JAR:
- IS: copy the driver JAR into
<IS_HOME>/repository/components/lib - APIM: copy the driver JAR into
<APIM_HOME>/repository/components/lib - SI: copy the driver JAR into
<SI_HOME>/lib(if OB3 data publishing requires DB connectivity there)
- IS: copy the driver JAR into
-
Set and verify
DB_USERandDB_PASSin<OB_IAM_ACCELERATOR_HOME>/repository/conf/configure.propertiesmatch the environment variables. Do not print the values, report onlyMATCHorMISMATCHper property. Stop on anyMISMATCH:grep -q "^DB_USER=$OB_AGENT_DATABASE_USERNAME$" repository/conf/configure.properties && echo "DB_USER: MATCH" || echo "DB_USER: MISMATCH"
Note: Use
Select-Stringon Windows.
- Update the following in
<OB_IAM_ACCELERATOR_HOME>/repository/conf/configure.properties:- DB connection properties
- Change DB name pattern from current value to
<DATE_PREFIX>_* - Hostnames for IS/APIM/SI
IS_PRODUCT=wso2is-<IS_VERSION>PRODUCT_CONF_PATH=repository/resources/wso2is-<IS_VERSION>-deployment.toml
<DATE_PREFIX> uses today's date in YYYYMMDD.
- Run IAM Accelerator scripts:
cd <OB_IAM_ACCELERATOR_HOME>/bin
./merge.sh
./configure.sh
-
If
IS+APIM, repeat equivalent configuration + scripts in:<OB_AM_ACCELERATOR_HOME>/repository/conf/configure.properties<OB_AM_ACCELERATOR_HOME>/bin(merge.sh,configure.sh)
-
If OB3 data publishing is requested, repeat equivalent configuration + scripts in:
<OB_SI_ACCELERATOR_HOME>/repository/conf/configure.properties<OB_SI_ACCELERATOR_HOME>/bin(merge.sh,configure.sh)
-
Create event-notification tables (OB4 only):
- Check if target tables already exist; skip if present.
- Run
mysql.sqlfrom<IS_HOME>/dbscripts/financial-services/event-notificationsagainst the consent DB. - Default consent DB name:
<DATE_PREFIX>_*consentdb
5. Exchange Certificates
- Follow the exchange certificates guide.
6. Start servers and verify basic health
Start order:
- IS: run the OS-specific startup script in
<IS_HOME>/bin
./wso2server.(sh|bat) start
- APIM (optional): run the OS-specific startup script in
<APIM_HOME>/bin
./api-manager.(sh|bat) start
- SI (optional): run the OS-specific startup script in
<SI_HOME>/bin
./server.(sh|bat) start
Verification checklist:
- IS, APIM, and SI hosts and ports are reachable
- No critical errors in selected components logs:
<IS_HOME>/repository/logs/wso2carbon.log<APIM_HOME>/repository/logs/wso2carbon.log(if APIM selected)<SI_HOME>/wso2/server/logs/carbon.log(if SI selected)
Completion criteria (must satisfy all applicable)
- All selected components start successfully.
- Health/port checks pass for selected components only.
- No startup-blocking or critical errors in logs after 30 seconds (e.g., ERROR|FATAL).
- Accelerator configs and DB scripts are applied for selected components.
- Certificate exchange is complete for selected components.
Failure handling
- On any failed command:
- Stop immediately.
- Report the exact command, exit code, and path.
- Do not continue until user confirms remediation.