Using the Smashdocs API from Python

In order to use Smashdocs from Python you need to obtain the following data from your Smashdocs provider:

  • Partner URL (URL of Smashdocs service)
  • Client ID (used for authentication)
  • Client Key (used for authentication)

Prequisite

The following examples are written for Python 2.7 and use unicode strings as parameters. In general all parameters must be passed as unicode strings (not as UTF-8 encoded byte strings). Unicodeness is strongly checked. There is no implicit conversion from utf-8 parameters to unicode strings.

Creating client handle to Smashdocs

from zopyx.smashdocs.api import Smashdocs

# first you need to instantiate a client instance of the `Smashdocs`
# connector class. The `group_id` is used to group all documents together
# belonging to a particular user group (e.g. a work group working on one or more
# document). The `client` is from now on used for all interactions with Smashdocs.

client = Smashdocs(partner_url, client_id, client_key, group_id)

Upload a DOCX document to Smashdocs

The following code will upload a given DOCX file from the local filesystem into Smashdocs and create a document instance inside Smashdocs. The API call returns all relevant data including the document id of the document inside Smashdocs and an URL that can be used open the uploaded document inside your browser for editing.

The filename parameter is the path to a locally stored DOCX file. title and description are arbitrary unicode strings (metadata length restrictions apply and are partly checked within the module).

The role parameter is one of the four roles in Smashdocs:

  • reader
  • commentator
  • editor
  • approver

You also need a user_data datastructure containing information about the current user using the Smashdocs API. The fields of the dict structure are obvious. Please keep in might that Smashdocs does not provide you with an explicit user management. The userId field represents the user within Plone.

user_data = dict(
    email=u'test@foo.com',
    firstname=u'Henry',
    lastname=u'Miller',
    userId=u'testuser',
    company=u'Dummies Ltd')


result = client.upload_document(
    filename='sample.docx',
    title=u'My document',
    description=u'My description',
    role='editor',
    user_data=user_data)

# preserve the id of the document in Smashdocs for further usage
document_id = result['documentId']

# this URL can be used to access the uploaded document through the browser
document_url = result['documentAccessLink']

Creating a new empty document

Creating a new empty document works exactly the same way as uploading a DOCX file except that you do not need any document here.

result = client.new_document(
    title=u'My document',
    description=u'My description',
    role='editor',
    user_data=user_data)

# preserve the id of the document in Smashdocs for further usage
document_id = result['documentId']

# this URL can be used to access the uploaded document through the browser
document_url = result['documentAccessLink']

Open an existing Smashdocs document by its ID

With a given document_id you can open (obtain its access URL) using the following code. In this case we open the document for read-only access (role=reader) with a different user context.

user_datai2 = dict(
    email=u'mike@foo.com',
    firstname=u'Mike',
    lastname=u'Reader',
    userId=u'mike-reader',
    company=u'Dummies Ltd')

result = client.open_document(document_id, 'reader', user_data2)

# this URL can be used to access the uploaded document through the browser
document_url = result['documentAccessLink']

Archiving and unarchiving a Smashdocs document

The API provides the following two methods for archiving and unarching a Smashdocs document given by its document_id.

client.archive_document(document_id)

client.unarchive_document(document_id)

Trying to archive or unarchive a document twice will lead to an API exception.

Deleting a Smashdocs document

A Smashdocs document given by its document_id can be deleted using delete_document().

client.delete_document(document_id)

Trying to delete a document twice will lead to an API exception.

Duplicating Smashdocs content

An existing Smashdocs document can be duplicated with a new title and a new description. The API call return a new document id and an new access URL.

result = client.duplicate_document(
         document_id,
         title=u'new title',
         description=u'new description',
         creator_id='some_user_id)

 new_document_id = result['documentId']
 new_document_url = result['documentAccessLink']

Listing word templates

An export to word requires a word template. This API method returns a list of available word templates with id, name and description. See also https://documentation.smashdocs.net/api_guide.html#get-partner-templates-word

templates = client.list_templates()

Exporting content

You can export Smashdocs content to either HTML, SDXML or DOCX. Both HTML and SDXML exports produce a ZIP file (index.xml + images/* subfolder).

output_filename = client.export_document(
         document_id,
         format='docx',
         template_id=docx_template_id, # see above)
         user_id='admin')