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.

ubConnect 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.

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

    

Note

When you use a Jinja string as value, you must ensure the field names of a service object, set as values for the mapping option, does not contain spaces because that will raise a Jinja Template Syntax Error . For example: Instead of the column name being CREATED AT use CREATED_AT . Read more about the mapping configuration.

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'],
}

    

Note

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

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