CloudStreams 10.5 | webMethods CloudStreams | Administering webMethods CloudStreams | Cloud Connections, Services, and Connector Listeners | Multipart/form-data content type
 
Multipart/form-data content type
Though application/x-www-form-urlencoded is a more natural way of encoding, it becomes inefficient for encoding binary data or text containing non-ASCII characters. The media type multipart/form-data is the preferred media type for request payloads that contain files, non-ASCII, and binary data. CloudStreams supports this media type using which you can embed binary data such as files into the request body in a transparent way.
A multipart/form-data request body contains a series of parts separated by a boundary delimiter, constructed using Carriage Return Line Feed (CRLF), "--", and also the value of the boundary parameters. The boundary delimiter must not appear inside any of the encapsulated parts.
Each part must contain a Content-Disposition header field where the disposition is form-data. The Content-Disposition header field must also contain an additional parameter of name. For form data that represents the content of a file, a name for the file should be supplied as well, by using a filename parameter of the Content-Disposition header field.
Each part may have an optional Content-Type header field which defaults to text/plain. If the contents of a file are to be sent, the file data should be labeled with an appropriate media type, if known, or application/octet-stream.
Example of a multipart request
--BOUNDARY
Content-Type: application/json
Content-Disposition: form-data; name="job"

{
"object":"Contact",
"contentType":"CSV",
"operation":"insert"
}

--BOUNDARY
Content-Type: text/csv
Content-Disposition: form-data; name="content"; filename="content"

(Content of your CSV file)
--BOUNDARY—
Parts for a REST resource
CloudStreams defines the following three part types:
Part Type
Description
TEXT
Represents a simple text part of a multipart/form-data payload where the content of the part is of type text/plain. You can use this part to send raw text data as the content of a part, in a multipart request. From a file upload perspective, this part is generally used to convey extra information about the upload behavior, like target folder paths/folder names where the file has to be uploaded.
FILE
Represents a binary part of a multipart/form-data payload where the content of the part is binary or the content of the file itself. To upload a file, you will normally use this part. For file upload kind of use cases, this part is the main or mandatory part required by the service provider.
Note:
There is no limit in terms of the size of the file part that you can send as part of multipart. It depends on the available heap space.
DOCUMENT
Represents a part where the content of the part is of type application/json or application/xml.
Defining the parts for a REST resource
You can define the parts for a REST resource in the following ways:
*Connector XML
*Service Development perspective in Software AG Designer
Using the Connector XML to define the parts for a REST resource
If you are a connector developer and are sure about all combinations of all the parts for a REST resource, add the part definitions under Resource Definitions in the Connector XML file. This reduces your effort while developing cloud connector services as you can just create and run the cloud connector services and there is no need to add any parts by using the Service Development perspective in Software AG Designer. In the Connector XML file, if the isRequired attribute of the part element is set to true, the part will be available in the service signature. If isRequired is marked as false, the part appears in the Attachment table but does not appear in the signature. You can still add a new part by using the Service Development perspective in Software AG Designer.
*TEXT - In this definition, the following table describes the various attributes of the part element:
Attribute Name
Description
name
Name of the part.
contentType
Content type of the part's content.
Type
Part type, for example, here it is TEXT.
defaultValue
If provided, sets as the value of this text part.
isRequired
Represents whether this part will be included in the signature.
The following example shows how the file uploading path, sampleFolder, is sent using a text part.
Note:
Set the messageFormatterType attribute of the request element as multipart/form-data. This will denote this resource as a multipart form-data resource.
<request name="UploadFileRequest" messageFormatterType="multipart/form-data"
builderType="application/octet+idataoref">
<parts>
<part name ="folder_paths" contentType ="text/plain" type="TEXT"
defaultValue="sampleFolder" isRequired="true"/>
</parts>
</request>
*FILE - In this definition, the following table describes the various attributes of the part element:
Attribute Name
Description
name
Name of the file part.
contentType
Content type of the file that is being uploaded.
Type
Part type, for example, here it is FILE.
defaultValue
If provided, sets as the filename by which it will be uploaded.
isRequired
Represents whether this part will be included in the signature.
The following example shows how a raw file takeit.txt having content type text/plain is sent using a file part.
<request name="UploadFileRequest" messageFormatterType="multipart/form-data"
builderType="application/octet+idataoref">
<parts>
<part name ="files" contentType ="text/plain" type="FILE"
defaultValue="takeit.txt" isRequired="true"/>
</parts>
</request>
*DOCUMENT - In this definition, the following table describes the various attributes of the part element:
Attribute Name
Description
name
Name of the file part.
contentType
The serialization type to which the document will be serialized and become the part content. CloudStreams supports only application/json and application/xml as the content type for this part.
Type
Part type, for example, here it is DOCUMENT.
defaultValue
If provided, sets as the document reference.
isRequired
Represents whether this part will be included in the signature.
Example: You want to send the following JSON payload, which is of type application/json as the part's content.
{
"object":"Contact",
"contentType":"CSV",
"operation":"insert"
}
To transmit this payload in a part, you have to create an Integration Server document, for example, metadata, which will contain three string fields.
In this example, the fields are object, contentType, and operation. You have to point the document namespace as the default value, in this example, multipart.sample:metadata, and the content type as application/json. CloudStreams can now serialize the Document and make it available as the content of the document part.
The following is a sample part definition for the Document part:
<request name="UploadFileRequest" messageFormatterType="multipart/form-data"
builderType="application/octet+idataoref">
<parts>
<part name ="job" contentType ="application/json" type="DOCUMENT"
defaultValue="multipart.sample:metadata" isRequired="true"/>
</parts>
</request>
Using the Software AG Designer to define the parts for a REST resource
This approach allows the service developer to add parts, after creating the cloud connector service. The Attachment panel in the Service Development perspective in Software AG Designer lists all the parts that have been added.
*TEXT - In the Name field, type the name of the file part as documented in the SaaS provider API documentation. The Name field is mandatory. In the Value field, type the value of the part. If you do not give any value, an empty string will be set as the default value.
*FILE - In the Name field, type the name of the file part as documented in the SaaS provider API documentation. The Name field is mandatory. In the Content Type field, type the content type of the file you are uploading. If you do not give any value, the default value will be set as application/octet-stream. In the File Name field, type the file name by which you want the file to be uploaded. If you do not give any value, the default value will be set as attachment.
*DOCUMENT - In the Name field, type the name of the file part as documented in the SaaS provider API documentation. In the Content Type field, type the content type of the body part that you want your document to be serialized and sent to the back end. CloudStreams supports only application/json and application/xml as the content type for this part. For the Document field, first create a document that matches the payload and then select that document. The Name, Content Type, and Document fields are mandatory.
Note:
All options including the Add Part option are disabled if the resource is not of type multipart/form-data. Currently, multipart/form-data payload is supported only at the request level, that is, only in the input signature.
If you do not provide the optional values, CloudStreams sends the default values as mentioned in the following table to the back end.
Part Type
Field Name
Default Value
TEXT
Value
Empty string
FILE
Content Type
application/octet-stream
FILE
File Name
attachment
See the Building Cloud Connector Services section in the webMethods Service Development Help for more information on how to add parts using Software AG Designer.