Set up a Viewing Session for a CAD Drawing which has XREF Dependencies

PrizmDoc v12.4 - Updated

Collapse All

Developer Guide > PrizmDoc Server > How To > Set up a Viewing Session for a CAD Drawing which has XREF Dependencies

How to Setup a Viewing Session for a CAD Drawing Which Has XREF Dependencies

This guide explains how to setup a viewing session for a CAD drawing which depends upon external files via XREF.

Many documents, such as a PDF, are self-contained in a single file. Setting up a viewing session for these sorts of documents is relatively simple: after creating a viewing session, you make one HTTP call to upload the source document's file bytes.

Setting up a viewing session for a CAD drawing which is made up of multiple files is slightly more complicated. You will need to:

POST to create a new viewing session.
POST to upload each file to the work file API, both the primary CAD drawing and all its dependencies, creating distinct fileId values for each one.
POST a JSON object to the work file API to create a special "package" work file for the entire set. This "package" work file defines which of the files is the primary file for viewing, specifies path information for each of the files (typically relative to the primary file), and has its own distinct fileId.
Assign the "package" fileId to the viewing session so that the entire CAD drawing may be viewed.

This guide walks through examples of this in detail. It has two parts:

Preparing to view a CAD XREF document for the first time
Preparing to view a CAD XREF document which has already been uploaded

Preparing to view a CAD XREF document for the first time

Step 1: Identify the Necessary Files and their Local Paths

Imagine a CAD engineer has prepared a master.dwg file which depends on several other files, and he has stored all of the files on the disk in the following way:

./master.dwg
./parts/desk.dwg
./parts/desk-extension.dwg
./other/chair.dwg
./common/logo.png

In order for other CAD engineers to be able to open master.dwg and view the entire contents, they will need all of these files, stored in the same way as they are here.

In the same way, in order for PCC to prepare master.dwg for viewing by an end user in the browser, it too will need all of these files and information about how they were stored by the CAD engineer on the local disk.

Step 2: Create a New Viewing Session

Submit a POST to creating a new viewing session:

POST /PCCIS/V1/ViewingSession
Content-Type: application/json

{
    "render": {
        "html5": {
            "alwaysUseRaster": false
        }
    }
}

HTTP/1.1 200
Content-Type: application/json

{
    "viewingSessionId": "AqQp3wrrSZ5YhJoFdj44Z_rT4629XnO6j7bEjjSRA5fiQUljuiYgi-ng9sP4v95VTVqilte6bsaC6eGpUulMUWid1VN9qwH6rN5wp82eSfM",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Hold on to the viewingSessionId (and affinityToken, if provided). You will need it again later.

Step 3: Deliver the Configured HTML5 Viewer Resources to the End User

Now that you have a viewingSessionId, you can go ahead and deliver the HTML5 viewer, configured with the given viewingSessionId, to your end user's browser. This allows their browser to start parsing the viewer's JavaScript resources as early as possible.

NOTE: We currently do not support the viewer's download option when viewing CAD with XREF. When configuring the viewer, make sure you set uiElements.download to false.

Step 4: Upload the Files to the Back End

POST each of the necessary files to the work file API, creating a unique fileId for each one. If you are using PrizmDoc Server Self-Hosted in multi-server mode or PrizmDoc Server Accusoft Cloud-Hosted, be sure to include the affinityToken value returned after creating the viewing session in an Accusoft-Affinity-Token header of each request.

master.dwg:

POST /PCCIS/V1/WorkFile
Content-Type: application/octet-stream
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

<<master.dwg bytes>>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "CVBuD7DbQYNoJDqByGierQ",
    "fileExtension": "dwg",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

parts/desk.dwg:

POST /PCCIS/V1/WorkFile
Content-Type: application/octet-stream
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

<<parts/desk.dwg bytes>>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "5qTYa3gzN9gYUb5SzqUhqg",
    "fileExtension": "dwg",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

parts/desk-extension.dwg:

POST /PCCIS/V1/WorkFile
Content-Type: application/octet-stream
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

<<parts/desk-extension.dwg bytes>>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "o1bLJwFGxf9QGuTkyrOqig",
    "fileExtension": "dwg",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

other/chair.dwg:

POST /PCCIS/V1/WorkFile
Content-Type: application/octet-stream
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

<<other/chair.dwg bytes>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "KxonBTYJyRpCswOLn_paiw",
    "fileExtension": "dwg",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

common/logo.png:

POST /PCCIS/V1/WorkFile
Content-Type: application/octet-stream
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

<<common/logo.png bytes>>

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "JcskB6w8D5_qlf4OA3xspQ",
    "fileExtension": "png",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

At this point, you have a unique fileId for each of the uploaded files.

Step 5: Create a Final 'Package' Work File

This is the step where you tie all of the files together under a single new fileId and provide some crucial information which is necessary for the back end to actually prepare the content for viewing.

When uploading simple work files, the POST body is simply the bytes of the file. However, by submitting a POST with a Content-Type of application/json, you can instead instruct the back end to create a new "package" work file from a set of existing work files.

A "package" file defines the following:

A list of files in the package, specified by fileId.
A unique path for each file in the package.
The primary file in the package, identified by its path.

To create a new "package" for the files already uploaded in Step 4 above, we would submit a POST like this:

POST /PCCIS/V1/WorkFile
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

{
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/desk.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/desk-extension.dwg" },
        { "fileId": "KxonBTYJyRpCswOLn_paiw", "path": "other/chair.dwg" },
        { "fileId": "JcskB6w8D5_qlf4OA3xspQ", "path": "common/logo.png" }
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "fileId": "nkG9fiAmj27X3MhqGdbsXA",
    "fileExtension": "dwg",
    "primaryPath": "master.dwg",
    "items": [
        { "fileId": "CVBuD7DbQYNoJDqByGierQ", "path": "master.dwg" },
        { "fileId": "5qTYa3gzN9gYUb5SzqUhqg", "path": "parts/desk.dwg" },
        { "fileId": "o1bLJwFGxf9QGuTkyrOqig", "path": "parts/desk-extension.dwg" },
        { "fileId": "KxonBTYJyRpCswOLn_paiw", "path": "other/chair.dwg" },
        { "fileId": "JcskB6w8D5_qlf4OA3xspQ", "path": "common/logo.png" }
    ],
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

The new fileId which is returned ("nkG9fiAmj27X3MhqGdbsXA") is a single id we can use to refer to this entire set of files, with master.dwg being the primary file for viewing.

Step 6: Attach the 'Package' Work File to the Viewing Session

Now that your "package" work file exists, you can attach it as the source document for the viewing session with this PUT request. Note carefully that the viewingSessionId used in the URL is prefixed with the letter u:

PUT /PCCIS/V1/ViewingSession/uAqQp3wrrSZ5YhJoFdj44Z_rT4629XnO6j7bEjjSRA5fiQUljuiYgi-ng9sP4v95VTVqilte6bsaC6eGpUulMUWid1VN9qwH6rN5wp82eSfM/SourceRef
Content-Type: application/json

{
    "refType": "workFile",
    "fileId": "nkG9fiAmj27X3MhqGdbsXA"
}

HTTP/1.1 200 OK

(If you are wondering, an Accusoft-Affinity-Token is not required in this particular request; the viewing session id itself serves the role of the affinity token.)

At this point, the back end will begin converting the CAD content for viewing in the browser and delivering content to the end user as it becomes ready.

Preparing to view a CAD XREF document which has already been uploaded

All work files do eventually expire, and there is never a guarantee that a particular fileId will be available. However, each time you use a fileId as the source document of a viewing session, we will extend the amount of time that fileId will remain available. In many cases, you can simply continue reusing the existing fileId when creating a new viewing session for the same CAD drawing.

Step 1: Create a New Viewing Session

Submit a POST to creating a new viewing session. If you are using PrizmDoc Server Self-Hosted in multi-server mode or PrizmDoc Server Accusoft Cloud-Hosted, make sure that you add an Accusoft-Affinity-Token header which matches the affinityToken of the work file. This is crucial to ensure that the viewing session will be created on a machine in the cluster that will actually have access to the existing fileId in the next step.

POST /PCCIS/V1/ViewingSession
Content-Type: application/json
Accusoft-Affinity-Token: ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM=

{
    "render": {
        "html5": {
            "alwaysUseRaster": false
        }
    }
}

HTTP/1.1 200
Content-Type: application/json

{
    "viewingSessionId": "HO9MagQSyIizShhzLpjp-H73-IRtoqcPlJZmLP0PPwI3HxJ36Ds_HunbqMmtKfT1gt4h4-96X67t7onW2P9XfV5Rw4pSddBrNoFp4A8bdFw",
    "affinityToken": "ejN9/kXEYOuken4Pb9ic9hqJK45XIad9LQNgCgQ+BkM="
}

Step 2: Attach the Existing 'Package' Work File to the Viewing Session

Simply attach the existing fileId to the new viewing session as you did before. Remember that the viewingSessionId used in this URL must be prefixed with the letter u:

PUT /PCCIS/V1/ViewingSession/uHO9MagQSyIizShhzLpjp-H73-IRtoqcPlJZmLP0PPwI3HxJ36Ds_HunbqMmtKfT1gt4h4-96X67t7onW2P9XfV5Rw4pSddBrNoFp4A8bdFw/SourceRef
Content-Type: application/json

{
    "refType": "workFile",
    "fileId": "nkG9fiAmj27X3MhqGdbsXA"
}

HTTP/1.1 200 OK

(Although it was crucial you provided an Accusoft-Affinity-Token in the previous POST request, it is not required in this PUT request; the viewing session id itself serves the role of the affinity token.)

That's it. The new viewing session ready to provide viewing content for the previously-uploaded CAD drawing files.

What if the Existing 'Package' Work File has Expired?

When you make the PUT request to associate the existing fileId to the new viewing session, the PUT request will fail if no such fileId can be found:

HTTP/1.1 480 NotFound
Content-Type: application/json

{
    "errorCode": "NotFound",
    "errorDetails": {
        "in": "body",
        "at": "fileId"
    }
}

If the fileId has indeed expired, this is the response you will receive. At this point, you will need to re-upload all of the CAD files again and create a new "package" fileId which you can then attach to the viewing session.

Note that this error technically only means that the specified fileId could not be found, and it may occur for several reasons:

The fileId has expired.
The fileId value itself was incorrect.
You forgot to provide the correct Accusoft-Affinity-Token header value when creating the viewing session, and as a result the viewing session has been assigned to a machine in the cluster that does not have access to the work file (even though the work file itself may still exist). To prevent this, make sure you are providing the work file's affinityToken value in an Accusoft-Affinity-Token header when making the POST request to create the new viewing session (cf. Step 1).

Send Feedback