The Codebeamer service synchronizes data between codebeamer from Intland and the Requirement Engineering extension Sphinx-Needs from useblocks.

The implementation is based on the services mechanism of Sphinx-Needs.

The Codebeamer service allows to retrieve external data during documentation build and to create Sphinx-Needs objects based on this data. After the created Sphinx-Needs objects support every function from Sphinx-Needs, which includes Filtering, Linking, Updating and much more.


The following options can be used inside .. needservice:: Codebeamer and related directives.


A query string, which must be valid to cbQL.


A string, which is taken as prefix for the need-id. E.g. CB_IMPORT_ –> CB_IMPORT_005.


If set to “True”, the description content gets presented inside a code-block and is not handled as rst-valid text anymore. Use it to avoid sphinx build errors, is the item description is based on wiki or html syntax.

Default: False


If set to “True”, wiki-based item content gets transformed to html and is presented in a .. raw:: html directive.

Default: True

If raw is set as well, content gets transformed to HTML, but is presented inside a code-block.


Use :debug: to see the data structure of Codebeamer’s responses.


A Codebeamer service configuration must be created inside your file.


For details about most configuration options, please take a look into the common configuration description.

The following documentation describes service specific information for Codebeamer only.


Default value for Codebeamer services is /rest/v3/items/query.

See also endpoint for more details.


Please see url for details.


Inside your file:

# Manipulates the content to add a link to the source issue
cb_content = """
`Codebeamer Link to Issue {{}} <{{data.cb_server}}/issue/{{}}>`_


needs_services = {
    'codebeamer_config': {
        'url': "",
        'user': 'bond',
        'password': '007',
        'prefix': "CB_IMPORT_",
        'content': cb_content,
        'query': " IN ('my_project', 'another_project') and type = 'Requirement' and status = 'Draft'",
        'mappings': {
            'type': "spec",
            'tags': 'cb_import, example',
            "id": ["id"],
            "status": ["status", "name"],
            "title": ["name"],
        'extra_data': {
            'assignedBy': ['assignedTo', 0, 'name'],
            'createdAt': ['createdAt'],
            'updated': ['modifiedAt'],
            'type': ['typeName'],

Inside any rst file of your Sphinx project:

.. needservice:: codebeamer_config
    :query: IN ('my_project', 'another_project')
    :prefix: CB_IMPORT

.. needtable::
   :filter: "CB_IMPORT" in id



The below examples are just images, as no Codebeamer instance was available during documentation build.

../_images/cb_example.png ../_images/cb_table.png