Multipart form-data

Last modified by Carlijn Kokkeler on 2024/09/03 12:30

This microlearning is only applicable once running on the current generation architecture.

In this microlearning, we’ll dive into configuring multipart/form-data messages in eMagiz to ensure accurate delivery to an endpoint. You’ll learn the essentials of defining boundaries, setting content types, and constructing messages that comply with the HTTP standard. By understanding these key aspects, you’ll be able to efficiently handle complex data exchanges involving multiple parts and ensure seamless integration with external systems.

If you have any questions, please contact academy@emagiz.com.

1. Prerequisites

  • Expert knowledge of the eMagiz platform

2. Key concepts

This microlearning focuses on configuring a multipart/form-data message within eMagiz to ensure it is sent correctly to an endpoint.

Key aspects are:

  • Understanding the boundary that separates the parts of the message
  • Defining the content types of each part of the message
  • Construction of the complete message according to the specification

3. Multipart form-data

In this microlearning, we will focus on understanding how the multipart/form-data contentType works within the HTTP standard and which steps a user needs to take to construct such a message. Armed with this knowledge, you can implement these complex connections within a limited time frame.
  

3.1 Understanding the boundary

eMagiz will automatically generate a random boundary string that will change with each call. This way, you don't have to worry about this.
The following criteria apply when utilizing the boundary functionality within the multipart/form-data construction:

  • The value of the boundary must begin with a double horizontal bar –this is called a leading hyphen
  • The boundary value must not contain more than 70 characters in addition to the leading hyphen.
  • The boundary value must not contain characters disabled by the HTTP protocol or URL, such as the colon.
  • A CRLF line must always precede a boundary within the request body. This means that when the request body ends with a CRLF line, an additional CRLF line is needed before the boundary doubling the CRLF lines in that part of the request body.

3.3 Preparing the message

Several steps are needed to construct the message. Luckily, most of the steps necessary have to do with concepts we have already discussed in previous microlearnings. Based on what multipart/form-data entails, we need a way to store both the meta information and the file(s) we want to send to the external party. For example, put the metadata in one (or multiple) header(s) and use the file content as a payload. You can achieve this with a header enricher and standard transformer.

Once the file content is your payload, you must ensure the data is "raw." So, when you have a base64-encoded string, you should decode it before sending it to the endpoint.

In addition, we need to define the contentType header. Here, we need to define the value "multipart/form-data" to avoid potentially sending the incorrect contentType when calling the REST endpoint.

expert-data-handling-multipart-form-data--content-type-header-config-new.png

3.2 Construct the message

After you have set the stage, you can use a standard transformer component to build your message correctly. To create it correctly, you need to take the following into account:

  • Each part of the message needs to be a separate map entry. A comma separates these entries. The example below is the comma just before "'configuration'".
  • Each value part (in the example below, the part after file and after configuration needs to be an HTTP entity object)
  • Pay attention to the correct use of single quotes when constructing a message as part of this standard transformer.
  • eMagiz will handle the boundary logic necessary to construct the message.

Given all this, you can write the following SpEL expression that will yield a desirable output:

{'file': new org.springframework.http.HttpEntity(payload, T(org.springframework.util.CollectionUtils).toMultiValueMap({'Content-Disposition': {'form-data; name="file"; filename="'+ headers.file_name + '"'}, 'Content-Type': 'text/csv'})),
'configuration': new org.springframework.http.HttpEntity('{"timestampFormat":"' + headers.timestampFormat + '",'name":"' + headers.customerId + '","workspace":{"id":"' + headers.workspaceId + '"}}'
, T(org.springframework.util.CollectionUtils).toMultiValueMap({'Content-Disposition': {'form-data; name="configuration"'}, 'Content-Type': 'application/json'}))} 

Putting this in a standard transformation gives you the following solution in the flow.

expert-data-handling-multipart-form-data--standard-transformer-config-new.png

3.3 Calling the endpoint

Now that we have constructed our message correctly, the last thing to do is call the endpoint. Since we have prepared our message and accurately defined our contentType, calling the endpoint does not require additional configurations compared to what you are already used to when dealing with REST endpoints.

4. Key takeaways

  • eMagiz will automatically generate a random boundary string that will change with each call.
  • Each part of the message needs to be a separate map entry. A comma separates these entries. The example below is the comma just before "'configuration'".
  • Each value part (in the example below, the part after file and after configuration needs to be an HTTP entity object)
  • Pay attention to the correct use of single quotes when constructing a message as part of this standard transformer.
  • eMagiz will handle the boundary logic necessary to construct the message.

5. Suggested Additional Readings