Integration SDK

What is the Integration SDK?

The SMASHDOCs Integration SDK is a JavaScript Development kit which allows a partner to integrate the SMASHDOCs application seamlessly into his own application.

Besides the SMASHDOCs Integration SDK a partner also has the option to use the SMASHDOCs Partner API for an integration. Using the Partner API a partner has to implement the user interface, modals and forms by himself but gives the advantage of full flexibility

The Integration SDK aims for an easy integration and full control over all styles of the integration but without the need for any implementation of modals, forms, etc. Both options can of course be used in parallel.

Currently the Integration SDK provides the functions:

  1. Creating new documents (with all necessary fields)
  2. Importing documents from word files
  3. Rendering the document list for a context or group
  4. Editing the documents metadata

An example for a seamless integration is shown in the screenshot below:

_images/sdk_integration_example.png

Prerequisites

  1. Partner API credentials to SMASHDOCs (client-id, client-secret)
  2. SMASHDOCs Integration SDK (including an api-key)
  3. A backend to backend integration for secure authentication

Glossary

  • partner system: is the system where SMASHDOCs should be integrated in
  • context / group: the logical context in which the document will be created. This can be a group, a context, a case file, a process, etc. For SMASHDOCs the parameter is called group but can be used from a partner for any logical context.
  • user / partner user: the user of the partners system

Getting started

Using the Integration SDK requires users to be synchronize between the partner application and SMASHDOCs. To reduce the overhead and error-proneness of any user sync process SMASHDOCs integrations will require the partner application to create or update users on the fly. This means that a partner must authenticate a user (known and unknown to SMASHDOCs) before initializing the Integration SDK. Unknown users will be created on the fly and will be updated by its given ID on the next authentication. This authentication must be done in a Backend-to-Backend authentication for security reasons.

Therefore an integration consists of 2 steps

User synchronization

This example assumes that a user with the name “Steven Miller” (email: “steven.miller@yourcompany.net” and ID “8c975c52”) is logged into the partner system. Before the partner system can initialize the Integration SDK this user must be synchronized with SMASHDOCs.

The synchronization call to the SMASHDOCs API contains the user information as well as information about his groups / contexts he has access to. Besides the group access the corresponding SMASHDOCs role must be given (Users, Groups and Roles).

In the example Steven Miller belongs to group ID 467f34 with role editor and group ID 92aa37 with role approver.

With the usage of the SMASHDOCs API endpoint POST /partner/users/{id} the following request and response will be sent and received. For request authentication JWT is used as described here api_guide.html#authentication.

URL: https://your-cloud-api.smashdocs.net/partner/users/8c975c52
METHOD: POST
Headers:
    "x-client-id": "24703d6ac0938445c78ed6911c52a1e34929f7928606ed2f5ef454c671abc3f1",
    "content-type": "application/json",
    "authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0OTY4MjgyMzUsImlzcyI6IjhjOTc1YzUyMjZjOTZkNzBjODQyOTRkOTdkNGU5Y2M5Mjk1OTVjZDIiLCJqdGkiOiI0NjhiMDlkMi1hMWFmLTRjZTEtYmU4Yi02ZmUyOThjYjc3ZWUifQ.IhzW5cnUI55I0wjN6uuvTH0YY-Sklj6weY3kGtdgV9I"
Request Payload:
{
    "firstname": "Steven",
    "lastname": "Miller",
    "email": "steven.miller@yourcompany.net",
    "language": "en_US",
    "groups": [
        {
            "id": "467f34",
            "role": "editor"
        },

        {
            "id": "92aa37",
            "role": "approver"
        }
    ]
}

Response:
{
    "accesstoken": "399610aacca6d68d0cc84ba256f40f65996360c7dfa1caef95f824afe690a7c0"
}

The accesstoken in the response will be used in the next step for the initialization of the SDK.

Integrating the JavaScript and CSS files

The integration SDK consists of simply 2 files. The main.css and the smashdocs-integration-sdk-1.0.0.js. Both files can be either downloaded from our bitbucket repository or can be build manually from the code and should be integrated in the body of your application.

<link rel="stylesheet" href="main.css">
<script src="main.bundle.js"></script>

For an easy integration and full flexibility all elements of the SDK will render all HTML into given Div HTML elements. The most simple integration in this example will contain a Button for creating a SMASHDOC and list of all documents of a given context or group.

Therefore the 2 Div HTML Elements “createDocumentButtonContainer” and “doclistContainer” need to be inside of the scope of your HTML.

<div id="createDocumentButtonContainer">This will be the create document Button.</div>
<div id="doclistContainer">This will be the document list.</div>

Now the SDK can be initialized for the current user and group by passing the user’s accesstoken received from the SMASHDOCs backend and the groupId. Additional, your application’s apiKey has to be passed for the init.

<script>
var sdk = new SmashdocsSdk({
    token: "399610aacca6d68d0cc84ba256f40f65996360c7dfa1caef95f824afe690a7c0",
    groupId: "92aa37",
    apiKey: "2c2a39ddc739ee9878e690d79aaae6942d490fe7c35e88f87a66d2f29d79d062" # provided by SMASHDOCs with the SDK
});
</script>

Linking the HTML Div Elements to the SDK will render the document list and the create new document Button.

<script>
sdk.getDocumentsList('#doclistContainer');
sdk.createDocument('#createDocumentButtonContainer');
</script>

The Integration SDK will use the default style from the main.css which can be overwritten without any problem as described in section Building and styling the SDK.

Users, Groups and Roles

In the Integration API we distinguish between users, groups and roles which are controlled by the partner application and sent via a backend to backend request to the SMASHDOCs API (User Synchronization and Authentication).

One user can be member or has access to none to many groups/contexts. In each group/context this user must be given certain SMASHDOCs role (“reader”, “commentator”, “editor” or “approver” api_guide.html#overview-over-smashdocs). This SMASHDOC role must be mapped from the partners system rights/roles while registering the user at the SMASHDOCs API.

In one group/context a user that has access to the group/context can create many draft documents, which are first visible for just this user until shared for review (document state = review). Only review documents are visible for other users inside this group and can be opened by anyone of these users. The mapped SMASHDOCs roles then limit the actions which can be taken.

Please note that a user with the SMASHDOCs role “reader” or “commentator” will be able to create draft documents. When setting these documents to review the user will become a “reader” or “commentator” in his created review document. To prevent such constellations it is up to the partner to show the create button to these users in the first place.

User Synchronization and Authentication

For a seamless integration of SMASHDOCs into a parter system a robust user syncing process is required. Therefore the SMASHDOCs Integration SDK provides an easy create or update user syncing process which allows the partner system to create or update users on the fly.

The SMASHDOCs identifies the user by the given ID, all other properties like email, names etc can change and must be send with every authentication request to be possibly refreshed. The ID can be the partner systems user id or any other generated identifier of a user.

If the partner system authenticates the user he must send the user properties as well as the group/context access and group/context roles.

The authenitcation is done by the following SDK-API endpoint:

POST https://your-cloud-api.smashdocs.net/partner/users/{id}

Following fields are possible to send as user properties:

firstname string
lastname string
company string (optional)
email string
language string (optional) possible values: de_DE, en_US
groups array of group objects

A group object consists of two required fields:

id string
role reader, commentator, editor or approver

The list of group objects gives the information which role the user holds in the groups he belongs to.

For the HTTP headers, there are three required fields:

x-client-id <your client id>
content-type application/json
authorization Bearer <generated JWT token>

The “authorization”-field contains a signed JWT token. Creating the JWT works analogue to section “Authorization” in the documentation of the Partner-API api_guide.html#authentication.

Initialize the SMASHDOCs SDK

Initialization of the SMASHDOCs SDK is done by instantiating the SmashdocsSdk JavaScript class. This instance is created for a user in a certain group.

Parameters are passed as one object with the following properties:

token string the user’s accesstoken, received from the SMASHDOCs backend
groupId string id of group for which the SDK should be initialized. It is required that the same id had been sent to the backend when pushing the user properties
apiKey string your api key provided by SMASHDOCs
language string (optional) language, in which the SDK will be rendered. Possible is en_US or de_DE.
errorCallbacks object Functions for error handling can be passed here

example:

var sdk = new SmashdocsSdk({
    token: accesstoken,
    groupId: groupId,
    apiKey: apiKey,
    errorCallbacks: {
       authorizationFailed: function (htmlMessage) {
           console.debug('SMASHDOCS SDK authorization failed', htmlMessage);
       },
       loadDocumentListFailed: function (htmlMessage) {
           console.debug('SMASHDOCS SDK loading document list failed', htmlMessage);
       }
    }
});

UI Scenarios

Once the SDK is instantiated, there are different scenarios that can be rendered for the authenticated user with the Integration SDK. For each scenario, a HTML DIV Element has to be passed, wherein the correspondent modal dialogue or list is rendered.

With this approach, you are most flexible in placing and sizing the SDK-modals.

Rendering the user’s document list is easily done through calling function “getDocumentsList” on the SDK-instance, where the HTML DIV Element ID is passed as single required argument, which is shown in the following example:

sdk.getDocumentsList('#doclistContainer');

Opening the documents is handled directly in the SDK. The user just clicks on a document and it will open in a new tab.

If there is the need to show multiple groups on one page it is necessary to initialize the SmashdocsSdk class again with a different variable name.

The HTML DIV Element ID for the create document button is passed to the SDK instance via the function “createDocument”.

There are two ways for displaying the document creation form a partner can choose from:

  1. Using the provided modal dialogue from SMASHDOCs including all validation, free to style.
  2. Rendering the form in an existing HTML DIV Element provided by the partner also including validation, free to style.

Choose between option a) and b) by providing the optional “formContainerSelector” HTML DIV Element ID.

buttonContainerSelector string # followed by id of div-element where to render the create-document-button
formContainerSelector string (optional) # followed by id of div-element where the create-document-modal is shown. If not set, the modal will be shown in the center of the same browser tab.

example:

sdk.createDocument('#createDocumentContainer', '#optionalCreateDocumentModalContainer');

The approach for integrating the import from word functionality is similar to create empty documents: One HTML DIV Element ID is passed for the import-from-word-button and one optional HTML DIV Element ID can be passed for the modal dialogue.

buttonContainerSelector string # followed by id of div-element where to render the create-document-button
formContainerSelector string (optional) # followed by id of div-element where the create-document-modal is shown. If not set, the modal will be shown in the center of the browser tab.

example:

sdk.importFromWord('#importWordContainer', '#optionalImportWordModalContainer');

Building and styling the SDK

In order to style the SDK a partner has to override the css styles in the main.css. This main.css can also be generated by changing the variables in the src/variables.scss found in the source code of the Integration SDK.

To build the SMASHDOCs Integration SDK simply run:

# install all dependencies.
npm i

# Build your app without minification:
npm run build

# Build your app with minification:
npm run build.prod