Selecting An Integration Strategy

Terminology

• 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 (acme.yourcompany.conceptshare.com). 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. sales.acme.conceptshare.com , marketing.acme.conceptshare.com). 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.

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