Uploading Multiple Images to a Work Item

Overview

You can upload multiple images simultaneously to a specified work item using Advance's APIs. This feature enhances efficiency by allowing batch uploads, reducing the time required for image management. You can add up to 10 images at once to a specified work item.

Prerequisites

  • The template used for the work item must ask an Image variable.
  • Image variables are only supported in DOCX templates.
  • The maximum upload size is 10MB. This applies to each individual image. 
  • You can send up to 10 images per upload.
  • JPEG and PNG file formats are supported.

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

To add a batch of images to a work item

The following procedure outlines how to upload a multiple images. If you have a single image to upload, follow the documentation for adding an image.

  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.
    • 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 an image reference 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 up to 10 image files in the body of the following request, using a multipart form post:
    • PUT /WorkItems/{workItemId}/Images/
  6. Examine the response and identify any images which failed to upload.
  7. If required, you can repeat steps 4 and 5 to upload further batches of images. Ensure each request is completed; concurrent requests will receive a 409 response.
  8. Create a new work item version.

Advance updates the image references. When the document is assembled, the Image variables show as answered.

Responses

  • 200: Success

Successfully uploaded images return the image reference and the image ID. You can then use this image ID in different answer files to reference the same image.

  • 400: Bad request

If you send more than 10 images Advance returns a bad request response.

  • 409: Conflict

Images which fail to upload return one of the following error messages:

  • "Invalid file type"
  • "Image reference was duplicated in request"
  • "Unknown image reference"
  • "Image size exceeded {max size}MB"

Once any issues are resolved, you can retry uploading your images either with the same procedure or that for individual images.

Code Example

// Example code to upload multiple images
var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Put, "https://api.example.com/WorkItems/{workItemId}/Images/");
var content = new MultipartFormDataContent();
// Paths to sample images
List<string> imagePaths = ["{PATH_TO_IMAGE}/image1.jpeg", "{PATH_TO_IMAGE}/image2.png"];
// Add new images to the request
foreach (var imagePath in imagePaths)
{
    byte[] imageBytes = await File.ReadAllBytesAsync(imagePath);
    var imageContent = new ByteArrayContent(imageBytes);
    imageContent.Headers.ContentType = new MediaTypeHeaderValue("image/jpeg"); // Use "image/png" for PNG images
    // Obtain the image reference needed to upload the image to the specified variable.
    // Image references are returned as unresolvedImageReferences when you retrieve the AnswerSet.
    var imageReference = GetImageReference();
    content.Add(imageContent, imageReference);
}
request.Content = content;
var response = await client.SendAsync(request);
if (response.IsSuccessStatusCode)
{
    var responseContent = await response.Content.ReadAsStringAsync();
    var responseObject = JsonSerializer.Deserialize<MultipleUploadResponse>(responseContent, _jsonSerializerOptions); // `MultipleUploadResponse` corresponds to the response JSON.
    
      // Example classes
      // class MultipleUploadResponse
      // {
      //         record UrlsCollection(string AnswerSetUrl);
      //    List<ImageUploadSuccess> SuccessfullyUploadedImages { get; set; }
      //        List<ImageUploadFailure> FailedToUploadImages { get; set; }
      //        UrlsCollection Urls { get; init; }
      // }
      // class ImageUploadSuccess
      // {
      //         string ImageReference { get; init; }
      //        Guid ImageId { get; init; }
      // }
      // class ImageUploadFailure
      // {
      //         string ImageReference { get; init; }
      //        string ErrorMessage { get; init; }
      // }
  
      // Store the image IDs of the successfully uploaded images for reuse in other documents.
    foreach (var successfulImage in responseObject.SuccessfullyUploadedImages)
    {
          StoreImageId(successfulImage.ImageId);
    }
    // Check if any images failed to upload.
    if (responseObject.FailedToUploadImages.Any())
    {
          // Handle failed images.
          // Example: Log error messages for failed uploads.
          foreach (var failedImage in responseObject.FailedToUploadImages)
        {
              LogErrorMessage($"Image reference {failedImage.ImageReference} failed to upload with error : {failedImage.ErrorMessage}");
        }
    }
}
else
{
    // Handle failed upload.
    // Indicates the request itself failed with no successful uploads.
}

Example response objects

1. All images upload successfully

{
    "successfullyUploadedImages": [
        {
            "imageReference": "cf7ebcd5-4c3f-32c5-7ae9-d54c3fe05273",
            "imageId": "cf7ebcd5-4c3f-32c5-7ae9-d54c3fe05273"
        },
        {
            "imageReference": "5cfbc087-7f40-e5ce-3110-063d70b04ec5",
            "imageId": "5cfbc087-7f40-e5ce-3110-063d70b04ec5"
        },
        {
            "imageReference": "4a05b0b0-e435-b804-0af3-ed70a59e2345",
            "imageId": "4a05b0b0-e435-b804-0af3-ed70a59e2345"
        },
        {
            "imageReference": "3f256963-7bcc-8095-f297-b8efa60582ad",
            "imageId": "3f256963-7bcc-8095-f297-b8efa60582ad"
        },
        {
            "imageReference": "a615f258-f448-968e-6ba8-ae568fba75cc",
            "imageId": "a615f258-f448-968e-6ba8-ae568fba75cc"
        },
        {
            "imageReference": "2129895e-06cc-045e-6e6a-504bbdabd600",
            "imageId": "2129895e-06cc-045e-6e6a-504bbdabd600"
        },
        {
            "imageReference": "2ff75621-68ab-fcad-a5d1-a97d8946a1a0",
            "imageId": "2ff75621-68ab-fcad-a5d1-a97d8946a1a0"
        },
        {
            "imageReference": "ae5d55c0-5992-cab3-2d7e-0a2fc10bc21a",
            "imageId": "ae5d55c0-5992-cab3-2d7e-0a2fc10bc21a"
        },
        {
            "imageReference": "22396cc1-5121-e330-e4a7-1b1bb25c8881",
            "imageId": "22396cc1-5121-e330-e4a7-1b1bb25c8881"
        },
        {
            "imageReference": "551ee2e7-11e6-3173-1517-41a43f911951",
            "imageId": "551ee2e7-11e6-3173-1517-41a43f911951"
        }
    ],
    "failedToUploadImages": [],
    "urls": {
        "answerSetUrl": "https://yourtenancy.yourorganization.com/HdaApi/rest/v2.0/WorkItems/213c5991-8d46-4ccd-844f-ec494f032cf1/AnswerSet"
    }
}

2. Some images upload successfully and some fail


{
    "successfullyUploadedImages": [
        {
            "imageReference": "cf7ebcd5-4c3f-32c5-7ae9-d54c3fe05273",
            "imageId": "cf7ebcd5-4c3f-32c5-7ae9-d54c3fe05273"
        },
        {
            "imageReference": "5cfbc087-7f40-e5ce-3110-063d70b04ec5",
            "imageId": "5cfbc087-7f40-e5ce-3110-063d70b04ec5"
        },
        {
            "imageReference": "4a05b0b0-e435-b804-0af3-ed70a59e2345",
            "imageId": "4a05b0b0-e435-b804-0af3-ed70a59e2345"
        },
        {
            "imageReference": "3f256963-7bcc-8095-f297-b8efa60582ad",
            "imageId": "3f256963-7bcc-8095-f297-b8efa60582ad"
        }
    ],
    "failedToUploadImages": [
        {
            "imageReference": "39647852-3c94-7064-7e2d-1c45e0ababd8",
            "errorMessage": "Unknown image reference"
        }
    ],
    "urls": {
        "answerSetUrl": "https://yourtenancy.yourorganization.com/HdaApi/rest/v2.0/WorkItems/213c5991-8d46-4ccd-844f-ec494f032cf1/AnswerSet"
    }
}
}