Domain Model for Integrators

Overview

This guide provides an overview of how data is organized within ConceptShare. The primary domain model objects used to organize data are Accounts, Resources, Projects, Folders, Reviews, and Assets. It's important to understand these objects, their intended purpose, and their interrelations in order to effectively plan and design your integration.

Enumerated Model

1. Instance refers to the monolithic unit encapsulating all the data, services, and work that's performed. Whether your integration is running on a segregated, single-tenant instance, or running on our multi-tenant instance which serves dozens of clients; everything happens on a specific instance. For OEM integrations, you will be granted access to your own segregated instance which you will configure in accordance with your integration's requirements.
   
2. Instance Resources includes every user created within that instance. Account Resources, Project Resources and Review Resources are all Instance Resources (users on a particular instance). There are also instance-only users, who're granted access to the Admin Panel, but are not part of any accounts or projects. These is very typical of IT and instance administrators. When first provisioning your ConceptShare instance, we will create an instance-only user first, which you will then use to create new Accounts, and new Account Resources to administer those accounts.
   

3. Accounts are often used to define and separate users from different organizations (or in the case of larger organizations, used to separate different departments). An account is a top level container, and can be configured with its own sub-domain under the instance under which it is created.
   
4. Account Resources refers to any Instance Resource (people) that has been assigned to a particular Account. An Instance Resource may be assigned to any number of accounts, making them an Account Resource for each of those Accounts.
   
5. Projects hold sub-sets of Resources (users), Assets, and Reviews. They're best used as a container for users and work related to a specific deliverable. This deliverable may be one or a collections of Assets which need to undergo formal or ad-hoc Reviews. Assets added to a Project are visible (by default) to all Project Resources, and accessible from the Proofing Workspace under "Related Assets".
   
6. Project Resources are the sub-set of Account Resources who are assigned to work on a particular Project. When you create a Project, you must assign Project Resources to it from a list of Account Resources who have been assigned the role/permissions to work on Projects.
   
7. Project Assets refers to all files that are uploaded to ConceptShare. You can't upload Assets to an Account or an Instance, they must be contained within a Project. All assets placed in the same Project are visible (by default) to all Project Resources, and accessible from the Proofing Workspace under "Related Assets". A Project Asset can be annotated without a formal review. The resource URL for any given asset lead to the Proofing Workspace where that asset can be annotated.
   
8. Folders can optionally be used to further compartmentalize Assets and limit exposure and access. Folders do not limit sub-sets of Project Resources, but only filter access to only those Project Resources with the necessary permissions to view the contents of the Folder.
   
9. Reviews define feedback activity carried by to whom s assigned one or more Assets in the Project. The assignee(s) must be Project Resources, and the Assets must be in the same Project. As mentioned above (7), a Project Asset can be annotated outside of formal Reviews. You can set a flag to determine whether your Review should include all annotations, or only annotations from the specific Review.
   
10. Review Resources are the sub-set of Project Resources assigned to perform the particular Review.
    
    
11. Asset Versions are specific snapshots of an asset as they were uploaded to ConceptShare. Each time an asset is updated, the latest version in uploaded, and its previous versions are retained, along with their annotations. This allows ConceptShare to retain and track the entire progression and history of an asset as it undergoes feedback cycles. There are specific API function calls and Callbacks to differentiate between updates to an existing file vs creating a new Asset.
    

Additional Notes

Versioning Assets and Rollbacks

A common question about versioning assets is how to perform a rollback (undo an update to the file version) in the event of erroneous update to an asset. ConceptShare uses a chronological paradigm for asset versioning rather than a purely numeric. As a result, if an asset was incorrectly versioned, rather than rolling it back, we expect to correct the error by versioning the next iteration of the asset with the correct file. We don't support rollbacks in order to accurately and wholly preserve the chronological order of events. A rollback within this design paradigm would be like trying to turn back time, and defeats the purpose of audit trails and logs which are meant to capture the entirety of activity surrounding an asset.

Permissions and Roles

The topic of permissions & roles is somewhat out of the scope of this guide, but it's worth noting some of the major highlights.Every Account Resource has an Account Role. This role determines what account settings that user can modify (ex. adding/removing other Account Resources to the Account).

Every Account Resource also has a Default Project Role. This default role is used anytime the user is added as a Project Resource without explicitly defining their Project Role. The default project role can be overridden on a per-project basis. This means that the same Account Resource can play different roles on different projects. The project role defines what modifications a user can make within that project (ex. commenting, modifying assets, adding/removing other Project Resources, etc...).

ConceptShare comes with predefined roles (Account Administrators, Project Administrators, Commentator, etc...) , but also supports the ability to create Custom Account Roles and Custom Project Roles.