Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

File attachment configuration in REST and SOAP integrations

Updated on April 6, 2022

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.

REST and SOAP services also provide a simple way to send files over a REST or SOAP call.

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

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.

Diagram of connector rule execution for multipart messages request

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.

Diagram of connector rule execution for multipart messages response

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.

Diagram of service rule execution for multipart messages request

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.

Diagram of service rule execution for multipart messages response

Named attachment mapping pages

To configure your application to upload or download attachments, you must use activity rules that reference the following clipboard pages:

  • pyRequestAttachmentPage
    • 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.
  • pyResponseAttachmentPage
    • 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 pyRequestAttachmentPage and pyResponseAttachmentPage.

    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.

Performance considerations

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.

For more information, see Configuring advanced details for a SOAP Connector and Creating a Service SOAP rule.

  • 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.

  • Previous topic REST connector reads payload as binary data instead of text
  • Next topic Configuring a REST connector to receive binary attachments

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us