Tutorial - Management of Documents | Chino.io

Introduction

The focus of this tutorial is to create a system for the management of Documents implementing the upload of pictures (using BLOBs) and searching for specific ones.

Note: In this tutorial we don't manage Users, everything is created with the developer credentials.

This tutorial is available for the following programming languages: {{languages.join(", ")}}. In the setup you can change the programming language.

Use Case

We are going to use the following scenario for a better explanation of this tutorial:

We will create a system for the management of doctors' visits to their patients. visits will be stored in Documents.

Note: in this tutorial we do not manage Users in a proper fashion, we perform all operations with customer_id and customer_key credentials. For a tutorial with logged Users' operations check this link.

A Doctor can:

  • Create Documents with the visit's result

  • Search for specific User's Documents

  • Read all Documents

A User can:

  • Read his Documents with the doctor's visit result

Resources used

For this tutorial, Chino.io operates with the following Resources:

  • Repository: it's the main container which contains Schemas.

  • Schema: it's the resource which defines the structure of Documents. Here are defined the fields of the future Documents.

  • Document: it's the resource we will use to store sensitive data.

Select language:

Register to Chino.io 

To register to our service go to console console , fill in the form, confirm the email and access.

Note: You can use Chino.io test environment for free.

Setup development environment

Install library

First thing to do is to setup an environment (optional) and install the SDK (mandatory) 

(sudo) pip install git+https://github.com/chinoio/chino-python.git

Install library

First thing to do is to setup an environment (optional) and install the SDKs (mandatory)

There are two ways to install the SDKs:

If you're using Maven, then edit your project's pom.xml and add this: 

    <repositories>
        <repository>
            <id>jitpack.io</id>
            <url>https://jitpack.io</url>
        </repository>
    </repositories>

    <dependency>
        <groupId>com.github.chinoio</groupId>
            <artifactId>chino-java</artifactId>
        <version>1.0</version>
    </dependency>

If you're using Gradle, then edit your project's build.gradle and add this: 

    allprojects {
        repositories {
            ...
            maven {
                url 'https://jitpack.io'
            }
        }
    }

    dependencies {
        // ...
        compile 'com.github.chinoio:chino-java:1.0'
    }

The other method is building the SDKs from source: 

git clone https://github.com/chinoio/chino-java.git
    cd chino-java
    ./gradlew build

The output will be in build/

And if you want a "fat jar" with all the dependencies inside use the following commands: 

git clone https://github.com/chinoio/chino-java.git
    cd chino-java
    ./gradlew build shadowJar

In order to perform network operations your Android manifest must include the following permissions: 

<uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
Note

Network operations in Android cannot be performed in the main UI Thread. You have to wrap the API calls in an AsyncTask :

  • Start the AsyncTask passing all the required parameters in an array: execute(params)

  • Perform your call inside the method doInBackground, which is executed asynchronously

  • Elaborate the results - if it can be done in the async method - and eventually return them

  • Update your local values and the UI in the method onPostExecute, which is executed on the UI thread.


{{ androidCode ? "Hide" : "Show" }} example

Create a subclass of AsyncTask:

Then, from your Activity or class trigger the task like this:

TextView mTextView = findViewById(R.id.myTextView); String[] params = { "68e0cfb0-bb2b-4cf1-b73a-f83e262f2ce8", "a311dea9-9486-4a05-8050-a53409b00aa4", "0dbe2671-7f74-4739-be1d-7a0db303f6bb" }; new ChinoAsyncTaskExample(mTextView).execute(params);

You can use Postman to try our rest API. We provide a Collection, to be imported in Postman, which allows you to easily test every call in this tutorial.

You can download Postman at this link .

SDK distribution

You can integrate the CHINO.io Swift SDK into your project using one of several methods.

CocoaPods

To use CocoaPods, a dependency manager for Cocoa projects, you should first install it using the following command:

$ gem install cocoapods

Then navigate to the directory that contains your project and create a new file called Podfile. You can do this either with pod init, or open an existing Podfile, and then add

pod 'ChinoOSXLibrary', :git => 'https://github.com/chinoio/chino-ios.git', :tag => '1.0'

to the main loop. Your Podfile should look something like this:

use_frameworks!

target '<YOUR_PROJECT_NAME>' do
    pod 'ChinoOSXLibrary', :git => 'https://github.com/chinoio/chino-ios.git', :tag => '1.0'
end

Then, run the following command to install the dependency:

$ pod install

Once your project is integrated with the CHINO.io Swift SDK, you can pull SDK updates using the following command:

$ pod update

Write here your customer ID and Key

Here you can write your customerId and customerKey to have them filled out in the code. It's just for the purpose of the tutorial.

Note: these are developer credentials and the developer has the permissions to do everything. The focus is on the creation of Documents and not on the Permissions that Users have over them. For this kind of operations please check this tutorial.

Click on the following button to add the Collection with the calls of this tutorial in Postman.
Postman will automatically set the values inserted in this page in the environment variables.

Note: if you want to add an environment in Postman, please fill the customer_id and customer_key in the box above.

Initialize

First thing to do is to initialize our SDK.

We now have access to the SDK that wraps all the calls that Chino.io API offers.

Create a Repository

The next step is to create a Repository.

Repositories can be created via the API or via the console. For this first tutorial we create a Repository via the console.

We create a Repository using Postman

Note: without a Repository you can't create Schemas, and without Schemas you can't create Documents in which to store your data.

Once created we copy the (write here your repository_id) and we use it as constant in our code.

Create a Schema

The Schema represents the structure of the Document we want to store inside Chino. Since our objective is to store records of various doctors and patients, storing also their IDs is necessary to identify the right ones.

Note: this design is made only for the purpose of a better explanation of Documents' creation. For a better management of Users and Permissions check this link.

For this tutorial the following information is stored:

  • patient_id : string (indexed) - the patient that we have visited

  • doctor_id : string (indexed) - a reference to a doctor that performs the visit

  • visit_type : string (indexed) - the type of the visit

  • visit : text (not indexed) - the response of the visit

  • date : datetime (indexed) - timestamp of when the visit was made

  • picture : blob (not indexed) - timestamp of when the visit was made

Note: if the field is indexed it can be used to search for Documents. Better explanations throughout this tutorial.

We call this schema base_vist

Once created, copy the schema_id .

Create a Document

The Schema is now in place, and the application can be created. The server side code receives the data and creates the document on Chino.

The assumption is that the server side code knows the doctor_id and user_id (which are the user stored in our system, not on Chino). The other parameters (vist, visit_type) are taken from the form, while the data is computed by the server side code.

Once created, copy here the document_id .

Upload of a picture (BLOBs)

BLOBs allow the upload of files like pictures, PDF, etc. To upload a BLOB you need to create a proper field in a Schema (we created the field "picture" of type "blob" in the previous Schema).

Note: you need to create a Document first and than upload a BLOB in that Document.

In order to use BLOBs in Postman you have to make three different calls:

  • The first call is to initialize the upload

    Once initialized, copy the upload_id .

  • The second call uploads the file in binary form

    If you're using Postman you have to select the binary method in the "Body" panel and than choose the file you want to upload

    Note: you have to manually insert the length of the file in the header of the call!

    show how to get the length value

    If you're using Windows you can simply right-click on the file and copy the size value (not the size on disk one!)

    If you're using a Linux distribution or macOS you can use the following command line from the terminal

    stat "your-file-path"

    An example of output is the following:

    File: `bc.png' Size: 152708 Blocks: 299 IO Block: 4096 regular file Device: 14h/20d Inode: 108 Links: 1 Access: (0777/-rwxrwxrwx) Uid: ( 1000/ vagrant) Gid: ( 1000/ vagrant) Access: 2017-03-07 14:16:17.882794100 +0000 Modify: 2017-02-16 19:02:41.237824300 +0000 Change: 2017-02-16 19:02:41.237824300 +0000 Birth: -

    In this case the value to copy is 152708.

  • The third call commits the upload

Read all Documents

We can read all the Documents by getting the list of Documents inside a Schema.

Here an example on how to get the content of the Documents read.

Summary

We have created a System that manages Documents.

Notes

  • For a better use of Users and Permissions, follow the tutorial.