Metadata-Version: 2.1
Name: mmdok-cli
Version: 1.9
Summary: Cli client for TinyDS
Home-page: https://github.com/emagnca/mmcli
Author: emagnca
Author-email: ehsmaga@yahoo.se
License: BSD 2-clause
Classifier: Development Status :: 1 - Planning
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3 :: Only
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cmd2 ==1.5.0
Requires-Dist: requests ==2.25.0
Requires-Dist: urllib3 ==1.26.2

<h2>Command client for MMDok used to store documents and metadata.</h2>
        MMDok 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>
        
        <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>batch</b></td><td><i>prepare batch upload data</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>view 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>view 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">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/">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.
