> ## Documentation Index
> Fetch the complete documentation index at: https://docs.roboticks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# codeBeamer

> Round-trip requirements between PTC codeBeamer and Roboticks via ReqIF. Tracker types, field mapping, association mapping, codeBeamer-specific quirks.

# codeBeamer

Roboticks integrates with PTC (formerly Intland) codeBeamer via the **OMG ReqIF** standard. codeBeamer's native ReqIF support is solid and configurable per tracker.

## 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 codeBeamer license. Roboticks talks ReqIF only.

## Workflow

```mermaid theme={null}
%%{init: {"theme": "neutral", "themeVariables": {"primaryColor": "#4040ff"}} }%%
flowchart LR
    CB["codeBeamer Tracker"] -->|ReqIF Export| Hub["CI Job"]
    Hub -->|rbtk requirements upload| Plat["Roboticks"]
    Plat -->|with coverage| Hub2["rbtk requirements export"]
    Hub2 -->|ReqIF Import| CB
```

## One-time setup

<Steps>
  <Step title="Configure the codeBeamer tracker for ReqIF">
    In codeBeamer: **Tracker → Settings → ReqIF**. Enable export and import. Pick which custom fields participate in the round-trip. This is per-tracker.
  </Step>

  <Step title="Add the connector in Roboticks">
    **Settings → Integrations → Requirements → Add → codeBeamer**. Name it for the project (e.g., `cb-armcontroller`).
  </Step>

  <Step title="Author a codeBeamer-specific field mapping">
    codeBeamer uses tracker IDs (numeric) for type identity and human-readable field names for everything else:

    ```yaml theme={null}
    # roboticks/codebeamer-mapping.yaml
    workitem_types:
      "Requirement":            functional
      "Safety Requirement":     safety
      "Performance Requirement": performance
    fields:
      ID:           id
      Name:         title
      Description:  text
      "ASIL/PL":    asil_pl
      Priority:     priority
    associations:
      "derived from": derives_from
      "verified by":  confirmed_by
      "refines":      refines
    ```

    Upload:

    ```bash theme={null}
    rbtk integrations codebeamer update --field-map roboticks/codebeamer-mapping.yaml
    ```
  </Step>
</Steps>

## CI recipe

```yaml theme={null}
# .github/workflows/codebeamer-sync.yml
name: codeBeamer sync
on:
  schedule: [{ cron: "0 5 * * *" }]
  workflow_dispatch:

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

      - name: Pull codeBeamer ReqIF export
        run: |
          curl -fsSL \
            -u "${{ secrets.CB_USER }}:${{ secrets.CB_TOKEN }}" \
            "https://codebeamer.acme.com/cb/api/v3/trackers/4711/reqif" \
            -o codebeamer-export.reqif

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

      - run: |
          rbtk requirements upload codebeamer-export.reqif \
            --mode update \
            --field-map roboticks/codebeamer-mapping.yaml

      - run: |
          rbtk requirements export \
            --format reqif --with-coverage \
            --out roboticks-export.reqif

      - name: Push back to codeBeamer
        run: |
          curl -fsSL \
            -u "${{ secrets.CB_USER }}:${{ secrets.CB_TOKEN }}" \
            -X POST -F "file=@roboticks-export.reqif" \
            "https://codebeamer.acme.com/cb/api/v3/trackers/4711/reqif/import"
```

## codeBeamer-specific quirks

### Tracker ID vs tracker name

codeBeamer's REST API requires the numeric tracker ID. Find it under **Tracker → Settings → Tracker ID**. Mistaking the name for the ID is the #1 first-time error.

### Multi-tracker projects

A codeBeamer project may have several trackers (e.g., `System Requirements`, `Software Requirements`, `Test Cases`). One Roboticks integration handles one tracker. For multi-tracker round-trip, register one connector per tracker.

### Associations vs Relations

codeBeamer distinguishes:

* **Associations** — bidirectional links between items (`derived from`, `verified by`)
* **Relations** — parent/child within a tracker

The mapping handles associations. Relations come through as `parent_id` on the requirement.

### Field name collisions

codeBeamer auto-creates a `Name` field that mirrors `Summary` on some templates. The ReqIF export includes both. Map the one you want and ignore the other:

```yaml theme={null}
fields:
  Summary: title
  Name: __ignore
```

### Workflow status

codeBeamer's workflow status (New / Reviewed / Verified / Released) round-trips via the `Status` field. Add to the mapping if you want it visible in Roboticks:

```yaml theme={null}
fields:
  Status: workflow_status
```

`workflow_status` is a free-form Roboticks attribute and doesn't affect coverage logic.

## Round-trip caveats

<AccordionGroup>
  <Accordion title="codeBeamer-only artifact types">
    codeBeamer supports `Folder` and `Information` artifact types that Roboticks does not import as requirements. They're skipped silently; check the upload log for the `skipped` count.
  </Accordion>

  <Accordion title="Bidirectional associations create one link, not two">
    Roboticks stores the relationship once with a typed role. Re-exporting back creates the inverse for codeBeamer correctly.
  </Accordion>

  <Accordion title="codeBeamer's `cb:` namespace attributes">
    codeBeamer puts internal metadata under a `cb:` XML namespace. Roboticks preserves them as foreign attributes — they round-trip but aren't queryable from Roboticks.
  </Accordion>
</AccordionGroup>

## Validation

```bash theme={null}
# Spot-check
rbtk requirements list --output json | jq '.[] | select(.workflow_status == "Released") | .id' | wc -l
# Should match Released count in codeBeamer
```

## Troubleshooting

<AccordionGroup>
  <Accordion title="ReqIF import to codeBeamer reports `Type mismatch`">
    The exported `SPEC-OBJECT-TYPE-REF` doesn't match a known type in the destination tracker. Tighten the `workitem_types` mapping.
  </Accordion>

  <Accordion title="Custom field not appearing in Roboticks">
    The tracker may not have it enabled for ReqIF export. **Tracker → Settings → ReqIF → Field selection**.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup cols={2}>
  <Card title="Jama" icon="diagram-project" href="/integrations/jama">
    Similar shape, different terminology.
  </Card>

  <Card title="DOORS" icon="diagram-project" href="/integrations/doors">
    IBM DOORS Classic vs DOORS Next.
  </Card>
</CardGroup>