Services¶

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:

Configuration¶

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

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

{{data.description}}
"""

needs_services = {
    'my_service': {
        'url': "http://127.0.0.1:8081",
        '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¶

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

endpoint¶

The final address of the endpoint.

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

user/password¶

Credentials used for login.

query¶

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.

id_prefix¶

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.

mapping¶

The field names of a service object do not often map to option names of Sphinx-Needs. So mapping defines 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 either a Jinja string such as is_{{status}} or a list/tuple, which defines the location of the value in the retrieved service data object.

Example using a Jinja string as value for the Excel service

Goal: The need option author shall be set to both the Last and First names.

The last and first names information are stored in the retrieved Excel data under LAST_NAME and FIRST_NAME.

So the final mapping entry looks like:

'mapping': {
    'author': "{{LAST_NAME}} {{FIRST_NAME}}",
}

Example using a list/tuple as value for the Codebeamer service

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

This information is stored in the retrieved Codebeamer json data under assignedTo.0.name.

So the final mapping entry looks like:

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

mappings_replaces¶

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.

Example

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¶

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
-----------------------------
``{{data.description}}``.

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

`Link to source <http://my_server/issue/{{data.id}}>`_
"""

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}}

{{data.description}}

{% if options.prefix == "TEST_" %}
**TEST TICKET**
{% endif %}
"""

extra_data¶

There may be information stored inside a service’s data fields that can not be mapped to Sphinx-Needs options, but shall be made available inside the needed 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 are the same as used by mapping.

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

raw¶

Outputs the needed content to a codeblock without any modifications.

For some services 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

wiki2html¶

Transforms a needed content, that uses a wiki-like syntax, to a format Sphinx can use (e.g rst or HTML).

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

Default: True

Supported Services: Codebeamer