ubconnect import

ubconnect import allows the execution of configured need_services and stores the retrieved data in a needs.json file, which can be used by .. needimport:: .

$ ubconnect import -c docs/conf.py jira -v 3.0.1 -r needs.json -o . -w

Importing config from /home/daniel/workspace/sphinx/sphinx-needs-enterprise/docs/conf.py
Using provider "jira" for given service jira

URL: ``http://127.0.0.1:8081/rest/api/2/search``
Query: project = PX
Sending request:  Done
Retrieved 2 element
Version to use: 3.0.1
Reusing needs.json: /home/daniel/workspace/sphinx/sphinx-needs-enterprise/needs.json
Erasing existing data for version 3.0.1.

Note

Please take into account that not all services are supporting all functions like ubconnect import or ubconnect export .

Take a look at the service badges on our main page, to figure out what a service currently supports.

use case

ubconnect import can be used to retrieve and store baselines of external data at a specific point of time. So instead of always getting the latest data via .. needservice:: jira during each build, ubconnect import can be used to request and store this data only once in a needs.json file. This file can be stored inside your source version system, so that each developer works on the same data. To get the data into your documentation, use .. needimport:: needs.json .

For huge requests and big teams, this can reduce the number of requests against the external service dramatically and it makes sure that each build is using the same data.

arguments

ubconnect import takes only one argument, the name of the service to call.

service

A given service must be defined inside needs_services of a conf.py file. By default ubconnect looks into the current working directory for a conf.py file. Use -c to specify another location.

The service key should start with the name of the tool, so that ubconnect is selecting the internal driver automatically. For instance: jira_my_server for JIRA or codebeamer123 for Codebeamer .

ubconnect import jira_my_server

options

-c / –conf

Can be used to specify the location of the conf.py file to use.

ubconnect import jira -c docs/conf.py

Default: conf.py (in the current working directory)

-o/–outdir

The folder, under which the final needs.json file shall be created. Will create not existing subfolders automatically.

ubconnect import codebeamer -o my_exports/2.0.1/

Default: . (current working directory)

-q/–query

Query to use for the service request.

ubconnect import jira -q "status != closed"

Default: Taken from service config in conf.py .

-r/–reuse

Location of a needs.json compatible file, which data shall be copied/updated in the final needs.json file.

ubconnect import codebeamer -r my_exports/2.0.1/needs.json

Default: Not set

-v/–version

The version, under which the data shall be stored in the needs.json file.

ubconnect import codebeamer -v 2.0.1

Default: version attribute from conf.py

-w/–wipe

If -r/--reuse is used, version specific data may contain data, which is not valid after an import. Maybe because an issue got deleted, but its data is still available in the reused needs.json .

Use -w / --wipe to delete all data for the version given by -v / --version before the newly imported data is stored.

ubtrace-connect import codebeamer -v 2.0.1 -w

Default: Not set

Examples calls

Excel

$ ubtrace-connect import excel_config -o _temp
Importing config from /tmp/pants-sandbox-Mp1Edj/docs/conf.py
Using provider "excel" for given service excel_config

URL: 
Query: 
Sending request:  Done
Retrieved 11 elements
Version to use: 1.0
Warning: new created needs from imported data do not have such needs options: ['tags', 'links', 'hide', 'collapse', 'layout', 'style', 'template', 'pre_template', 'post_template', 'duration', 'completion']

Storing data to json file: Done