You can configure REST and SOAP integrations in Pega Platform to upload or download file attachments directly in your application. REST and SOAP connectors in Pega Platform allow you to use REST or SOAP APIs that receive or return attachments.
You can take advantage of SOAP and REST connectors and services in the following use cases:
- Uploading file attachments from a Pega Platform application to a remote REST or SOAP endpoint
- Uploading file attachments to a Pega Platform application from a remote REST or SOAP client
- Downloading file attachments from a Pega Platform application to a remote REST or SOAP client
- Downloading file attachments to a Pega Platform application from a remote REST or SOAP endpoint
Review the following information to learn about how your application uses REST and SOAP connectors or services to send or receive file attachments.
- How multipart messages are formatted
- Connector rule execution for multipart messages
- Service rule execution for multipart messages
- Named attachment mapping pages
- Handling Base64-encoded file content
- Performance considerations
- Considerations for REST file attachments
- Considerations for SOAP file attachments
How multipart messages are formatted
File attachments pass between the REST or SOAP client and the service endpoint by using the MIME Multipart messaging standard. The MIME standard defines a format for the message payload that is specific to the protocol you are using:
- REST connectors and services use the multipart/form-data [RFC1867] content type
- SOAP connectors and services use the multipart/related [RFC2112] content type
The value of the Content-Type HTTP header that accompanies the message payload indicates the specific formatting of the multipart message. The message payload uses partitions to separate each file attachment, and each partition declares its own Content-Type header value based on the file type of the attachment. In addition, each message part has a Content-Disposition header that specifies the name of the file attachment. Pega Platform REST and SOAP connectors and services handle the multipart file automatically, based on a few additional configuration steps in the Pega Platform application. The following is an example of a multipart message for a REST call in Pega Platform:
Content-Type: multipart/form-data; boundary=messageboundarytext Your application has been approved. Please review the attached information. boundary=messageboundarytext Content-Type: text/plain; Content-Disposition: attachment; filename="loanapplication.pdf" --messageboundarytext--
Connector rule execution for multipart messages
When the Pega Platform application invokes a REST or SOAP connector, the connector execution run time looks for a clipboard page named pyRequestAttachmentPage. If the connector finds the clipboard page, it formats the outgoing message payload as a multipart message.
When the connector execution run time receives a response message payload formatted as a multipart message, it creates a clipboard page named pyResponseAttachmentPage and writes the message parts to that page.
Service rule execution for multipart messages
When the REST or SOAP service execution run time receives a request message payload formatted as a multipart message, it creates a clipboard page named pyRequestAttachmentPage and writes the message parts to that page prior to running the service activity.
When the service activity finishes running, the service execution run time looks for a clipboard page named pyResponseAttachmentPage and if it finds the page, formats the outgoing message payload as a multipart message.
Named attachment mapping pages
To configure your application to upload or download attachments, you must use activity rules that reference the following clipboard pages:
- Use the pyRequestAttachment page to upload multipart attachment content sent over REST or SOAP protocols
- This page applies to both connector and service configurations.
- The Pega Platform application must create and populate this page before using a REST or SOAP connector to send files to a remote endpoint.
- The Pega Platform application must copy data from this page when processing files that were sent by the remote client in the request message of REST or SOAP service interaction.
- Use the pyResponseAttachmentPage to download multipart attachment content sent over REST or SOAP protocols.
- This page applies to both connector and service configurations.
- The Pega Platform application must copy data from this page after using a REST or SOAP connector to retrieve files from a remote endpoint.
- The Pega Platform application must create and populate this page when returning files to the remote client in the response message of a REST or SOAP service interaction.
- Data-ServiceMessage is the data class for both
The application uses the following Value List properties to manage multipart file content and metadata:
- pyAttachKeys– Holds the names of the files that the application is sending or receiving.
- pyAttachTypes – Holds the content-type MIME header values of the files that the application is sending or receiving.
- pyAttachValues – Holds the Base64-encoded content of the files that the application is sending or receiving (each value in the list represents a different file).
All three value lists are expected to contain an identical number of elements.
Note: When executing connectors that send or receive multipart file attachments, always remove the attachment pages from the clipboard after each connector invocation. This reduces the memory footprint of the application and prevents any errors related to the presence of stale data.
Handling Base64-encoded file content
The multipart mapping configuration behaves the same way,irrespective of the native file format. Pega Platform handles file content for binary formats (for example, JPEG or PDF) in the same way as file content for text formats (such as XML or JSON). All multipart file content is treated as binary file content, and all multipart file content is assumed to be Base64-encoded text when it is read from or written to the pyAttachValues value list property. This means that the Pega Platform application is responsible for Base64-encoding all content being written to the attachment page, and potentially Base64-decoding all content being read from the page. The need for decoding the content depends on how the application is using the data.
Sending or receiving very large file attachments over REST or SOAP integrations can cause memory-related performance problems for Pega Platform applications. This is because all multipart file data is present in clipboard memory before the application sends it or after the application receives it. To avoid degraded performance, consider using other file-based platform integration capabilities that are better suited to very large files.
For more information, see the following documentation:
Considerations for REST file attachments
REST message payloads might contain binary file content that is not formatted using the MIME Multipart message standard. An example of this use case is described in Configuring a REST connector to receive binary attachments.
If the REST service endpoint deals exclusively with multipart messages for file uploads or downloads, omit any configuration of the message body on the REST rule forms and map all message parts by using the named attachment pages. When the REST rule form is configured to map a message body, this mapping configuration is applied to the first part of a multipart message. This configuration can lead to confusing results, and therefore should be avoided in most use cases.
For more information, see Service REST rules.
Considerations for SOAP file attachments
SOAP message payloads always include the SOAP Envelope, which uses XML-formatted text defined by the connector or service rule configuration. SOAP Messages with Attachments is an internet standard that defines a MIME Multipart message with the SOAP Envelope as the first message part, and one or more binary attachments as the remaining message parts. The SOAP Envelope message part is mapped according to the connector or service rule configuration, and the remaining message parts are mapped using the named attachment pages.
MTOM is another internet standard that is built on top of the earlier SOAP standards. If MTOM is enabled on the SOAP connector or service rule form, any attached file content is mapped as part of the SOAP Envelope payload and not mapped using the named attachment pages.
- Configuring a REST connector to receive binary attachments
Pega Platform can receive attachments regardless of the content type or response type. Configure a REST connector to receive attachments when your application connects to a service that responds with a binary stream, for example, a PDF file or XLS file.
- Use case: Send file attachments from a repository
You are running an insurance claim case for a car insurance company. You must send a payment request to the insurance carrier of the driver who hit the car that belongs to your client.
- Use case: Process inbound file attachments for storage in a repository
You are running an insurance claim case for a car insurance company. You send a payment request of $1,500 in a PDF file to the insurance carrier of the driver who hit the car that belongs to your client. The insurance carrier adds a revised payment amount and returns the PDF file renamed: InsurancePaymentRequest-Disputed.pdf.