Skip to main content


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

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 configure a SOAP or dotNET connector to send or receive SOAP with attachments

Updated on August 24, 2021

Summary

Starting in Version 5.4, SOAP dotNET connectors can send or receive SOAP messages with attachments.

  • When a SOAP connector receives a SOAP attachment, it creates a page named pyAttachmentPage (of class Data-ServiceMessage) and puts the SOAP attachment on that page using the properties pyAttachNames and pyAttachValues. The connector activity can then extract the file from the pyAttachmentPage and, perhaps, attach it to the work object.
  • When a SOAP connector sends a SOAP message with attachments, it expects to find the binary file for the attachment on the pyAttachmentPage (of class Data-ServiceMessage). The connector activity must include a step that puts the file on the pyAttachmentsPage before the activity step that invokes the connector.

The Process Commander SOAP and dotNET connector architecture uses an Axis client to make the SOAP call and process the SOAP response. In version 5.4, two versions are available: 1.2.1 and Axis2. To send SOAP with attachments, the SOAP or dotNET connector must use the Axis2 client.

When a SOAP connector uses the Axis2 client, it must also use a new data type instead of XML Page for mapping XML objects: XML Literal. The XML Literal data type holds the actual, literal un-encoded XML and replaces the model-based paradigm used for literal XML data manipulation when the Axis client is version 1.2.1. When you use this data type, you can map the data for an XML object from an XML stream rule or a single value text property and you can map it to an XML parse rule or a single value text property.

This article describes how to configure a SOAP connector to both send and receive SOAP with attachments. In both cases, you run the Connector Accelerator as usual, but then you change the default settings in the generated connector rule, and either edit the connector activity or create a new one.

See also:

 

Configure SOAP connectors that send SOAP with attachments

To accomplish this task you use the Connector Accelerator to generate the SOAP connector (Application > New > Connector) as usual. For help, see Building SOAP Connectors and the help accessible from each form. Then you add steps to the connector activity and modify the connector rule.

Edit the connector activity

Connector activities that call a SOAP connector that sends an attachment should do the following:

1.    Create the pyAttachmentPage page of class Data-ServiceMessage.

2.    Obtain the file the connector is to send. For example:

  • If the file is an instance of Rule-File-Text or Rule-File-Binary, you can use one of the Obj-Open methods to get a copy.
  • If the file is currently attached to the work object, you can use the pzInsKey of the work object to browse the Link-Attachment class and locate the attachment. Note the following:
    • The value of the work object’s pzInsKey property is the value of the Link-Attachment object’s pxLinkedRefFrom property.
    • The value of the Link-Attachment object’s pxLinkedRefTo property is the pzInsKey of the attachment.

3.   Put the file or work object attachment on the pyAttachmentPage. It must:

  • Put the name in pyAttachNames property (the name is used as the Content-ID in the MIME header for the attachment)
  • Put the content – the binary data – in pyAttachValues property
  • Set the Content Type MIME type of the file in the pyAttachTypes property. For example, image/gif or image/jpg.

Note: if you do not set the content type in pyAttachTypes, Process Commander sets it to application/octet-stream, which probably isn’t what you want.

Locate and open the connector activity. Before the activity step that invokes the connector with the Connect-SOAP or Connect-dotNET method, insert steps that locate the file you want attached to the SOAP message and put it on the pyAttachmentPage page.

Example

The following figure shows what the Pages and Classes tab of the generated connector activity might look like after editing it:

The DataPage is the one generated by the accelerator. Because this example activity retrieves a file that is stored as an instance of Rule-File-Binary, the tab defines a page for the sample file to be retrieved to (SampleFile). It also defines the pyAttachmentPage where the sample file needs to be placed before the connector is called.

The next figure shows what the steps might look like after the generated activity is modified:

The first two steps set up the data for the SOAP message. You would edit the Property-Set step generated by the accelerator as usual. Following is the step that retrieves the file that gets attached to the outbound SOAP message as a SOAP attachment:

The InstanceHandle parameter is set to the value of the binary file rule’s pzInsKey property.

The next step copies the binary file to the pyAttachmentsPage page, where the SOAP connector expects to find it when it runs:

This step copies the contents of the file to the pyAttachValues property, copies the name of the file to the pyAttachNames field, and uses the pyFileType of the file as the content type mime type in the pyAttachTypes field. Note that these properties are Value List properties so you must specify an index value, as shown.

When the next step calls the connector rule (Connect-SOAP step), the connector rule will use the file from the pyAttachmentsPage page as a SOAP attachment.

Edit the connector rule

Locate and open the generated connector rule and make the following changes:

1.    On the Advanced tab, under Client Properties, set the version of Axis to Axis2.

2.    On the Request tab, select Send attachments with request.

3.    Then examine the data mapping rows on the Request and Response tabs. Do any of the rows map XML objects with the XML Page data type?

 

Configure SOAP connectors that receive SOAP messages with attachments

To accomplish this task you use the Connector Accelerator to generate the SOAP connector (Application > New > Connector) as usual. For help, see Building SOAP Connectors and the help accessible from each form. Then you add steps to the connector activity that process the incoming attachment and modify the connector rule or create a new one.

Create or edit the connector activity

Typically, the connector activity processes the incoming SOAP attachment by attaching it to the work object. Remember the following about work objects and work object attachments:

  • The work object must exist before you can create a work object attachment for it. That is, the work object must be committed, not just saved to the deferred operations list with an Obj-Save method, before you can attach something to it.
  • Creating attachments is a two-part process: an activity must create the attachment object (of class Data-WorkAttach-File), and then it must create a link object (of class Link-Attachment) that connects the attachment to the work object.
  • Set a value for the pyNote property so an entry is written in the audit trail (history). Notes are limited to 60 characters.

Activities that create the attachment objects and link them to their work objects should do the following:

  1. Create a page for the work object attachment (Data-WorkAttach-File class).
  2. Copy the file from the pyAttachment page (Data-ServiceMessage class) to the work object attachment page.
  3. Save the attachment page (Obj-Save method).
  4. Create a link object (Link-Attachment class) that connects the attachment to the work object with the Link-Objects method.
  5. Commit the attachment object and the link object.

For more information, see PRKB-24121 How to create activities that attach files to work objects.

Example:

The following figure shows the Pages and Classes tab of an example connector activity:

Because the connector activity typically belongs to the same class as the work object, there’s no need to define pyWorkPage. Therefore, the tab defines the requestor page, the page where the attachment is stored (pyAttachmentPage), and the work object attachment page where the SOAP attachment is copied (NewAttachment).

The next figure shows the Steps tab of the example connector activity:

The first two steps gather the information for the outbound SOAP message and then call the connector. Step 3 calls an activity that adds the attachments (AddAttachment).

The following figure is an expanded image of step 3. This step calls the AddAttachment activity for each element in the Value List property pyAttachmentPage.pyAttachNames in case there are multiple SOAP attachments:

This figure shows the AddAttachment activity.

The first step creates the attachment page, NewAttachment; step 2 copies the files from the pyAttachmentPage to the pyAttachStream property on the NewAttachment page; step 3 saves the attachment page; and step 4 uses the Link-Objects method to link the work object to the attachments.

Here's the Property-Set step that copies the SOAP attachments to the NewAttachment page:

This step also copies or sets other property values that are needed to create a work object attachment: pxAttachName, pxAttachedBy, pxAttachKey, pxRefObjectKey, and pyNote.

The work attachment page must be saved before it can be linked to the work object so the next step uses Obj-Save. Then the activity uses the Link-Objects method to attach the file to the work object as a work object attachment:

The Link-Objects step creates the link object that connects the new work object attachment to the work object. The step page is the primary page, which in this case is pyWorkpage. Therefore, the Link-Objects method creates a link object of class Link-Attachment (LinkClass parameter) to the NewAttachment page (LinkTo parameter), which has the SOAP attachment file.

Note: 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.

When the connector activity exits, flow processing commits the deferred operations list and the work object and work object attachment are committed to the database.

Edit the connector rule

Locate and open the generated connector rule and make the following changes:

1.   On the Advanced tab, under Client Properties, set the version of Axis to Axis2.

2.   On the Response tab, select Extract attachments from response.

3.   Then examine the data mapping rows on the Request and Response tabs. Do any of the rows map XML objects with the XML Page data type?

Convert XML Page data mappings to XML Literal

When you convert data mappings from XML Page to XML Literal, you manually change the data mapping settings in the connector rule and you may need XML parse and stream rules to interpret or produce the data. If you need XML parse and/or stream rules, use the Metadata Accelerator to generate them.

Generate XML parse and stream rules

If you need XML parse and stream rules, determine whether the WSDL you used to generate the SOAP connector contains schema descriptions of the data types. If it does not, obtain an XSD or DTD file that describes the schema in the messages. Then, after you generate the connector rules, run the Accelerator again and select the Generate Data Mapping Rules option. Additionally:

  • Use the same base class, RuleSet, and RuleSet version that you used for the connector rules.
  • Select the XML parse and XML stream rule options only on the Select Rule Types form. Do not generate properties and classes again.

Note: Start the accelerator from the Integration slice. From the main Process Commander portal page, select Integration. From the Integration home page, under Accelerators, select Connector and Metadata Accelerator. For help with the accelerator forms, click the help button to see the Application Developer Help.

Edit the data mapping settings

After generating the parse and stream rules, return to the SOAP connector rule and change the data types in the data mappings for the XML objects:

1.  On the Request tab, for each mapping that specifies the XML Page data type:

  • Change the data type to XML Literal.
  • Select XML Stream in the Map From field.
  • Specify the appropriate XML stream rule in the Map From Key field.

2. On the Response tab, for each mapping that specifies the XML Page data type:

  • Change the data type to XML Literal.
  • Select XML Parse in the Map To field.)
  • Specify the appropriate XML parse rule in the Map To Key field.

Note: The first key to the parse or stream rule is assumed to be that of the connector rule. If that is not the case, map the XML to or from a single-value text property and then call the parse or stream rule from the connector activity with the Apply-Parse-XML or Property-Set-XML methods.

3. On the Advanced tab, delete any rows in the Schema Definitions section.

4. Save the rule.

Test the Configuration

If you are far enough in your development cycle that the work flow for which you are building this SOAP connector exists, run through the flow to the point where the SOAP connector gets called to verify that it works as expected.

If the flow is not yet built, you can use the Run Rule option in the connector activity to run the activity and invoke the connector.

See also: Testing Services and Connectors.

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