Selecting An Integration Strategy

January 01, 2020


  • Instance – This is the term used to describe an entire functional installation of ConceptShare and all of its running components.
  • Account – A ConceptShare account is tied to a specific domain (or more typically a sub-domain of the instance) such as ( Most integrators will opt to provision multiple accounts on the same instance, choosing to keep clients, departments, or even larger teams in separate accounts (ex. , Accounts act as containers, allowing you to organize projects and manage users such that access is limited to only those users in that account.
  • User – This relates to a particular individual within the ConceptShare system.
  • Project – Inside an account, a project is the top-level container used to organize a collection of assets, the users who have access to them, and any reviews created for these users and assets.
  • Asset – This refers to a digital document within the ConceptShare system. This can be images, documents like Word, Excel, PDF, audio/video, etc.
  • Resource – This is term that refers to a user of either an instance, account, or a project. It can a human being or another system acting via the API.
  • Review – This is a formal process/functionality which allows the host application to solicit approvals from individuals on assets.
  • Reviewer – This refers to a particular user who is part of a review.

Read ConceptShare's Domain Model for Integrators for more details about how these object are related.

ConceptShare Side-by-Side Integration Model

A side-by-side integration, where two systems work together, while each is capable of fully independent operation, user-access, credentials, etc. These two independent systems still facilitate data exchange when certain trigger events occur that help automate tasks and provide business value. This is a common model of integration for SaaS products; when event A happens in system X, perform some action in the configured ConceptShare account.

ConceptShare Embedded Integration Model

An embedded (a.k.a. OEM) integration, is a closed loop integration whereby ConceptShare effectively becomes a widget/tool (via an iframe) of another host system. All data flow and user credentials are be managed by the host system, and ConceptShare is not independently accessible to users. Typically, in these OEM style embedded integrations, the end-user doesn't even realize that the Proofing Workspace presented in the ConceptShare iframe is actually driven by another system.

Figuring out which integration model is most suitable for your context is the primary and key step to a successful integration. Each model, implies certain constraints and freedoms with respect to both the commercial and technical aspects of the integration. We'll outline some of these considerations below.

Before delving too deep into any technical design for an integration, you will need to weigh the pros and cons of each type of integration. While the core Review & Approval functionality remains largely unchanged between the two integration types, there are several (potentially key) capabilities that may not be available depending on the style of integration you choose. It's important to understand the implications of each approach. For example;

Is it possible for end-users to access ConceptShare independent of the integration?
The point here is whether or not the integration needs to account for user actions in ConceptShare taken outside the scope of the integration. Depending on your use-cases and requirements, it may not have much impact, or it may highlight additional requirements to ensure that certain activities that users perform (whether through the integration or via direct access to ConceptShare), be reflected in the adjacent product.

Will the integration be able to function with existing ConceptShare customers who already have accounts?
If the answer here is yes, it means you should not design the integration with the assumption that you will have administrative privileges on the account, since you as the integrator, don’t own that account. Instead, the customer owns their own account, and configures your integration to allow you access, typically in the form of a ConceptShare API user with Account Admin level access to carry out your requests. As such, you should not rely on any calls in the API that would require administrative access or Partner Tokens/Keys.

Is the integration to be built such that it could be pointed to any preexisting ConceptShare instance, or will it only be pointed at dedicated instances, with full administrative access and Partner Token/Keys for making privileged API calls?
Similar to the question above, and with mostly the same implications. If the instance is solely owned and managed by you as the integrator, then you have full privileges and can manage all aspects of the instance settings, account settings, roles, users, accounts, etc... On the other hand, if you’re pointing at an unspecified target, you can’t make any assumptions about what roles exist, what users exists, what modules are or aren’t available, what each user’s role allows or disallows. All these variables need to be acquired. Also, since you don’t own the account, you cannot make privileged API calls that require Partner Tokens/Keys.

Another method to aid your decision making would be through a capability matrix.

Capability Matrix

Private Instance OEM Public Account
Proofing Workspace UI X X X
Admin Panel UI X X
Management App UI X X
Mobile App X X
Email Notifications X X
Standalone Access X X
Account Management X X partial
Account Creation X X
Project Management X X X
User Management X X X
Asset Management X X X
Roles & Permissions X X partial
Review Dialog UI X X
Instance level callback events X X
Account level callback events X X X