Skip to main content
This content has been archived and is no longer being updated. Links may not function; however, this content may be relevant to outdated versions of the product.

How to attach a binary file to a SOAP service message


SOAP services can accept and process binary attachments received from an incoming SOAP request. However, if you are using a Process Commander SOAP connector, you must configure both the service and the connector to process binary files. For example, SOAP services can receive and process and attach to a work object binary objects such as images, PDF files, Microsoft Office documents, or video and audio files to a request from a connector.

Note: You must have access to an incoming SOAP connection capable of sending/receiving binary attachments. For more information about the configuration of such a connector in Process Commander, see How to configure a SOAP or dotNET connector to send or receive SOAP with attachments.


In this example, an auto insurance customer must send a picture of a damaged vehicle. The image is sent as an attachment in the SOAP service request, and attached to a claim work object.

Suggested Approach

Complete the following steps to configure a SOAP service to receive binary attachments:

  1. Create a new SOAP service using the Service Accelerator or access an existing SOAP Service rule. For more information about creating services using the Service Accelerator, see Using the Service Accelerator.
  2. Add the Data-ServiceMessages class to the Pages & Classes tab:
  3. On the Servicetab of the service activity add:
    1. A step to open the desired work object.

      For the purposes of this example, property .pyID is being set to a static value. However, in a real-world scenario, you can set this property dynamically using a parameter or Global Resource Setting syntax.
    2. A step to attach the image to the opened work object. For ease of use, call separate activity to complete this method. Detailed instructions for this activity are provided in Step 4.
    3. A Commit statement to save the updated work object back to the database.
  4. Create an activity to attach the image to a the opened work object. For more information about attaching items to work objects, see How to create activities that attach files to work objects.
    1. On the Pages & Classes tab, define the following:
    2. Add a step to set the properties on the Attachment page to the values received by the SOAP Service.

      Property Value Description
      .pxAttachName pyRequestAttachmentPage.pyAttachNames(1) The name of the received file becomes the attachment name
      .pyAttachStream pyRequestAttachmentPage.pyAttachValues(1) The raw data of the attachment.
      .pxAttachedBy .pxRequestor.pyUserIdentifier The operator responsible for attaching the file. This value is set to the current operator in this example, but can vary based on your implementation.
      .pxAttachKey @getCurrentTimeStampUnique() The unique key associated with the attachment.
      .pxRefObjectKey pyWorkPage.pzInsKey The .pzInsKey value of the currently open work object. This field links the attachment to a specific work object.
      .pyNote @truncateLongText(pyRequestAttachmentPage.pyAttachNames(1),60) Any note that can be used to identify the attachment. In this example, the note is set to a truncated version of the attachment name.
    3. Add a step to save the contents of the AttachmentsPage (Data-WorkAttach-File class).
    4. Add a step to link the attachment to the work object.

      This step creates the link object that connects the new work object attachment to the work object. The step page is specified as pyWorkPage. Therefore, the Link-Objects method creates a link object of class Link-Attachment (LinkClass parameter) that links pyWorkPage to the AttachmentPage (LinkToPage parameter), which now has the binary file (privacy policy).

      To set additional properties on the link object page, use the LinkPageProperty and LinkPageValue parameters. For example, to identify a category for the attachment, you specify the pyCategory property as the LinkPageProperty and specify the category with the LinkPageValue parameter.

Open the work object and observe the attachment.

Processing Multiple Attachments

To process multiple attachments, make changes to the following steps above:

5. Add the following parameters to the Parameters tab:

5b. Use the parameter values to set the values of the attachment properties.

4.b. Add a For-Each loop to the method that calls the activity to attach the binary files to the work object.

Field Value
Property name pyRequestAttachmentPage.pyAttachNames
attachmentName pyRequestAttachmentPage.pyAttachNames(<current>)
attachmentValue pyRequestAttachmentPage.pyAttachValues(<current>)

For each pyAttachName value on the Attachments Page, this method passes the attachment name and attachment stream to the AttachAPicture activity.

Suggest Edit
Did you find this content helpful?

33% found this useful

Have a question? Get answers now.

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

Ready to crush complexity?

Experience the benefits of Pega Community when you log in.

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

Pega Community has detected you are using a browser which may prevent you from experiencing the site as intended. To improve your experience, please update your browser.

Close Deprecation Notice
Contact us