Getting Started With Integrations

Before you start …

ConceptShare can be integrated in in a number of fundamentally different and mutually exclusive ways. Understanding the advantages and limitations of each approach prior to design and implementation is critical to a successful design and delivery for an integrated solution. In order to explore the different ways that ConceptShare can be integrated with other systems, please take a moment and familiarize yourself with these options.

Before you start designing an integration, you will need to weigh the pros and cons for each type of integration and align these with your business and end-users’ needs. While the core Review & Approval functionality remains the same, there are several, potentially key, capabilities that may not be available depending on the type of integration you choose. It's important to understand the implications of each approach, and while the full spectrum factors is outside the scope of this tutorial, we strongly advise that you discuss your integration needs with the ConceptShare team prior to going down a specific path. Our team will be happy to help you align your requirements and choose the best option for your users.

Terminology

Instance – This is the term used to describe an entire installation of ConceptShare and all of its running components.
Account – This is a particular account in ConceptShare. An account is tied to a domain such as (acme.conceptshare.com). Some 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).
User – This relates to a particular individual within the ConceptShare system.
Project – This is the primary container within a ConceptShare account to store assets and create reviews.
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 term refers to an end-user in an account or a project.
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.

Overview

This tutorial will walk you through the process to add Review & Approval (R&A) capabilities to your host application. We'll facilitates this by providing the functionality and tools you need to create a closed loop user experience where the end-user starts and finishes in your host application.

Consider the workflow diagram below:

We're going to cover a few of the most common R&A use-cases (informal feedback and formal approvals). In order to accomplish this, we'll need to cover some supporting steps including:

• Authentication
  
• Managing Resources (account, project, and review participants)
  
• Managing Projects
  
• Managing Assets
  
• Creating a Review
  
• Getting pre-authenticated Resource URLs for the review so that you can launch users into their reviews through your host application via an i-frame
  
• Download a Feedback Summary of all the activity in a Review
  
• Download one or more Asset

Prerequisites

• An Instance of ConceptShare needs to be provisioned for you.
  
• You will need a Partner Token and Partner Password. If you haven't received a Partner Token/Password, you should request it from ConceptShare.
  
• You will also need to be connected to and setup the API in your environment by connecting to the SOAP service for your instance. You'll find the end-point and WSDL locations will follow the format outlined below.
  

User Interface Considerations

As part of this tutorial, we provide you with a mechanism to generate URLs for use within an iframe. This pre-authenticated URL will open the Proofing Workspace for the user to perform their review. Since this iframe can be placed anywhere, it is part of your host application, and therefore for you to determine its placement (ex. popup, new tab, surrounded by other content). In OEM mode, there are no close buttons visible in the ConceptShare iframe, and thus that part of the experience is controlled by your host application.

Initial ConceptShare Configuration

For managing API interactions, we recommend that you create a specific API user in the ConceptShare system to authenticate with and perform API actions. You can do this by creating a new Instance Administrator user via the AdminPanel and leverage that user's credentials. You'll also want to ensure that the user is an Account Administrator in whatever account you will be working in. You can do this programmatically, but it's recommended that that first account you create, have this user created manually.

Common use-cases for Online Proofing

Some of the most common R&A integrations with ConceptShare require some basic interactions:

• Get authorization so you can work with the API
  
• Create new account/project users
  
• Create new projects to put assets into
  
• Add new assets, find existing assets, or version an existing asset
  
• Create a formal review or informal feedback for one or more assets
  
• Optionally download a summary of the review
  
• Optionally download the final / approved asset for storage in a DAM
  

Use-case #1: Informal / Ad-Hoc Feedback

• The goal is to allow for capture of feedback on one or more assets without demanding a formal response (i.e. Approve or Reject) on the asset(s)
  
• The end user will launch from the host application directly to the ConceptShare annotation tool
  
• The end user will be able to view the asset, navigate to related assets within the same container (if that option is enabled)
  
• The end user will be able to annotate the asset(s)
  
• The end user will complete providing their feedback, shut down the window/tab/integrated-iframe and return the workflow focus back to the host application
  

Use-case #2: Formal / Structured Review

• The goal is to have a one or more people review and provide a response (i.e. Approve or Reject) on one or more assets
  
• The end user will launch from the host application to a review screen within ConceptShare which will provide the review instructions and the assets requested for review
  
• The end user will be able to open each asset within the review in the annotator
  
• The end user will be able to annotate the asset(s)
  
• The end user will be able to provide a formal response for each asset
  
• The end user will complete providing all responses and submit them to the system
  
• The end user will leave the ConceptShare system and return to the host application

Supporting Sections

Authentication

As a user, before you can do anything in ConceptShare, you first need to login. Similarly, in order to perform any action via the API, you must first authenticate your API user into ConceptShare.

Users' API Tokens in ConceptShare are unique per user. Once you know the API token for a given user, you can store it as it is only changed/updated if there is malicious activity on the account or a request was made to reset it. Storing the API token is beneficial because it allows you to skip any subsequent "Authorize" steps via the API.

APIs

Authorize: This call authorizes the user into ConceptShare and returns their User object (includes the user's token) which you'll need to construct a Context which will be used by every subsequent API call.

Callback Events

USER_LOGIN_API: triggered when a user logs in via API (using Authorize)

Here's a C# sample on how to Authorize a regular user, without any elevated permissions.

try

{

   User user = API.Authorize(username, userPassword);

   string apiToken = user.ApiToken;

   context = new APIContext

   {

      UserToken = apiToken,

      PartnerToken = null,

      PartnerPassword = null

   };

}

try

{

   User user = API.Authorize(username, userPassword);

   string apiToken = user.ApiToken;

   APIContext _context = new APIContext

   {

      UserToken = apiToken,

      PartnerToken =  partnerKey,

      PartnerPassword =  partnerPassword 

   };

}

Support: Getting Assets into ConceptShare

In order to annotate, review, and approve assets in ConceptShare, we first need to get the assets into ConceptShare. In order to achieve this we suggest creating a project or possibly re-use an existing project and ingest the asset into ConceptShare either from an external URI accessible to the ConceptShare server or over the SOAP API directly (via byte-array). Assets are processed asynchronously in ConceptShare which means that the API call will return as soon as it has successfully been added to the queuing system for processing. You will need to leverage the callback system (or alternatively poll asset statuses via ConceptShare’s APIs) to await the status of the asset. You will also want to leverage the ASSET_ERROR callback which is triggered when an asset fails processing so that your system can either retry, or perform whatever error handling routines the host application deems necessary.

APIs

• AddProject creates the project
• AddProjectAsset / AddProjectAssetFromExternalUri will allow you to load an asset to a project
• AddVersionedAsset (Optional – For use when versioning an existing asset)

Callback Events

• ASSET_CREATED triggered when an asset is successfully created
• ASSET_VERSIONED (Optional) triggered when an asset is successfully versioned
• ASSET_ERROR (Optional) triggered if there was an error anywhere in the asset ingestion phase.

Support: Getting Users into ConceptShare

In order to send users to the ConceptShare system for a review or to annotate a particular asset, they must first be part of the ConceptShare system. Typically this part of the process is done as needed by the host system to save generating a large volume of users who may never use the system. We recommend that you make a routine that will do the following:

1. Check if the user already exists in the ConceptShare system, and if it doesn’t, create them
2. Check if the user is already part of the ConceptShare account, and if it isn’t, add them.
3. Check if the user is already part of the ConceptShare project, and if it isn’t, add them.

APIs

• GetUserID: You can pass in an email address, and the system will return the user ID of the ConceptShare user if they exist.
• GetAccountRoleList: Returns a list of Account Roles. When adding users to an account you must assign them a role. ConceptShare comes with two default account roles, Account Administrator and General User. We recommend you assign all users utilizing the integration the General User role with the exception of the API user.
• GetProjectRoleList: Returns a list of Project Roles. When adding users to an account or project you must assign them a project role. ConceptShare comes with three default account roles: Project Administrator, Commentator, and View Only. We recommend you assign all users utilizing the integration the Commentator role.
• AddUser: This call creates a user in the ConceptShare system. It does not make them part of any accounts, resources, or content.
• AddAccountUser: This call will add a user to an account as resource.
• AddAccountUserNew This call creates a new user and adds them to the currently logged in account.
• AddUpdateProjectMember: This call will add an existing account user to a project as a project resource.
• AcceptTermsAndConditions This call will accept the ConceptShare Terms & Conditions for a user.

Support: Generating URLs to Access ConceptShare Resources

When you are ready to have a user redirected to the ConceptShare system to either perform a formal review, or to view and annotate an asset, you must utilize an IFRAME and a pre-authenticated URL which will automatically place the user at the appropriate location within the system.

APIs

• GetResourceUrlForUser: This API call allows you to specify a ConceptShare user ID and generate a pre-authenticated URL for that user. You will want to leverage the ResourceUrlOptions in order to specify the type of URL being generated. If you want to generate a URL to a particular asset and have it load in the Annotator you would choose the following ResourceUrlOptions:

Common use-case #1: Informal / Ad-Hoc Feedback

Sometimes it might be desired to get informal or ad-hoc feedback on a particular asset. This use-case allows the host system to give users the ability to access a particular asset within the annotator but no formal approval or rejection response is captured. In order to facilitate this use-case it is assumed that the required asset is already part of the project. Furthermore, once the user being sent to the system and asset is available you can generate URLs to access the annotator window particular users. There is no additional work required outside of the support steps.

Support Steps:

1. See Support: Getting Assets into ConceptShare.
2. See Support: Getting Users into ConceptShare.
3. See Support: Generating Urls to Access ConceptShare Resources

Common use Case #2: Formal / Structured Reviews

Sometimes users want to solicit a formal response (approval) from end-users on a particular set of assets. You can create reviews in ConceptShare to facilitate this. In order to create a review, it is assumed that all the required assets and users are already part of the project. Furthermore, once the review is created you can generate URLs to access the review for particular users (see support Steps).

APIs

• AddUpdateReviewFull: This call allows you to create a formal review within the specified project for the desired assets, and users (reviewers). See the support steps below to get assets and users into the ConceptShare system.
• GetReviewResponses (Optional): You can leverage this API call to retrieve the responses for a given review or asset.
• GetReviewProfileFull (Optional): You can leverage this to pull down a full profile (Review, Members, Assets, and Responses) for a given review.
• GenerateFeedbackSummary (Optional): You can leverage this to download a PDF Feedback Summary of all the activity in the Review.

Callback Events

• REVIEW_COMPLETED is triggered once a review marked as completed (all assets approved, by all reviewers).
• REVIEW_MEMBER_COMPLETED is triggered once a particular reviewer has submitted their responses (approve/reject) for a given review.
• REVIEW_MEMBER_RESET is triggered if an asset is versioned and members had their responses reset, meaning they should go a review the newly updated version and provide their responses.

Support Steps

1. See above Support: Getting Assets into ConceptShare
2. See above Support: Getting Users into ConceptShare
3. See above Support: Generating URLs to Access ConceptShare Resources