mmdok-cli 1.9

Cli client for TinyDS

Command client for MMDok used to store documents and metadata.

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.

    <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:[e-mail]
    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:[e-mail]
    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': '[e-mail]',
      'metadata': {'Fakturanr': '123459', 'type': 'Faktura'},
      'ts': '2021-08-17T20:46:42.853Z',
      'type': 'Faktura',
      'updated_by': '[e-mail]'}]
    </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': '[e-mail]'},
     {'op': 'view', 'ts': '2021-08-17T21:24:33.977Z', 'user': '[e-mail]'},
     {'op': 'view', 'ts': '2021-08-19T21:27:01.185Z', 'user': '[e-mail]'}]
    
     (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 } ]

    and a file <h3>types.json</h3>
    <pre><code>[

{ "name": "test_type", "order": 1, "fields": [ "test_field" ] } ]

    Then we can create the document type using the following command, assuming that [e-mail] 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: [e-mail] 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

    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.