How to Set Up a Viewing Session for a CAD Drawing Which Has XREF Dependencies
This topic explains how to set up 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 topic 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 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 PrizmDoc 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 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
tofalse
.
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 Self-Hosted (in cluster-mode) or PrizmDoc Cloud, 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: 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 create a new viewing session. If you are using PrizmDoc Self-Hosted (in cluster-mode) or PrizmDoc Cloud, 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 is 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'saffinityToken
value in anAccusoft-Affinity-Token
header when making the POST request to create the new viewing session.