Mercurial > libervia-backend

comparison doc/libervia-cli/list.rst @ 3563:267e4987b58b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
author Goffi <goffi@goffi.org>
date Fri, 11 Jun 2021 09:21:41 +0200
parents doc/libervia-cli/ticket.rst@c80a0f864b5d
children 524856bd7b19
comparison
equal deleted inserted replaced
3562:9f599ccbea4e 3563:267e4987b58b
1 =================================
2 list: create and manage lists
3 =================================
4
5 list is a generic tools to create items with metadata and states (where state can be
6 ``queued``, ``done``, etc). This can be used for many things, from TODO list to bugs
7 management.
8
9 get
10 ===
11
12 Retrieve one or more lists and display them. A project may use magic string in README to
13 indicate PubSub service and node to use, in which case use just need to be in the
14 directory of the project.
15
16 examples
17 --------
18
19 Retrieve last 5 lists (ordered by creation) from a project using magic string in README::
20
21 $ li list get -m 5 -o creation
22
23 Retrieve the list with id ``123`` on service ``pubsub.example.org``::
24
25 $ li list get -s pubsub.example.org -i 123
26
27
28 set
29 ===
30
31 Create/replace or update a list item. You can specify fields using the ``-f NAME [VALUES
32 ...], --field NAME [VALUES ...]``, several values can be set. For ``text-multi`` (multiple
33 lines of text), each line is set in distinct value.
34
35 The ``-U {auto,true,false}, --update {auto,true,false}`` indicates if the item must be
36 updated (non specified values are kept) or fully replaced (non specified values would then
37 be default, even if they were previously set in the item). If ``auto`` is used (this is
38 the default), ``--update=true`` is used when ``item_id`` is specified, otherwise a new
39 item is created.
40
41 If ``-n NODE, --node NODE`` is not specified, it uses tickets default namespace.
42
43 examples
44 --------
45
46 Modify priority of a ticket with id ``123`` to ``major`` (the ticket is updated and not
47 replaced due to the default ``--update auto``)::
48
49 $ li list set -s pubsub.example.org -i 123 -f priority major
50
51 Set ``body`` for a new item when its schemas makes it a ``text-multi``::
52
53 $ li list set -s pubsub.example.org -f body "line 1" "line 2" "line 3"
54
55 delete
56 ======
57
58 Delete an item from a list. The options are the same as for :ref:`li_pubsub_delete`, the
59 only different is that ``-n NODE, --node NODE`` defaults to tickets namespace.
60
61 example
62 -------
63
64 Delete item with id ``456`` from tickets on PubSub service ``pubsub.example.org``::
65
66 $ li pubsub delete -s pubsub.example.org -i 456
67
68 import
69 ======
70
71 Import lists from an external source. This works in the same way as
72 :ref:`libervia-cli_blog_import`: you need to specify an importer and a data location. If you let
73 both positional argument empty, you'll get list of importers, if you specify importer but
74 not data location, you'll get a description on how the importer works.
75
76 If you want to see a progress bar for the import, use the ``-P, --progress`` option, this
77 is recommended for most imports.
78
79 Some importers may have specific option (check description for details), you can specify
80 them with ``o NAME VALUE, --option NAME VALUE``
81
82 When you import a list, the list will be created according to the schema of the PubSub
83 node. By default, the metadata of the original list will be put to the one of the same
84 name in the dest PubSub item. But of course the schema of your destination PubSub node may
85 differ from the original metadata. In this case, you can use ``-m IMPORTED_FIELD
86 DEST_FIELD, --map IMPORTED_FIELD DEST_FIELD`` to specify how the mapping mus be done
87 (``IMPORTED_FIELD is the name of the field in the original list, while ``DEST_FIELD`` if
88 the name of the field in your node schema).
89
90
91 examples
92 --------
93
94 Get list of list importers::
95
96 $ li list import
97
98 Get description of list importer for Bugzilla::
99
100 $ li list import bugzilla
101
102 Import lists from a Bugzilla XML export file at ``~/bugzilla_export.xml`` to the
103 ``pubsub.example.org`` PubSub service. We use default lists node and want a progression
104 bar::
105
106 $ li list import -P -s pubsub.example.org ~/bugzilla_export.xml
107
108 Same import, but this time we want to map the field ``assigned_to_name`` from Bugzilla to
109 the field ``assigned_to`` in our schema::
110
111 $ li list import -P -s pubsub.example.org -m assigned_to_name assigned_to ~/bugzilla_export.xml