Services are used to get objects like Issues from external services like JIRA and create Sphinx-Needs objects based on them.

Write .. needservice:: <service> into any rst-file and the related service will add the received data as Sphinx-Needs objects.

Sphinx-Needs Enterprise supports the following services:


Most services share a common set of configuration parameters, which are described on this page.

my_content = """
**Raw description of content**


needs_services = {
    'my_service': {
        'url': "",
        'endpoint': "/custom/rest/endpoint"
        'user': 'test',
        'password': 'test',
        'id_prefix': "SERVICE_",
        'query': 'project = TEST',
        'content': my_content,
        'mappings': {
            "id": ["key"],
            "type": 'spec',
            "title": ["fields", "summary"],
            "status": ["fields", "status", "name"],
        'extra_data': {
            "Original Type": ["fields", "issuetype", "name"],
            "Original Assignee": ["fields", "assignee", "displayName"],
        'raw': 'False',
        'wiki2html: 'True',


URL of the server. The final REST api location gets added automatically.


The final address of the endpoint.

Is service specific, but the configured default values should work for most cases.


Credentials used for login.


A string which represents the query parameter. The syntax of the query string is service specific.

It can be overwritten by option query of the needservice directive.

.. needservice:: JIRA
   :query: status not in ('Closed', 'Resolved', 'Done')

See related service description for details.


A prefix for the final ID of the created need. Can get important, if the IDs from Codebeamer are not unique.

Example: CB_ will create IDs like CB_1002.


Field names a service object do normally not map to option names of Sphinx-Needs. So mapping defines, from where a Sphinx-Needs option shall get its value inside the service data.

mapping must be a dictionary, where the key is the needs object name and the value is a list or tuple, which defines the location of the value in the retrieved service data object.

Example using Codebeamer

Goal: The need option author shall be set to the Assignee name.

This information is stored in the retrieved Codebeamer json data under


So the final mapping entry looks like:

'mapping': {
    'author': ['assignedTo', 0, 'name'],

Note: Combining data from multiple locations in a mapping definition is currently not supported.


There are use cases, where a value inside service data is not valid for a Sphinx-Needs options.

For instance: In Codebeamer the type is named Requirement, but Sphinx-Needs supports only req as value for type option.

mappings_replaces can replace strings defined by a regular expression with a new value. This replacement is performed for all mappings.


The Codebeamer value Requirement must be replaced by req and set as value for the need option type.

'codebeamer': {
    'mappings': {
        'type': ['typeName'],  # maps the original location
    'mappings_replaces': {
        '^Requirement$': 'req',


content takes a string, which gets interpreted as rst-code for the need-content area. Jinja support is also available, so that service data is available and can be accessed like {{data.description}}.

Example for a Codebeamer configuration:

my_content = """
Content from Codebeamer Issue

This is assigned to **{{data.assignedTo[0].name]}}**.

`Link to source <http://my_server/issue/{{}}>`_

needs_services = {
'codebeamer': {
    # ... some other values
    'content': my_content

The set options for the needservice are available under options. Example:

my_content = """
Executed query: {{options.query}}


{% if options.prefix == "TEST_" %}
{% endif %}


There may be information stored inside services data fields, which can not be mapped to Sphinx-Needs options, but which shall be make available inside the need object.

This can be done by using extra_data, which adds this kind of information to the end of the content of a need object.

The logic and syntax is the same as used by mapping.

'extra_data': {
    'assignedBy': ['assignedTo', 0, 'name'],
    'createdAt': ['createdAt'],
    'updated': ['modifiedAt'],


Outputs the need content to a codeblock without any modifications.

For some service a content transformation (e.g. wiki-syntax to html or rst) is needed, to get a nice looking and “working” representation of the content.

Default: False

Supported Services: Codebeamer


Transforms a need content, which is using a wiki-like syntax, to a format, which can be used by Sphinx (e.g rst or HTML).

Most services do not need to support this configuration options, as they provide by default a Sphinx compatible output.

Default: True

Supported Services: Codebeamer