Invoking services in AEM forms with document input and output values

You can invoke services that require file attachments as input values.

For example, service input and output variables of type document are represented in SOAP messages as file attachments. To provide input document values, the SOAP message includes a file attachment. Response messages include file attachments when web services have output variables of type document.

Files can be attached as MIME or MTOM attachments, base64-encoded text, or using the URL of the file. The SOAP message and the configuration of the Invoke Web Service operation are different for each type of attachment. If you are invoking a AEM forms web service that returns a document value, you specify a method to attach the file to the SOAP response message.

Note: Web services that AEM forms provides do not support MTOM attachments.

Before you configure file attachments, use the Web Service Options property of the Invoke Web Service operation to generate a template SOAP request message. (See About Web Service Settings .)

Configuring request messages

The Web Service Settings dialog box automatically generates a SOAP message for invoking the web service. The message is based on the web service properties that you specified.

You add file attachments that represent document values of service input parameters to the SOAP message. The following XML code shows the general structure of a SOAP message that is used to a call a web service operation: 

<soapenv:Envelope 
    xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ 
    xmlns:ser="http://foo.net/services"> 
    <soapenv:Header /> 
    <soapenv:Body> 
        <ser:operation_name> 
            <ser:parameter_name> 
                <!-- elements for file attachments are placed here --> 
            </ser:parameter_name> 
        </ser:operation_name> 
    </soapenv:Body>  
</soapenv:Envelope>

  • The Body element contains one element that has the same name as the service operation.

  • The operation_name element contains one element for each input parameter. The names of these elements are the same as the parameter names. For the web services of activated processes, the operation name is always invoke. Parameter names are the names of the input variables that are defined in the process.

  • The method used to attach files to the SOAP message determines the elements that are used to identify file attachments. The methods available are MIME, MTOM, base64-encoded text, or file URLs. (Web services that AEM forms provides do not support MTOM attachments.)

MIME/MTOM attachment

Use the Attachment tab of the Web Service Settings dialog box to specify the document value. Each row in the table represents a file attachment. The Part column contains the identification of the attachment. The web service determines the identification.

Configure a MIME/MTOM attachment:

  1. On the Web Service Settings dialog box, click the Attachment tab.

  2. To add rows to the table, click Load Attachment Part.

  3. Note the values in the Part column. You use these values in step 7.

  4. For each row in the table, click the Attachment field. Click the ellipsis button that appears to open XPath Builder.

  5. For each row in the table, click the Content-Type cell and type the MIME type of the file that you are attaching. An example of a MIME type is application/pdf .

  6. Click the Request tab, and add an attachmentID element inside each element that represents the parameter that takes a file attachment as the value.

  7. Inside each attachmentID element, type the text that appears in the Part column for the attachment on the Attachment tab.

Example

The following SOAP request is an example of a configuration for a MIME or MTOM attachment. It is a request message for a process with an input parameter named documentIn, which is a document value. 

<soapenv:Envelope 
    xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ 
    xmlns:ser="http://adobe.com/idp/services"> 
    <soapenv:Header/> 
    <soapenv:Body> 
        <ser:invoke> 
            <ser:documentIn> 
                <ser:attachmentID> 
                    part0 
                </ser:attachmentID> 
            </ser:documentIn> 
        </ser:invoke> 
    </soapenv:Body>  
</soapenv:Envelope>

base64-encoded text attachment

The content MIME type and the base64-encoded text representation of the file is included in the SOAP message. The content type is specified in a contentType element. The text is specified in a binaryData element.

To obtain the base64-encoded text, you can use the getDocContentBase64 XPath function.

The following procedure assumes that the base-64 encoded text that represents the document value is stored in a process variable.

Configure a base64-encoded text attachment:

  1. On the Web Service Settings dialog box, click the Request tab.

  2. Add a contentType element to the element that represents the parameter that specifies the document value.

  3. Inside the contentType element, either type the content type or add an XPath expression that resolves to a string variable that contains the content type.

  4. Add a binaryData element to the element that represents the parameter that takes the document value.

  5. Inside the binaryData element, add an XPath expression that resolves to a string variable that contains the base64-encoded text that represents the document.

Example

The following SOAP request is an example of a configuration for a base64-encoded text attachment.It is a request message for a process with an input parameter named documentIn, which is a document value. 

<soapenv:Envelope 
    xmlns:soapenv=http://schemas.xmlsoap.org/soap/envelope/ 
    xmlns:ser="http://adobe.com/idp/services"> 
    <soapenv:Header/> 
    <soapenv:Body> 
        <ser:invoke> 
            <ser:documentIn> 
                <ser:contentType> 
                    {$/process_data/@contentType$} 
                </ser:contentType> 
                <ser:binaryData> 
                    {$/process_data/@docBase64$} 
                </ser:binaryData> 
            </ser:documentIn> 
        </ser:invoke> 
    </soapenv:Body>  
</soapenv:Envelope>

File URL attachment

The URL of the file is specified in a remoteURL element.

Configure a file URL attachment:

  1. On the Web Service Settings dialog box, click the Request tab.

  2. Inside the element that represents the parameter that takes the document value, add a remoteURL element.

  3. Inside the remoteURL element, either type the URL of the file or add an XPath expression that resolves to a string variable that contains the URL.

Example

The following SOAP request is an example of a configuration for a file URL attachment. It is a request message for a process with an input parameter named documentIn, which is a document value. 

<soapenv:Envelope 
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
xmlns:ser="http://adobe.com/idp/services"> 
<soapenv:Header/> 
<soapenv:Body> 
<ser:invoke> 
    <ser:documentIn> 
        <ser:remoteURL> 
            http://help.adobe.com/en_US/AEM forms/es/overview.pdf 
        </ser:remoteURL> 
    </ser:documentIn> 
</ser:invoke> 
</soapenv:Body>  
</soapenv:Envelope>

Configuring web service response messages

When a AEM forms web service returns a document value, the value is an attachment to the SOAP response message. By default, AEM forms web services store the result document value on the AEM forms Server. The web services also include the URL to the document in the response message. However, if the SOAP request message includes a MIME attachment, the response also uses a MIME attachment to return document values.

You can override the default behavior and specify the method that AEM forms web services use to return document attachments. You can attach files to SOAP response messages as MIME attachments, base64-encoded text, or using the URL of the file. To specify the way files are attached to response messages, append one of the values in the following table to the Target URL. You specify the Target URL property on the Settings tab of the Web Service Settings dialog box:

Attachment type

Text to append

base64-encoded text

?blob=base64

MIME

?blob=mime

File URL

?blob=http

For example, the following value for Target URL causes the web service of a process to attach files to SOAP response messages as base64-encoded text. The process name is echoDocument: 

http://localhost:8080/soap/services/echoDocument?blob=base64

Override default SOAP response message attachment behavior:

  1. On the Web Service Settings dialog box, click the Settings tab.

  2. In the Target URL box, append one of the following values to the URL:

    • ?blob=base64

    • ?blob=mime

    • ?blob=http

// Ethnio survey code removed