mmdok-cli 1.15
Cli client for TinyDS
License: BSD 2-clause

<h2>Command client for TinyDS used to store documents and metadata.</h2>
TinyDS is a modern, minimal, simple and scalable DMS that is designed to be able to handle hundreds of millions of documents. 
It can run serverless, in a container or locally with the same code base. MMCli is a command line client to MMDok.<br><br>
For api documentation on the interfaces used by the cli see <a href="https://www.tinyds.se/api_documentation.html" target="_blank">api documentation</a>.<br>
For general information on TinyDS see <a href="https://www.tinyds.se/index_en.html" target="_blank">tinyds</a>.

<h2>Getting started with the cli</h2>

With Python3 installed:

$ python -c "from mmcli import mmcli; mmcli.run()"<br><br>

(Cmd) help<br><br>
Commands:<br>
   <table>
   <tr><td><b>add_signer</b></td><td><i>add a signer to a document</i></td></tr>
   <tr><td><b>add_viewer</b></td><td><i>add a viewer to a document</i></td></tr>
   <tr><td><b>audit</b></td><td><i>print audit logs for a document</i></td></tr>
   <tr><td><b>comment</b></td><td><i>add a comment to a document</i></td></tr>
   <tr><td><b>count</b></td><td><i>count documents</i></td></tr>
   <tr><td><b>createfromtemplate</b></td><td><i>create a document from a template and metadata</i></td></tr>
   <tr><td><b>delete</b></td><td><i>deletes a document</i></td></tr>
   <tr><td><b>delete_version</b></td><td><i>deletes a specific version of a document</i></td></tr>
   <tr><td><b>download</b></td><td><i>download and show a document in the webbrowser</i></td></tr>
   <tr><td><b>exit</b></td><td><i>exit the CLI</i></td></tr>
   <tr><td><b>external_sign</b></td><td><i>open sign page for a document in browser</i></td></tr>
   <tr><td><b>external_view</b></td><td><i>open view page for a document in browser</i></td></tr>
   <tr><td><b>freesearch</b></td><td><i>free text search for words or parts thereof in document content</i></td></tr>
   <tr><td><b>getcomment</b></td><td><i>get comments for a document</i></td></tr>
   <tr><td><b>getlock</b></td><td><i>get lock status for a document</i></td></tr>
   <tr><td><b>getprofile</b></td><td><i>get user profile</i></td></tr>
   <tr><td><b>help</b></td><td><i>display help information</i></td></tr>
   <tr><td><b>link</b></td><td><i>link two documents together</i></td></tr>
   <tr><td><b>list</b></td><td><i>list linked documents</i></td></tr>
   <tr><td><b>listtemplates</b></td><td><i>list templates for the current user</i></td></tr>
   <tr><td><b>lock</b></td><td><i>lock a document</i></td></tr>
   <tr><td><b>login</b></td><td><i>used to log in to the server</i></td></tr>
   <tr><td><b>login_server</b></td><td><i>change login server</i></td></tr>
   <tr><td><b>logout</b></td><td><i>log out from the server</i></td></tr>
   <tr><td><b>metadata</b></td><td><i>prints metadata for a document</i></td></tr>
   <tr><td><b>quit</b></td><td><i>quit the CLI</i></td></tr>
   <tr><td><b>register</b></td><td><i>register a user</i></td></tr>
   <tr><td><b>reset_password</b></td><td><i>reset user password</i></td></tr>
   <tr><td><b>search</b></td><td><i>search documents</i></td></tr>
   <tr><td><b>server</b></td><td><i>change target server from the default</i></td></tr>
   <tr><td><b>setprofile</b></td><td><i>set user profile</i></td></tr>
   <tr><td><b>signers</b></td><td><i>list signers for a document</i></td></tr>
   <tr><td><b>types</b></td><td><i>lists available document types</i></td></tr>
   <tr><td><b>unlink</b></td><td><i>unlink two documents</i></td></tr>
   <tr><td><b>unlock</b></td><td><i>unlock a document</i></td></tr>
   <tr><td><b>update</b></td><td><i>updates a document's metadata</i></td></tr>
   <tr><td><b>updateprofile</b></td><td><i>update user profile</i></td></tr>
   <tr><td><b>upload</b></td><td><i>upload either a new document or a new version</i></td></tr>
   <tr><td><b>url</b></td><td><i>get shareable URL for a document</i></td></tr>
   <tr><td><b>users</b></td><td><i>list users</i></td></tr>
   <tr><td><b>view</b></td><td><i>view a document in the browser</i></td></tr>
   <tr><td><b>view_version</b></td><td><i>view a specific version of a document</i></td></tr>
   <tr><td><b>viewers</b></td><td><i>list viewers for a document</i></td></tr>
</table>

For detailed help for a command type: 'help <command>'<br><br>


<h3>Example session</h3>
Note that if you at registration below answer that you don't belong to a group, you will be able to login
and use the system immediately. You will be able to use a set of predefined document types and attributes,
and you will only handle your own documents.<br>
However, if you belong to a group, your group administrator has to give you permissions before you can start.
You will then be able to share documents within the group.
<pre>

$ python3 -c "from mmcli import mmcli; mmcli.run()"

(Cmd) register
   Email:magnus@foo.bar
Password:
Do you belong to a group[Y|N]:Y
<i>
Registration succeded. 
An email will be sent to you for confirmation.
Please ask your group administration to give you permissions.
</i>

(Cmd) login
   Email:magnus@foo.bar
Password:
<i>
 Login succeded
 Group: edok
</i>

(Cmd) types 
<i>{'Faktura': {'_id': '611c18862271d9e4a5dae511',
             'customer': 'edok',
             'fields': {'Fakturanr': {'displayname': 'Invoice number',
                                      'displayname_sv': 'Fakturanummer',
                                      'format': '\\d+',
                                      'general': False,
                                      'index': True,
                                      'mandatory': True,
                                      'name': 'Fakturanr',
                                      'order': 1,
                                      'placeholder': '123456',
                                      'search': True,
                                      'type': 'text',
                                      'update': True,
                                      'values': None}},
             'id': 1,
             'name': 'Faktura',
             'order': 1}}
</i>
(Cmd) search
Filter: {"Fakturanr":123459}
Sort: 
From: 
Number: 
<i>[{'_id': '611c2032d444ac00094333b5',
  'creator': 'gustav@foo.bar',
  'metadata': {'Fakturanr': '123459', 'type': 'Faktura'},
  'ts': '2021-08-17T20:46:42.853Z',
  'type': 'Faktura',
  'updated_by': 'gustav@foo.bar'}]
</i>

(Cmd) metadata
Documentid: 611c2032d444ac00094333b5
<i>{'Fakturanr': '123459', 'type': 'Faktura'}
</i>

(Cmd) count
<i>
{'count': 14}
</i>

(Cmd) audit
Documentid: 611c2032d444ac00094333b5
[{'op': 'create', 'ts': '2021-08-17T20:46:42.853Z', 'user': 'gustav@foo.bar'},
 {'op': 'view', 'ts': '2021-08-17T21:24:33.977Z', 'user': 'gustav@foo.bar'},
 {'op': 'view', 'ts': '2021-08-19T21:27:01.185Z', 'user': 'sture@foo.bar'}]

 (Cmd) upload
Provide a document id if it is a new version, leave empty for new document
Docid: 
Chose document type: Faktura
Metadata: {"Fakturanr":123}
Path to files: /tmp/dummy.pdf
<i>
True
612404f1c0c7380008f019ad
</i>

(Cmd) count
<i>
{'count': 15}
</i>
</pre>

<h3>Permissions</h3>
All commands except register and login need permissions. One can either register as a standalone
user or as belonging to a group. In the first case the user has full permission but only
the documents created by the user. In the latter case permissions have to be set up by a
group administrator.

<h3>Document types</h3>
For standalone users available document types and attributes are a set of standand and common for all.
For group users those are defined in an admin gui. See below. In a future release
admin operations will be available via an api and cli.

<h3>Notifications</h3>
Notifications can be received upon document creation or deletion. For an example this can be look at 
this link: <a href="https://master.d8z78xbyyxmus.amplifyapp.com/notification.html" target="_blank">notification client</a>
The client takes the url parameter ?group=<i>group_name</i>, where the <i>group_name</i> is the name of your group. 

<h3>Server side</h3>
The default server is a serverless lambda located on AWS, which also is the default server for this CLI.
However, the client can be set to connect to a server anywhere, for example locally while testing, or 
againt a server running in a Docker container.

<h3>Other clients</h3>
MMDok can be accessed via a REST API. MMCli contains a Python client using this api.<br>
There is a gui client available at <a href="https://master.d8z78xbyyxmus.amplifyapp.com/" target="_blank">gui client</a>. The same login will work.

<h2>Administration</h2>
Administrations of documenttypes, users and their permissions can also be done via MMCli using the mmadmin module.

<h3>Admin Commands</h3>
Admin commands are available via mmadmin for managing resources:<br>
$ python -c "from mmcli import mmadmin; mmadmin.run()"<br><br>

Admin Commands:<br>
   <table>
    <tr><td><b>create</b></td><td><i>create a new admin resource from JSON file</i></td></tr>
    <tr><td><b>delete</b></td><td><i>delete an admin resource by ID</i></td></tr>
    <tr><td><b>exit</b></td><td><i>exit the admin CLI</i></td></tr>
    <tr><td><b>login</b></td><td><i>authenticate user via bankid, freja, apikey, or user-password</i></td></tr>
    <tr><td><b>quit</b></td><td><i>exit the admin CLI</i></td></tr>
    <tr><td><b>read</b></td><td><i>read an admin resource by name or list all</i></td></tr>
   <tr><td><b>update</b></td><td><i>update an admin resource from JSON file</i></td></tr>
  </table>
<br>

Resources handled by the admin cli are fields, document types, roles, users and templates.

Let's say that we want to create a new document type with one field. We can create a JSON files with the following content:

<h3>fields.json</h3>
<pre><code>[
  {
    "name": "test_field",
    "displayname": "Test",
    "displayname_sv": "Test",
    "type": "number",
    "placeholder": "900",
    "order": 7,
    "format": "^\\d+$",
    "search": true,
    "index": false,
    "update": true,
    "general": false,
    "mandatory": false
  }
]</code></pre> 

and a file <h3>types.json</h3>
<pre><code>[
  {
    "name": "test_type",
    "order": 1,
    "fields": [
      "test_field"
    ]
  }
]</code></pre>

Then we can create the document type using the following command, assuming that admin@foo.bar is a user with admin permissions for the group:
<pre><code>% python3 -c "from mmcli import mmadmin; mmadmin.run()"
(Cmd) login
  bankid|freja|apikey|user-password: u
  Email: admin@foo.bar
  Password: 
  Code: 121212
  Login succeded
(Cmd) create field data/fields/fields.json
  Object 1: Status: 200
  ok
(Cmd) create type data/types/types.json
  Object 1: Status: 200
  ok</code></pre>

Permission, roles, users and templates can be created in a similar way, with json-files that can be stored in for example a git repository. 
A full description is not given here.