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 retrieving external data during documentation build and creates 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, if 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.


Integer value to specify which project id to use when request wiki2html requests.

Default: 2


Integer value to set a delay between wiki2html requests to the API.

Default: 0


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.


Specifies an absolute path to a folder containing for example a self signed certificate for the codebeamer URL.


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 are examples of just images, since no Codebeamer instance was available during documentation build.

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