Learning the OAA Runner Framework: Series Overview

Calvin sits at a towering pile of computer manuals labeled CONFIG and YAML, looking determined. Hobbes leans against the stack reading one upside-down, looking amused.

Welcome to the Learning the OAA Runner Framework series. This is a hands-on series of step-by-step tutorials for building identity integrations with oaa-runner. You will build real integrations against live APIs, starting with a simple CSV file and advancing through REST API connections, multi-system integrations, and cross-system identity linking.

What you’ll need: A working oaa-runner installation and a terminal. No prior experience with oaa-runner is required, but you should be comfortable editing YAML files and running shell commands.

Pre-work checklist

Complete these before starting:

  • Python 3.9+ installed and available in your terminal

  • uv installed — see How to install uv

  • (for REST API track) Grab your 4 BW API keys from the profile pages below

    • BongaWonga App: https://app.bongawonga.com/profile → copy to BW_APP_API_KEY

    • BongaWonga HRIS: https://hris.bongawonga.com/profile → copy to BW_HRIS_API_KEY

    • BongaWonga IdP: https://idp.bongawonga.com/profile → copy to BW_IDP_API_KEY

    • BongaWonga CustomApps: https://customapps.bongawonga.com/profile → copy to BW_CUSTOMAPPS_API_KEY

Time estimates

Part

Track

Estimated time

1

CSV

10 min

2

CSV

10 min

3

CSV

10 min

4

CSV

15 min

5

REST API

20 min

6

REST API

25 min

7

REST API

20 min

8

REST API

20 min

9

REST API

20 min

10

REST API

30 min

REST API note: The BongaWonga training APIs are hosted on Render.com. These free-tier instances spin down after 15 minutes of inactivity. If an API endpoint is slow to respond on your first request in a tutorial part, it is likely waking up. Wait a few seconds and retry. Subsequent requests in the same part will be faster.

What is BongaWonga?

BongaWonga is a fictional company used throughout these tutorials. They operate three separate systems, each with its own live API:

  • BongaWonga App — a SaaS application with users, groups, roles, projects, and workflows

  • BongaWonga HRIS — a human resources system with employee records

  • BongaWonga Identity — an identity provider with user identities and groups

All tutorials run against the live BongaWonga training APIs, which serve synthetic data. You will need API credentials for the REST API tutorials (Parts 5–10). The CSV tutorials (Parts 1–4) use local files and require no credentials.

Before you start

If you haven’t installed oaa-runner yet, do that first:

  1. How to install uv

  2. How to run integrations locally

Getting API credentials

The CSV track (Parts 1–4) uses local files — no credentials required.

The REST API track (Parts 5–10) connects to live BongaWonga training APIs. Sign in to each BongaWonga application, then navigate to your profile page — your API key is listed there. Each system has its own profile page:

System

Profile page

Environment variable

BongaWonga App

https://app.bongawonga.com/profile

BW_APP_API_KEY

BongaWonga HRIS

https://hris.bongawonga.com/profile

BW_HRIS_API_KEY

BongaWonga IdP

https://idp.bongawonga.com/profile

BW_IDP_API_KEY

BongaWonga CustomApps

https://customapps.bongawonga.com/profile

BW_CUSTOMAPPS_API_KEY

You only need credentials for the systems used in each tutorial — Part 5, for example, only requires the BongaWonga App credentials. Each tutorial lists what it needs in its Prerequisites section.

What you’ll build

The series has two tracks. Each tutorial introduces one or two new concepts and builds directly on the previous one.

CSV track (tutorials 01–04)

Start here if you are new to oaa-runner. You’ll load data from local CSV files and progressively add more capabilities.

Tutorial

What it introduces

Part 1 — Your First CSV Upload

Sources, destinations, field mapping

Part 2 — Transforming Fields

Transforms: lowercase, jinja_render, validate_boolean, date_convert

Part 3 — Modeling a Custom Application

Generators: auto-create groups and roles from column values

Part 4 — Writing Your First Hook

Record transform hooks for cross-record relationships

REST API track (tutorials 05–10)

Continue here after completing the CSV track. You’ll connect to the live BongaWonga APIs using API key authentication and load data into multiple Veza destination types.

Tutorial

What it introduces

Part 5 — Connecting to a REST API

Connections, custom modules, API key authentication

Part 6 — Multiple Systems, Multiple Destinations

Multiple destination types: Custom App, HRIS, IdP

Part 7 — Fetching CSV Data over HTTP

CSV-over-HTTP, io.StringIO, API key auth

Part 8 — Scoping Permissions to Resources

Resource-scoped role assignments

Part 9 — Defending Against Bad Data

Null guards, empty string checks, circular reference detection

Part 10 — Linking Identities Across Systems

Cross-system identity enrichment, module-level cache

Example directories

Each tutorial’s Setup section walks you through creating the required directory and files from scratch. There is nothing to clone or download — every file you need is shown inline in the tutorial.

Reference

For a quick reference covering the BongaWonga API endpoints, API helper script, and external resources, see the BongaWonga Reference.

Where to start

Go to Part 1 — Your First CSV Upload.