Stream Assembly changes live

GET {UPDATE_STREAM_URL}

In the response after creating an Assembly you will find two fields for retrieving the Assembly Status: assembly_ssl_url and update_stream_url. You can fetch the current Assembly Status from the URL provided in assembly_ssl_url. To obtain information about how the Assembly is progressing, you can either poll that regularly, or subscribe to the update stream, which is described in this document.

Server-Sent Events

The update_stream_url property in the Assembly Status defines a URL, where the update stream for the corresponding Assembly is available using server-sent events.

Server-sent events are a web technology for sending live notifications from the server to a client over HTTP. It is similar to Web Sockets, but only allows unidirectional messages from the server to the client and consists of a simple, text-based format.

While the Assembly is either in the uploading or executing state, a client can connect to this endpoint by sending a GET request with the Accept: text/event-stream header field to the URL specified in update_stream_url and parse the response stream. The server can send a mixture of messages and events to the client. The difference between them is that events include an additional payload with information, while messages don't.

Messages

A message consists of the message name and no additional payload. On the wire, a message with the name assembly_finished looks like this ([NL] indicates a new line):

data: assembly_finished[NL]
[NL]

Transloadit sends the following messages:

  • assembly_upload_meta_data_extracted is emitted when all uploads are finished and the meta data has been extracted for all of them.
  • assembly_uploading_finished is emitted when all uploads for this Assembly have been finished and the Assembly transitions from the uploading into the executing state.
  • assembly_finished is emitted when the Assembly is complete and all files have been processed. The server will end the stream after this message.
  • ping is emitted periodically to keep the connection alive while the Assembly is being processed. It is currently sent every minute, although this interval might change in the future.

Events

An event consists of the event name and an additional payload. On the wire, an event with the name assembly_result_finished looks like this ([NL] indicates a new line):

event: assembly_result_finished[NL]
data: {"id":"6bb16f6cd49a44b4ae431f576e016c6d","name":"lesereihe.doc",...}[NL]
[NL]

Transloadit sends the following events:

  • assembly_error is emitted when an error occurs while the Assembly is executing. The server will end the stream after this event. Additional information about the error is included, for example:

    {
  "error": "DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION",
  "http_code": 400,
  "step": "avatar",
  "previousStep": ":original",
  "worker": "dhor.transloadit.com",
  "msg": "The output format pdf is not supported for the input format pdf. The input format pdf is currently not allowed."
}

  • assembly_upload_finished is emitted for each upload that is finished. Additional information about the uploaded file is included. The structure is the same as an object in the uploads array from the Assembly Status, for example:

    {
  "id": "6bb16f6cd49a44b4ae431f576e016c6d",
  "name": "lesereihe.doc",
  "basename": "lesereihe",
  "ext": "doc",
  "size": 61440,
  "mime": "application/msword",
  "type": null,
  "field": "file",
  "md5hash": "154a9349b8f9111865a07ed0a7050f55",
  ...
}

  • assembly_result_finished is emitted whenever a new result from a Step is available. The step name and additional information about the result are included. The structure is the same as an object in the results array from the Assembly Status, for example:

    [
  "avatar",
  {
    "id": "5789e06b48ad450aa55f9b3721376581",
    "name": "lesereihe.pdf",
    "basename": "lesereihe",
    "ext": "pdf",
    "size": 120456,
    "mime": "application/pdf",
    "type": "pdf",
    "field": "file",
    "md5hash": "e9df77e5ee87e8ec3b4453bcddf191bc",
    "meta": {
      "page_count": 1,
      "width": 1238,
      "height": 1750,
      ...
    },
    ...
  }
]

  • assembly_execution_progress is emitted at regular intervals with information about the overall Execution Progress of the Assembly and its files. The structure and mechanisms are detailed in Assembly Execution Progress, for example:

    {
  "progress_combined": 50,
  "progress_per_original_file": [
    {
      "original_id": "6bb16f6cd49a44b4ae431f576e016c6d",
      "progress": 50
    }
  ]
}

Note: Additional messages and events might be added in the future. A client should therefore ignore unexpected messages/events and not error out.

Example in JavaScript

Modern browsers provide native support for server-sent events via the EventSource constructor. Assuming that the Assembly Status is stored in the assembly_status variable, the client can listen for the assembly_finished message, the assembly_uploading_finished message, and the assembly_result_finished event as follows:

const stream = new EventSource(assembly_status.update_stream_url)

// Listen for the assembly_finished and assembly_uploading_finished messages
stream.addEventListener('message', (event) => {
  switch (event.data) {
    case 'assembly_finished':
      console.log('Assembly is finished')
      break
    case 'assembly_uploading_finished':
      console.log('All uploads are finished')
      break
  }
})

// Listen for the assembly_result_finished event
stream.addEventListener('assembly_result_finished', (event) => {
  const result = JSON.parse(event.data)
  console.log('Assembly result is available', result)
})

GET query components

No request query components needed.

Response

Here’s an example response body:

For more information about the response format, please refer to Mozilla's documentation about server-sent events.