Jama Connect

Roboticks integrates with Jama Connect through two paths:

Direct sync via the BYO connector framework (v1) — Roboticks polls Jama’s REST API on a schedule (cloud sync) or rbtk does it from inside your network (CLI push). Items, relationships, and tags land in the traceability matrix continuously.
ReqIF round-trip (free, always supported) — for snapshot-style audits or one-shot imports.

This page covers both. Jama’s primary_sync_mode is cloud sync because Jama is SaaS-first and exposes a stable REST API; CLI push is available for self-hosted Jama deployments.

Jama’s REST API is at /rest/v1/. Auth is OAuth2 client-credentials (preferred) or a Personal Access Token (PAT) for self-hosted Jama.

Connector type and pricing


Type	BYO requirements connector
Tier	Team (3 BYO connectors included), Enterprise (bundled)
Price	$149 / connector / month above the Team allowance

You bring the Jama license. For direct sync you provide either an OAuth2 client_id + client_secret (Jama Cloud admin → API Clients) or a PAT.

v1 direct sync

The adapter pulls:

Jama entity	Roboticks shape
`items` (anything that isn’t a Folder or Set)	`Requirement` with `external_id = documentKey`, `external_version = modifiedDate`, `external_url` deep-linking to the item
`relationships` per item	`RequirementRelation` (`verifies`, `derives`, `refines`, `relates_to`) with the raw Jama role preserved
Custom fields	Stored verbatim in `attributes` JSONB — surfaced in the matrix UI without schema awareness

Incremental sync filters items by modifiedDate.from={cursor} — only changed items hit the wire.

Cloud sync setup (OAuth2)

Create an OAuth2 client in Jama

Jama → Admin → API Clients → Create OAuth Client. Scope: read access to the project(s). Save the client_id and client_secret.

Subscribe in Roboticks

Settings → Integrations → Requirements → Jama → Subscribe. The setup wizard skips the CLI install step (Jama is cloud-primary) and goes directly to credentials:

Base URL: https://acme.jamacloud.com
Client ID + Client Secret
Jama project ID (numeric — find it under Admin → Projects)

Verify

The wizard calls verify_credentials; Jama returns 200 from /rest/v1/projects. If it does, the badge flips to “OK” and the first sync runs immediately.

CLI push setup (on-prem Jama)

Install rbtk and authenticate

pipx install roboticks-cli
rbtk auth login --org-slug=acme

Configure with PAT or OAuth

rbtk connector configure jama \
    --url=https://jama.acme.internal \
    --auth=oauth2 \
    --client-id=$JAMA_CLIENT_ID \
    --client-secret=$JAMA_CLIENT_SECRET \
    --label=primary \
    --jama-project-id=7

Or for PAT auth (self-hosted Jama supports it):

rbtk connector configure jama \
    --url=https://jama.acme.internal \
    --auth=pat \
    --token=$JAMA_PAT \
    --label=primary --jama-project-id=7

Sync

rbtk connector sync jama --label=primary

ReqIF round-trip (alternative)

One-time setup

Add the connector in Roboticks

Settings → Integrations → Requirements → Add → Jama. Name it for the project (e.g., jama-warehouse). Roboticks creates the connector record and bills the $149/month line if over the Team allowance.

Upload a field mapping

Jama’s workItem types and field names rarely match Roboticks’ default vocabulary. Provide a YAML mapping:

# roboticks/jama-mapping.yaml
workitem_types:
  "System Requirement": functional
  "Safety Requirement":  safety
  "Performance Requirement": performance
fields:
  "Identifier": id
  "Name":       title
  "Description": text
  "ASIL/PL":    asil_pl
link_roles:
  "Derived from": derives_from
  "Verified by":  confirmed_by
  "Refines":      refines

Upload via CLI:

rbtk integrations jama update --field-map roboticks/jama-mapping.yaml

Decide on the sync cadence

Three patterns work:

Push-on-release — export from Jama only at release tagging time
Nightly — scheduled CI job pulls a fresh export
On-demand — humans trigger when they make spec changes

CI recipe

# .github/workflows/jama-sync.yml
name: Jama sync
on:
  schedule:
    - cron: "0 5 * * *"   # 05:00 UTC daily
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Pull Jama ReqIF export
        run: |
          curl -fsSL -u "${{ secrets.JAMA_USER }}:${{ secrets.JAMA_TOKEN }}" \
            "https://acme.jamacloud.com/rest/v1/projects/42/export?format=reqif" \
            -o jama-export.reqif

      - run: pipx install roboticks-cli
      - run: rbtk auth oidc-from-github

      - name: Upload to Roboticks
        run: |
          rbtk requirements upload jama-export.reqif \
            --mode update \
            --field-map roboticks/jama-mapping.yaml

      - name: Export Roboticks state back
        run: |
          rbtk requirements export \
            --format reqif --with-coverage \
            --out roboticks-export.reqif

      - name: Push back to Jama
        run: |
          curl -fsSL -u "${{ secrets.JAMA_USER }}:${{ secrets.JAMA_TOKEN }}" \
            -X POST -F "file=@roboticks-export.reqif" \
            "https://acme.jamacloud.com/rest/v1/projects/42/import?format=reqif"

The export-back loop carries Roboticks’ coverage_status attribute (confirmed | uncovered | stale) into Jama’s ReqIF.ForeignAttributes, where Jama exposes it as a sortable column.

Field mapping reference

Roboticks field	Required	Typical Jama source
`id`	yes	`Identifier` or `documentKey`
`title`	yes	`Name`
`text`	yes	`Description`
`type`	yes	derived from `itemType`
`asil_pl`	optional	custom field, often `ASIL/PL`
`priority`	optional	`Priority`
`tags`	optional	comma-split of `Tags`
derived-from links	optional	`Refines` / `Derived from` link roles

Round-trip caveats

Rich-text fields lose formatting

Jama stores Description as XHTML. Roboticks stores text as Markdown. The conversion preserves headings, lists, bold/italic, and inline code; it discards tables and embedded images. Use the Jama Web Viewer for the canonical rendering.

Roboticks-side annotations are advisory

coverage_status is exported as a foreign attribute. Jama displays it but does not gate workflows on it. If you want a Jama review state to block on coverage, wire a Jama webhook to your CI that fails when any pinned requirement is uncovered.

ID stability

Roboticks uses the value of the id field (default Identifier) as the immutable key. If Jama re-IDs a workItem (rare, usually via a migration), you’ll get a duplicate; resolve by archiving the old ID via rbtk requirements list --status archived.

Link role mapping is one-way at first

The first round trip imports Jama links as Roboticks “derives_from” or “refines” relationships. The export-back loop preserves them. New Roboticks-side relationships (e.g., a test annotating a requirement) appear in Jama under the roboticks.confirmed_by foreign attribute, not as native Jama links.

Validation

After the first sync:

rbtk requirements list --output json | jq '.[] | {id, title, type}'

Spot-check 5–10 requirements against Jama. Then run a --dry-run:

rbtk requirements upload jama-export.reqif --dry-run --output json | jq '.changes'

The output shows added, updated, archived, unchanged. On a properly-converged sync, added is 0 unless someone authored a new requirement in Jama since the last run.

Troubleshooting

`field-map: required field 'id' not produced`

Your mapping’s fields.id source doesn’t match Jama’s actual field name. Re-export with ?fields=true and inspect the column headers.

Duplicate requirement on every sync

Jama is re-keying. Pin the mapping to a stable field (e.g., documentKey instead of Name).

Round-trip export rejected by Jama

Jama enforces some constraints on import (e.g., itemType must exist). Check the upload log in Jama’s Project Admin → Imports.

Polarion

The other big RM tool — same shape, different quirks.

rbtk requirements

Upload, coverage, export reference.

Documentation Index

​Jama Connect

​Connector type and pricing

​v1 direct sync

​Cloud sync setup (OAuth2)

​CLI push setup (on-prem Jama)

​ReqIF round-trip (alternative)

​One-time setup

​CI recipe

​Field mapping reference

​Round-trip caveats

​Validation

​Troubleshooting

​Next

Polarion

rbtk requirements

Jama Connect

Connector type and pricing

v1 direct sync

Cloud sync setup (OAuth2)

CLI push setup (on-prem Jama)

ReqIF round-trip (alternative)

One-time setup

CI recipe

Field mapping reference

Round-trip caveats

Validation

Troubleshooting

Next