Metadata-Version: 2.4
Name: bmw-lobster-tool-codebeamer
Version: 0.14.0
Summary: LOBSTER Tool for Codebeamer
Home-page: https://github.com/bmw-software-engineering/lobster
Author: Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
Author-email: philipp.wullstein-kammler@bmw.de
License: GNU Affero General Public License v3
Project-URL: Bug Tracker, https://github.com/bmw-software-engineering/lobster/issues
Project-URL: Documentation, https://github.com/pages/bmw-software-engineering/lobster/
Project-URL: Source Code, https://github.com/bmw-software-engineering/lobster
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development
Requires-Python: >=3.7, <4
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31
Requires-Dist: bmw-lobster-core>=0.14.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# LOBSTER

The **L**ightweight **O**pen **B**MW **S**oftware **T**raceability
**E**vidence **R**eport allows you to demonstrate software traceability
and requirements coverage, which is essential for meeting standards
such as ISO 26262.

This package contains a tool to interface with the proprietary
requirements management tool
[Codebeamer](https://intland.com/codebeamer).

## Tools

* `lobster-codebeamer`: Extract requirements from codebeamer.

## Configuration
The tool requires a YAML configuration file to define its settings.
You must provide this file when running the tool to specify parameters to process.

It allows to configure the following features:

### References
Codebeamer items can reference other items through
[Reference Fields](https://support.ptc.com/help/codebeamer/r2.1/en/index.html#page/codebeamer/user_guide/ug_reference_fields.html).
This piece of information can be extracted by the tool, and serialized into the
LOBSTER output file.
It only needs to know which fields to take into account.
Following the LOBSTER yaml schema, the item references will be added to the
`refs` property of the LOBSTER item.
Accordingly, the configuration parameter to specify the codebeamer field names
is called `refs`, too.
It can contain a single field name, or a list of field names.
Field IDs cannot be used, only the field names.

Examples:
```yaml
  refs : "cb-fieldname"
```
or
```yaml
  refs : ["cb-fieldname"]
```
or
```yaml
  refs : ["cb-fieldname1", "cb-fieldname2"]
```

### Bearer Authentication Token
Define the Bearer authentication token in the configuration file as follows
```yaml
  token : "your-codebeamer-Bearer-token"
```
Note:
- If `--cb-user` or `--cb-pass` is given together with a Bearer token (through the configuration file), then the
  Bearer authentication method is used, and the username and/or password are
  ignored.
- If neither a token nor a username or password are given, then the tool tries
  to read the username and password from the `.netrc` file in the user's home
  directory.
- If value of root in config file is `https://codebeamer.bmwgroup.net`, then value of
  machine in .netrc will be `codebeamer.bmwgroup.net`.

### .netrc Configuration for Codebeamer

  ```.netrc
  machine your.codebeamer.url
  login your_username
  password your_password
  ```

### Example Configuration
Here is an example of a configuration file:
```yaml
  refs  : ["derived from", "satisfied by"]
  token : "SomeTokenStringABC123"
```

Is it also possible to define the codebeamer token in this file:
```yaml
  refs  : "cb-fieldname"
  token : "your cb-token"
```

### Schema
You can also specify the type of schema for the resulting output file. The supported values for the schema field are:
- Activity: Sets the schema to lobster-act-trace.
- Implementation: Sets the schema to lobster-imp-trace.
- Requirement: Sets the schema to lobster-req-trace.

If the schema is not specified, the tool will default to Requirement, and the schema lobster-req-trace will be used.

Here is an example of a configuration file:
```yaml
  schema: "Activity",  // Specifies schema
  refs  : ["cb-fieldname1", "cb-fieldname2"]  // Specifies references
```

If an invalid schema is provided, the tool will raise an exception. Supported schema values are Activity, Implementation, and Requirement.

## Usage

There are two ways you can use this tool:

1. Download all requirements mentioned by another lobster trace (this
  way you do not get a completeness check) (using `--import-tagged`)

2. Download all requirements generated by a saved codebeamer query ID OR a codebeamer query string (cbQL query)
  (using `--import-query` - accepts the query ID as well as query string)

* Configure the 'refs' upstream reference (this parameter is optional)

* Additionally, you can specify the schema and references:

  1. Specify the schema of the trace to be generated (optional, defaults to "Requirement"). You can set it in the configuration file.

  2. Configure the 'refs' upstream reference (optional).

    * For example:
    ```python lobster_codebeamer.py --config codebeamer-config.yaml```

       This command will extract activity traces (lobster-act-trace) with specified references.

## Limitations

The key limitation is item text, which is currently not
imported. However, we do plan to also import item text eventually.

## Copyright & License information

The copyright holder of LOBSTER is the Bayerische Motoren Werke
Aktiengesellschaft (BMW AG), and LOBSTER is published under the [GNU
Affero General Public License, Version
3](https://github.com/bmw-software-engineering/lobster/blob/main/LICENSE.md).

This tool has no actual dependency on, or with, Codebeamer. It just
talks the API as described here: https://codebeamer.com/cb/wiki/117612
