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