Adding Images to a Document via the API

You can upload an image to a document using Advance's API methods. Using this method, you can also associate existing images in Advance with your work item, avoiding the need to upload an image multiple times.

If you are displaying an interview, your end users can use the image upload feature in Advance to upload images directly to the work item.

Terminology

• Image variable - a component in a template that prompts the user to provide an image value as an answer. In the example, the corresponding answer in the Answer Set is "test".

<hd:imageAnswer name="test">
   <hd:value>{guid}</hd:value>
</hd:imageAnswer>

• Image value - refers to the <hd:value>{ImageReference:guid}</hd:value> where the Guid can be either:
  • An image identifier - a reference to an existing image stored in your Advance site.
  • A unique value which acts as a temporary identifier for an image that is not yet in Advance. 
• Image reference - this term refers to the {guid} that is used in the Image value. An image reference may be either an image identifier or a placeholder.

Workflow

Creating a work item with a supplied answer set:

When creating a work item you supply an answer set.

Advance automatically checks the image references supplied in the answer set against the images already uploaded to Advance. If the image exists and the user has access to it, the image reference is automatically resolved, avoiding the need to upload the image again.

If no existing image is found, Advance sends a list of any unresolved images in its response. You then supply each image file against each unresolved image reference. Once an image has been added to Advance, it is given an image identifier and the answer set is mutated to replace the image reference with the image identifier.

Updating or replacing images in an existing work item:

To replace an image, locate the image reference in the existing answer set and replace it with a new image reference.

A new image reference can be either:

• an image identifier, if the image already exists in Advance.
• a unique placeholder, for which you need to upload the image later. 

Prerequisites

• The template used for the work item must ask an Image variable.
• Image variables are only supported in DOCX templates.
• The default maximum file size for images is 10MB. You can edit this setting in the Core Assembly Service.
• JPEG and PNG file formats are supported.

You cannot upload images to a completed version of a work item.

To add an image to a work item

1. (If required) Create a new work item
2. Begin an assembly session to create a new work item version. Pass in answer XML in the body of the request.
3. Advance checks to find if any image values supplied in the answer XML already exist in Advance.
   • If any existing image identifiers are found, to which the user has permissions, Advance automatically associates the image value to the work item version.
   • If Advance cannot match the image references from your answer set to existing image identifiers, it returns a list of the unresolved image references.
4. Advance sends an HTTP 200 response showing which image references are unresolved.
5. Using the list of image references required, upload each image:
   • Either: Pass the image to the active work item version:
     • PUT /WorkItems/{workItemId}/Versions/active/Images/{imageReference}
   • Or: Pass the image to a specific work item version:
     • PUT /WorkItems/{workItemId}/Versions/{versionId}/Images/{imageReference}
6. Advance sends an HTTP 200 response to confirm the image has been uploaded.
7. Repeat steps 5 and 6 for each unresolved image reference.
8. Create a new work item version.

Advance updates the image references on the work item version. When the document is assembled, the image values show as answered.

Sequence diagram

The following diagram demonstrates the series of calls required to create a work item with images.

This diagram demonstrates the series of calls required to update image references in an existing answer set.