Insert a new volume

        Returns the ID of the added volume

        `metadata` must be a dict containg metadata of the volume::

            {
              "_language" : "it",  # language of the metadata
              "key1" : "value1",   # attribute
              "key2" : "value2",
              ...
              "keyN" : "valueN"
            }

            The only required key is `_language`


        `attachments` must be an array of dict::

            {
              "file"  : "/prova/una/path/a/caso" # path or fp
              "name"  : "nome_buffo.ext"         # name of the file (extension included) [optional if a path was given]
              "mime"  : "application/json"       # mime type of the file [optional]
              "notes" : "this file is awesome"   # notes that will be attached to this file [optional]
            }

def insert_volume(self, metadata, attachments=[]):
        '''Insert a new volume

        Returns the ID of the added volume

        `metadata` must be a dict containg metadata of the volume::

            {
              "_language" : "it",  # language of the metadata
              "key1" : "value1",   # attribute
              "key2" : "value2",
              ...
              "keyN" : "valueN"
            }

            The only required key is `_language`


        `attachments` must be an array of dict::

            {
              "file"  : "/prova/una/path/a/caso" # path or fp
              "name"  : "nome_buffo.ext"         # name of the file (extension included) [optional if a path was given]
              "mime"  : "application/json"       # mime type of the file [optional]
              "notes" : "this file is awesome"   # notes that will be attached to this file [optional]
            }

        '''

        log.debug("adding new volume:\n\tdata: {}\n\tfiles: {}".format(metadata, attachments))

        requiredFields = ['_language']
        for requiredField in requiredFields:
            if requiredField not in metadata:
                raise KeyError("Required field '{}' is missing".format(requiredField))

        volume = deepcopy(metadata)

        attsData = []
        for index, a in enumerate(attachments):
            try:
                attData = self._assemble_attachment(a['file'], a)
                attsData.append(attData)
            except Exception:
                log.exception("Error while elaborating attachments array at index: {}".format(index))
                raise
        volume['_attachments'] = attsData

        log.debug('constructed volume for insertion: {}'.format(volume))
        addedVolume = self._db.add_book(body=volume)
        log.debug("added new volume: '{}'".format(addedVolume['_id']))
        return addedVolume['_id']