VNTANA Logo - White
Book a Call
Get Started Free

Resources

VNTANA Resource API – Asset Review States

API – Asset Review States

API Base URL: https://api-platform.vntana.com

For a collection of all Endpoints in our Admin API, view the documentation here. To view the collection of Public Endpoints, view the documentation here. Note: In the following guide and aforementioned documentation, you will see referenced in numerous Endpoints something called a Client. This refers to the workspaces one can create on the Platform within an Organization. The Client nomenclature is a legacy reference being replaced with Workspace.

Asset States

The VNTANA Platform provides numerous states for an Asset which can be utilized both on the platform and via the Admin API to fit your workflow. There are three general categories of Asset states: the non-review states, regular review states, and client review states.

Non-Review States

These simply refer to the regular state an asset can be found in, Draft, Live Internal, or Live Public. They determine access to the asset both internally and when publishing the content elsewhere such as your eComm site. 

Draft

Generally, this status is intended to indicate the asset is not yet finalized. The asset is private and only the original file can be accessed via the platform or an authenticated Admin API call. The asset can be freely edited by users with Workspace Content Manager and higher access, or Restricted User Editors.

Live Internal

This state may refer to an asset that is approved, but not ready or intended for public viewing. The optimized formats are available for download via the Platform and Admin API, and they can be added and displayed within Showroom Share Links. Users with Workspace Admin or higher access can edit these assets.

Live Public

This state allows for public sharing of both the viewer and download links for the Original and/or Optimized models. Only users with Workspace Admin or higher can edit these assets.

Send for Review (Regular Review States)

The first set of review states are the regular group, consisting of Review, Approved, and Rejected. These are generally directed towards internal review, allowing you to invite users from your organization to approve or reject an asset that is still in the pipeline.

Review (Send for Review)

This state allows you to request review from another user before an asset is moved to one of the Live states. When setting an Asset to Review, a user must select at least one user as a Reviewer, though multiple can be assigned. The reviewer(s) will receive an email and Platform notification indicating an asset is ready for review. The email will contain a platform link for the asset.

While the reviewer can set it to Approved or Rejected, it is also possible for them to skip this and directly set it to one of the non-Review states.

Rejected

Indicates the asset has been rejected and changes are needed. The user who originally sent it for review will receive an email and Platform notification indicating it has been rejected. This state is only accessible when the Asset is in the Review state.

Approved

Indicates the asset has been approved and can be published. The user who originally sent it for review will receive an email and Platform notification indicating it has been approved. This state is only accessible when the Asset is in the Review state. This does not automatically set the asset to a non-Review state, this must be handled separately.

Bulk State Changes

When changing the review state in bulk, emails will be condensed to a single email indicating some number of assets have been set to some review state. The link provided will instead be a link to the Asset Library of the Workspace containing the assets and a search parameter for the particular review state.

Client Review

The Client / Customer review states are a bit more targeted in terms of workflow. Generally, these states are expected to be used by users you’ve invited that are Clients or Customers for whom you are providing the 3D models. It provides a couple of additional states compared to the regular review states, and both sets of states can be utilized in your workflow, these are just intended to provide a means by which users can separate review processes if there are different teams that have to approve at different stages of the models life cycle.

Client Review State

Indicates the Client needs to review the Asset. At least one reviewer must be assigned, and the reviewer(s) will receive an email and Platform notification. The reviewer can set the state to any state from Client Review. Only users with Workspace Admin and above or Workspace Client can make changes.

Client Hold

Unique client state intended to label an Asset as on hold and any work is to be paused on it. When an asset is set to Client Hold, the user that sent it to Client Review initially will be notified. Only Workspace Client and Workspace Admin or above can interact with these assets.

Client Dropped

Unique client state intended to label an Asset as dropped by the Client / Customer and no more work is needed on it. When an asset is set to Client Dropped, the user that sent it to Client Review initially will be notified. Only Workspace Client or Workspace Admin’s and above can interact with these assets.

Client Rejected

The Client has rejected the asset and changes are needed. The user that sent it for Client Review will be notified and they can adjust it back to another state such as Draft or even send if for regular review to have their internal team look into the issues.

Client Approved

The Client has approved the asset and it is ready for next steps. The user that sent it for Client Review will be notified, and they can move it into the next state in their workflow, such as Live Internal or Live Public.

Admin API Usage

The Admin API allows you to automate the sending of assets for review as well as updating their review state. Just as on the platform, in order to set the state to one of the review states (i.e. APPROVED or CUSTOMER_DROPPED), the asset would already need to be in the WAITING_REVIEW or CUSTOMER_REVIEW states , respectively.
Required Initial Steps

Before you can send for review or update a state via the API, you will need to Authenticate. Below is a quick summary of the steps involved, see our guide on Authentication to get a more detailed look at the process.

  1. Log in using an Authentication Key or email / password.

    • Returns an x-auth-token in the Response Headers.

  2. Retrieve a list of Organizations and store the needed Organization’s UUID.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      { ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token }

    • This step can be skipped if the Organization UUID is already stored locally.

  3. Generate a Refresh Token for the Organization.

    • Pass the x-auth-token from Step 1 in the Request Headers.

      1
      2
      3
      4
      {
      ‘x-auth-token’ : ‘Bearer ‘ + x_auth_token
      ‘organizationUuid’ : ‘string’
      }

    • Returns the Refresh Token as the Response Header x-auth-token.

  4. Retrieve a list of Workspaces and store the needed UUID.

    • Pass the x-auth-token in the Request Headers.

    • This step can be skipped if the Workspace UUID is already stored locally.

  5. Generate a Refresh Token for the Workspace (Organization Admin / Owner users must skip this step).

    • Pass the Refresh Token from Step 3 in the Request Headers with the Organization and Workspace UUIDs.

      1
      2
      3
      4
      5
      {
      ‘x-auth-token’ : ‘Bearer ‘ + refreshToken,
      ‘organizationUuid’ : ‘string’,
      ‘clientUuid’ : ‘string’
      }

    • Returns the Refresh Token as the Response Header x-auth-token.

The Workspace UUID needs to be retrieved for some endpoints, if it is not stored locally or already retrieved via Authentication, you can search for the Workspace using the API. This endpoint will return a list of Workspaces in the Organization and you can verify the correct one using the name or slug. Below is an example of this endpoint.

The Request structure is as follows:

1
2
3
Method: GET
Endpoint: /v1/clients/client-organizations
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken}

The Response structure is as follows:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
“success”: true,
“errors”: [],
“response”: {
“totalCount”: 1,
“grid”: [
{
“uuid”: “string”,
“slug”: “some-client-slug”,
“name”: “Some Client,
“role”: “ORGANIZATION_ADMIN”,
“imageBlobId”: “string”,
“created”: “2020-01-31T19:17:23.972”
}
]
}
}

Retrieving User IDs

Before setting assets to either regular Review or Client Review, you will need the User UUID of each reviewer you wish to assign. To do this, you can retrieve the list of users and their roles with the following:

1
2
3
Method: GET
Endpoint: /v1/users
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }

A successful request will return:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
‘totalCount’: 1,
‘grid’: [
{
‘uuid’: ”,
‘fullName’: ”,
’email’: ”,
‘imageBlobId’: None,
‘role’: ‘ORGANIZATION_CLIENT_MEMBER’,
‘externalRoleName’: None,
‘externalRoleId’: None,
‘roleAccessLevel’: ‘WORKSPACE’
}
]
}

You can match the email of the user(s) for the desired reviewer(s), and grab the uuid of each match to pass into the Send for Review endpoint.

Send for Review

When Sending for Review, there are two endpoint options, one for a single asset and the other for a bulk operation. In each case, you will pass the productUuid of each asset to send for review, the uuid of the user(s) to review, and set the status to WAITING_REVIEW.

1
2
3
4
5
6
7
8
Method: PUT
Endpoint: /v1/products/status/send-for-review
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“productUuid” : “”,
“reviewers” : [“”],
“status” : “WAITING_REVIEW” or “CUSTOMER_REVIEW”
}

Note key differences in the payload of the bulk operation:

  • Instead of productUuid it is uuids which takes an array of strings.

  • Must also include clientUuid which indicates the Workspace the assets live in. This endpoint only works on a list of assets within the same Workspace.

  • The bulk request is a POST request.
1
2
3
4
5
6
7
8
9
Method: POST
Endpoint: /v1/bulk/products/send-for-review
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“clientUuid” : “”,
“uuids” : [“”],
“reviewers” : [“”],
“status” : “WAITING_REVIEW” or “CUSTOMER_REVIEW”
}

Set Review Status

Similar to the Send for Review, there are two endpoints when updating the review status, one for a single asset and the other for bulk operations.

One important note, the while the endpoints are used for both the standard review states and the client review states, they can’t be mixed together. If the asset was sent for Client Review, it’s status can be updated to client statuses (or non-review status), but not standard Send for Review statuses.

1
2
3
4
5
6
Method: PUT
Endpoint: /v1/products/reviewed-status/{status}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“productUuid”: “”
}

The bulk version:

1
2
3
4
5
6
7
Method: POST
Endpoint: /v1/bulk/products/reviewed-status/{status}
Headers: { ‘x-auth-token’ : ‘Bearer ‘ + refreshToken }
Body: {
“clientUuid”: “”,
“uuids” : []
}

The status is going to correspond to the review states discussed above. They map to the following:

StatusValue
ApprovedAPPROVED
RejectedREJECTED
Client ReviewCUSTOMER_REVIEW
Client HoldCUSTOMER_HOLD
Client DroppedCUSTOMER_DROPPED
Client RejectedCUSTOMER_REJECTED
Client ApprovedCUSTOMER_APPROVED

Postman Scripts

Below is a postman collection to test these endpoints. In the collection, you can set pre-request variables:

  • Credentials (email/pass or auth key)
  • organizationSlug
  • clientSlug
  • productUuid – for the asset to test with
  • status – this will be the regular or client state to update to after it is in WAITING_REVIEW or CUSTOMER_REVIEW
  • reviewerEmail – the email to use to find the correct reviewerUuid

The collection contains a sub-folder for authentication requests, when running not all of them need to be run, just the correct login endpoint based on chosen credentials, and the Client Refresh Token only needs to be done if your access level is a Workspace user.

It also contains the endpoint to retrieve the list of users and both individual and bulk endpoints for the various review state changes.

Download

On This Page

Accelerate Your
Digital Transformation

Learn how our platform can automate your 3D process.
Learn More

Tap the magnifying glass to the left of your screen to search our resources.

OK