Provisioning API Documentation

The Provisioning API provides possibilities to create and modify organizations.

Authentication

All provisioning API calls are authenticated with a JWT, which is created analog to section Authentication. iat (Issued At), iss (Issuer) and jti (JWT ID) are required fields for the JWT payload. The token is signed with the provisioning key and passed as Bearer <JWT> in the authorization field of the headers. The x-client-id-field is not needed here, because the provisioning will affect the whole SMASHDOCs installation.

Important

The provisioning key for provisioning call is different from the partner API authentication credentials

Code example: JWT in Python

import jwt
import uuid
import datetime

# provided provisioning_key
provisioning_key = '32284ebdc5b8ea867058155b6ebcd7e0f9b0ed0ce2953b0451d9e6dbc9a68e70'

# user_id which issues the provisioning request
user_id = '5813099d5cb91899eea6da05'

jwt_payload = {
    'iat': int(datetime.datetime.now().timestamp()),
    'iss': user_id,
    'jti': str(uuid.uuid4())
}
token = jwt.encode(payload=jwt_payload, key=provisioning_key, algorithm="HS256")
bearer_token = "Bearer {token}".format(token)
print(bearer_token)

Provisioning options

Create Organization

A new organization can be created via POST /provisioning/organization. The organization is initialised with the default smashdocs branding and without any word templates.

In the json request payload, two parameters can be passed:

  • name is the organization’s name (required).
  • replacement_url is an url which is used to to make documents accessible via the partner system. This url must contain the string {doc_id} (e.g. https://partner_url.com/smashdocs/sessions/{doc_id}) which will be replaced with the SMASHDOCs document id. When this url is opened, the partner system has to check the users rights to that document, open the document via the partner api and redirect the user to the documentAccessUrl via HTTP-302.
  • add_default_word_template is an optional boolean parameter which determines, whether the default word template is added to the newly created organization.

The response of the API call contains credentials that are necessary for further calls in the partner API and the organization id.

Get Organizations

The info regarding all existing organizations can be fetched via GET /provisioning/organization. The response contains a list of objects with the following fields:

  • uuid: Identifier for this organization object
  • name: Organization name
  • features: Information about enabled features and limits
  • word_templates: List of word template objects
  • epub_templates: List of epub template objects
  • indesign_templates: List of indesign template objects
  • conversation_keys: List of conversation type keys that are configured in this organization

Validate credentials

Once an organization is created the client-id and client-secret credentials can be validated

In the json request payload, two parameters can be passed:

  • client-id (required).
  • client-secret (required)

The response of the validation call will either return HTTP 200 or HTTP 404 if the credentials could not be validated

Add a Word Template (optional)

The API call POST /provisioning/organization/{organization_id}/word/upload gives the possibility to add a word template to the organization. The organization id has to be passed as path parameter. In the Request Payload of type “multipart/form-data”, there are two fields:

  • file contains the Word-template itself as docx-file.
  • data contains a json string with additional fields, which determine title and description of the word template.

The id of the new created word template is returned.

Hint

Please find a code example for multipart/form-data uploads here: api_guide.html#importing-word-documents

Update an existing Word Template (optional)

A word template can be updated via POST /provisioning/organization/{organization_id}/word/{template_id}/upload. This call works similar to the create word template call: Additional is only the path parameter template_id, the rest is the same.

The organization id has to be passed as path parameter. In the Request Payload of type “multipart/form-data”, there are two fields:

  • file contains the Word-template itself as docx-file.
  • data contains a json string with additional fields, which determine title and description of the word template.

The id of the updated word template is returned.

Hint

Please find a code example for multipart/form-data uploads here: api_guide.html#importing-word-documents

Upsert a conversation type in an organization

Inserting or updating a conversation type can be done with the api endpoint POST /provisioning/organization/<organization_id:uuid>/conversation-types/<conversation_type_key>.

Path variables are the organization_id and the conversation_type_key.

The json request payload contains all data about the conversation type, which consists of:

  • translated name
  • metadata fields
  • option, whether resolved-functionality is enabled
  • list that determines, which field of the metadata is shown in the list of conversations in the document

A single metadata field consists of the information regarding:

  • human readable field key
  • translated name
  • translated tooltip text
  • field type:
    • text
      • height in lines
      • max length
      • default value: can be empty, clean_section or redline_section
    • dropdown
      • choices
      • default value
    • checkbox
      • default value
  • roles that are required to view, create or update this field
  • is required field
  • is tracked field
  • changelog message if it is tracked field
  • is filter for conversation list
  • is filter for export

A detailed description of all keys and values is contained in the jsonschema-file dynamicConversationConfiguration.json

Get conversation type

Information about a certain conversation type in an organization can be fetched via GET /provisioning/organization/<organization_id:uuid>/conversation-types/<key>.

Fields of the response are described in the section Upsert a conversation type in an organization

Examples

POST /provisioning/organization

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization
METHOD: POST
Headers:
    content-type: application/json
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI1MzAsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjcyZTE1NjU2LWYzZDQtNGZhYS05MWNmLWQ1NWJjZjdjYzhmMCJ9.pDmg-kV-bzgDdDTZL5Kn4CgOgPGYpiTdnd9xfwNvROY

Payload:
    {
        "name": "myorganization",
        "replacement_url": "https://smashdocs.myorganization.com/documents/{doc_id}"
    }
RESPONSE:
    {
        "jwt_auth": {
            "client_secret": "1199a4d4052c23d990a402f44c12a73d7db3f80c213380b3da67501cad64a211",
            "client_id": "2fc28f3bdfa2e041f4674f485cfb0393e194ea9b012c1cdbaf62258ac641c62f"
        },
        "password_auth": {
            "superuser_password": "eG5r^Nf@%G|0e/3*ep3}'|`(@,g{EBtu",
            "superuser_email": "myorganization@smashdocs.net"
        }
        "id": "d39f9433-00b3-424b-b797-3e23c0d44d56"
    }

GET /provisioning/organization

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization
METHOD: GET
Headers:
    content-type: application/json
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI1MzAsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjcyZTE1NjU2LWYzZDQtNGZhYS05MWNmLWQ1NWJjZjdjYzhmMCJ9.pDmg-kV-bzgDdDTZL5Kn4CgOgPGYpiTdnd9xfwNvROY
RESPONSE:
[
  {
    "uuid": "d39f9433-00b3-424b-b797-3e23c0d44d56",
    "conversation_keys": [
    ],
    "epub_templates": [
    ],
    "features": [
    ],
    "indesign_templates": [
    ],
    "name": "myorganization",
    "word_templates": [
    ]
  }
]

POST /provisioning/validate

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/validate
METHOD: POST
Headers:
    content-type: application/json
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI1MzAsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjcyZTE1NjU2LWYzZDQtNGZhYS05MWNmLWQ1NWJjZjdjYzhmMCJ9.pDmg-kV-bzgDdDTZL5Kn4CgOgPGYpiTdnd9xfwNvROY

Payload:
    {
        "client-id": "2fc28f3bdfa2e041f4674f485cfb0393e194ea9b012c1cdbaf62258ac641c62f",
        "client-secret": "1199a4d4052c23d990a402f44c12a73d7db3f80c213380b3da67501cad64a211"
    }

POST /provisioning/organization/{organization_id}/word/upload

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization/d39f9433-00b3-424b-b797-3e23c0d44d56/word/upload
METHOD: POST
Headers:
    content-type: multipart/form-data
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI2MzEsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6ImI5ZDVhNjk5LWRkNzEtNGNlNi1iYjQwLTIzYjQ4ZjZjYmQ1ZSJ9.EIV11J1vQ1Cv0jWDbNr6d1N63ZCmvqMpZoPExu_TeI0

Payload:
    "file":
         << DOCX - FILE >>
    "data":
        {
            "title": "standard",
            "description": "this is standard template"
        }
RESPONSE:
    {
        "template_id": "75ab3ebf-ad60-44ec-87bf-1248c9568bf6"
    }

POST /provisioning/organization/{organization_id}/word/{template_id}/upload

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization/d39f9433-00b3-424b-b797-3e23c0d44d56/word/75ab3ebf-ad60-44ec-87bf-1248c9568bf6/upload
METHOD: POST
Headers:
    content-type: multipart/form-data
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI3NTEsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjllZjZjNzQ0LTg1MTEtNGEzZi04YTkzLTE2NDhkMGVlNDgxYiJ9.o5HLHZWhZ8HQ2-PFW7BnraR6CWhuH0WrsdJVPd7ElRY

Payload:
    "file":
         << DOCX - FILE >>
    "data":
        {
            "title": "standard",
            "description": "this is my changed description"
        }
RESPONSE:
    {
        "template_id": "75ab3ebf-ad60-44ec-87bf-1248c9568bf6"
    }

POST /provisioning/organization/{organization_id}/conversation-types/{conversation_type_key}

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization/d39f9433-00b3-424b-b797-3e23c0d44d56/conversation-types/comment
METHOD: POST
Headers:
    content-type: application/json
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI3NTEsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjllZjZjNzQ0LTg1MTEtNGEzZi04YTkzLTE2NDhkMGVlNDgxYiJ9.o5HLHZWhZ8HQ2-PFW7BnraR6CWhuH0WrsdJVPd7ElRY

Payload:
{
  "display_key": [
    "subject",
    "description"
  ],
  "fields": [
    {
      "editable_for": [
        "ADMIN",
        "creator"
      ],
      "is_export_filter": false,
      "is_list_filter": false,
      "key": "subject",
      "name": {
        "de_DE": "Betreff",
        "en_EN": "Subject"
      },
      "required_role_to_view": "reader",
      "requirement_specific": {
        "is_required_field": false,
        "required_role_to_create": "commentator"
      },
      "tooltip_text": {
        "de_DE": "Betreff hier eingeben (optional)",
        "en_EN": "Type subject here (optional)"
      },
      "tracking_specific": {
        "is_tracked_changes": true,
        "stream_change_message": {
          "de_DE": "{actorName} hat den Betreff geändert: {redline}",
          "en_EN": "{actorName} has changed the subject: {redline}"
        }
      },
      "type_specific": {
        "default_value": "empty",
        "field_type": "DynamicConversationTextfield",
        "height_in_lines": 1,
        "max_length": 1000,
        "static_field": false
      }
    },
    {
      "editable_for": [],
      "is_export_filter": false,
      "is_list_filter": false,
      "key": "description",
      "name": {
        "de_DE": "Beschreibung",
        "en_EN": "Description"
      },
      "required_role_to_view": "reader",
      "requirement_specific": {
        "is_required_field": true,
        "validation_error_message": {
          "de_DE": "Beschreibung ist ein Pflichtfeld",
          "en_EN": "Description is a mandatory field"
        }
      },
      "tooltip_text": {
        "de_DE": "Beschreibung hier eingeben",
        "en_EN": "Type description here"
      },
      "tracking_specific": {
        "is_tracked_changes": false
      },
      "type_specific": {
        "default_value": "empty",
        "field_type": "DynamicConversationTextfield",
        "height_in_lines": 4,
        "max_length": 1000,
        "static_field": false
      }
    },
    {
      "editable_for": [
        "ADMIN",
        "approver"
      ],
      "is_export_filter": false,
      "is_list_filter": true,
      "key": "priority",
      "name": {
        "de_DE": "Priorität",
        "en_EN": "Priority"
      },
      "required_role_to_view": "approver",
      "requirement_specific": {
        "is_required_field": false,
        "required_role_to_create": "approver"
      },
      "tooltip_text": {
        "de_DE": "Priorität ist hier auswählbar",
        "en_EN": "Priority is possible to be selected here"
      },
      "tracking_specific": {
        "is_tracked_changes": true,
        "stream_change_message": {
          "de_DE": "{actorName} hat die Priorität von {oldValue} auf {newValue} gesetzt.",
          "en_EN": "{actorName} has set the priority from {oldValue} to {newValue}."
        }
      },
      "type_specific": {
        "choices": [
          "0",
          "1",
          "2"
        ],
        "default_value": null,
        "field_type": "DynamicConversationDropdown"
      }
    },
    {
      "editable_for": [
        "ADMIN",
        "approver"
      ],
      "is_export_filter": true,
      "is_list_filter": true,
      "key": "urgent",
      "name": {
        "de_DE": "dringend",
        "en_EN": "urgent"
      },
      "required_role_to_view": "reader",
      "requirement_specific": {
        "is_required_field": false,
        "required_role_to_create": "approver"
      },
      "tooltip_text": {
        "de_DE": "Klicken, um zu bestimmen, ob dieser Kommentar dringend ist",
        "en_EN": "Click to determine whether this conversation is urgent"
      },
      "tracking_specific": {
        "is_tracked_changes": true,
        "stream_change_message": {
          "de_DE": "{actorName} hat dringend auf {newValue} gesetzt.",
          "en_EN": "{actorName} has set urgent to {newValue}."
        }
      },
      "type_specific": {
        "default_value": false,
        "field_type": "DynamicConversationCheckbox"
      }
    }
  ],
  "key": "comment",
  "name": {
    "de_DE": "Kommentar",
    "en_EN": "Comment"
  },
  "show_resolved": true
}
RESPONSE:
  status: 200

GET /provisioning/organization/{organization_id}/conversation-types/comment

REQUEST:

URL: https://partner-api.smashdocs.net/provisioning/organization/d39f9433-00b3-424b-b797-3e23c0d44d56/conversation-types/comment
METHOD: GET
Headers:
    content-type: application/json
    authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE0Nzc2NDI1MzAsImlzcyI6IjU4MTMwOTlkNWNiOTE4OTllZWE2ZGEwNSIsImp0aSI6IjcyZTE1NjU2LWYzZDQtNGZhYS05MWNmLWQ1NWJjZjdjYzhmMCJ9.pDmg-kV-bzgDdDTZL5Kn4CgOgPGYpiTdnd9xfwNvROY
RESPONSE:
{
  "display_key": [
    "subject",
    "description"
  ],
  "show_resolved": true,
  "name": {
    "en_EN": "Comment",
    "de_DE": "Kommentar"
  },
  "key": "comment",
  "fields": [
    {
      "editable_for": [
        "ADMIN",
        "creator"
      ],
      "required_role_to_view": "reader",
      "requirement_specific": {
        "is_required_field": false,
        "required_role_to_create": "commentator"
      },
      "key": "subject",
      "tracking_specific": {
        "is_tracked_changes": true,
        "stream_change_message": {
          "en_EN": "{actorName} has changed the subject: {redline}",
          "de_DE": "{actorName} hat den Betreff geändert: {redline}"
        }
      },
      "type_specific": {
        "default_value": "empty",
        "height_in_lines": 1,
        "max_length": 1000,
        "field_type": "DynamicConversationTextfield",
        "static_field": false
      },
      "name": {
        "en_EN": "Subject",
        "de_DE": "Betreff"
      },
      "is_list_filter": false,
      "is_export_filter": false,
      "tooltip_text": {
        "en_EN": "Type subject here (optional)",
        "de_DE": "Betreff hier eingeben (optional)"
      }
    },
    {
      "editable_for": [],
      "required_role_to_view": "reader",
      "requirement_specific": {
        "is_required_field": true,
        "validation_error_message": {
          "en_EN": "Description is a mandatory field",
          "de_DE": "Beschreibung ist ein Pflichtfeld"
        }
      },
      "key": "description",
      "tracking_specific": {
        "is_tracked_changes": false
      },
      "type_specific": {
        "default_value": "empty",
        "height_in_lines": 4,
        "max_length": 1000,
        "field_type": "DynamicConversationTextfield",
        "static_field": false
      },
      "name": {
        "en_EN": "Description",
        "de_DE": "Beschreibung"
      },
      "is_list_filter": false,
      "is_export_filter": false,
      "tooltip_text": {
        "en_EN": "Type description here",
        "de_DE": "Beschreibung hier eingeben"
      }
    },
    {
      "editable_for": [
        "ADMIN",
        "approver"
      ],
      "required_role_to_view": "approver",
      "requirement_specific": {
        "is_required_field": false,
        "required_role_to_create": "approver"
      },
      "key": "priority",
      "tracking_specific": {
        "is_tracked_changes": true,
        "stream_change_message": {
          "en_EN": "{actorName} has set the priority from {oldValue} to {newValue}.",
          "de_DE": "{actorName} hat die Priorität von {oldValue} auf {newValue} gesetzt."
        }
      },
      "type_specific": {
        "default_value": null,
        "choices": [
          "0",
          "1",
          "2"
        ],
        "field_type": "DynamicConversationDropdown"
      },
      "name": {
        "en_EN": "Priority",
        "de_DE": "Priorität"
      },
      "is_list_filter": true,
      "is_export_filter": false,
      "tooltip_text": {
        "en_EN": "Priority is possible to be selected here",
        "de_DE": "Priorität ist hier auswählbar"
      }
    },
    {
      "editable_for": [
        "ADMIN",
        "approver"
      ],
      "required_role_to_view": "reader",
      "requirement_specific": {
        "is_required_field": false,
        "required_role_to_create": "approver"
      },
      "key": "urgent",
      "tracking_specific": {
        "is_tracked_changes": true,
        "stream_change_message": {
          "en_EN": "{actorName} has set urgent to {newValue}.",
          "de_DE": "{actorName} hat dringend auf {newValue} gesetzt."
        }
      },
      "type_specific": {
        "default_value": false,
        "field_type": "DynamicConversationCheckbox"
      },
      "name": {
        "en_EN": "urgent",
        "de_DE": "dringend"
      },
      "is_list_filter": true,
      "is_export_filter": true,
      "tooltip_text": {
        "en_EN": "Click to determine whether this conversation is urgent",
        "de_DE": "Klicken, um zu bestimmen, ob dieser Kommentar dringend ist"
      }
    }
  ]
}