Invoking AEM Forms using Web Services invoking-aem-forms-using-web-services

Most AEM Forms services in the service container are configured to expose a web service, with full support for web service definition language (WSDL) generation. That is, you can create proxy objects that consume the native SOAP stack of an AEM Forms service. As a result, AEM Forms services can exchange and process the following SOAP messages:

Using web services, you can perform the same AEM Forms services operations that you can by using the Java API. A benefit of using web services to invoke AEM Forms services is that you can create a client application in a development environment that supports SOAP. A client application is not bound to a specific development environment or programming language. For example, you can create a client application using Microsoft Visual Studio .NET and C# as the programming language.

AEM Forms services are exposed over the SOAP protocol and are WSI Basic Profile 1.1 compliant. Web Services Interoperability (WSI) is an open standards organization that promotes web service interoperability across platforms. For information, see https://www.ws-i.org/.

AEM Forms supports the following web service standards:

To invoke AEM Forms services using a web service, typically you create a proxy library that consumes the service WSDL. The Invoking AEM Forms using Web Services section uses JAX-WS to create Java proxy classes to invoke services. (See Creating Java proxy classes using JAX-WS.)

You can retrieve a service WDSL by specifying the following URL definition (items in brackets are optional):

 https://<your_serverhost>:<your_port>/soap/services/<service_name>?wsdl[&version=<version>][&async=true|false][lc_version=<lc_version>]

where:

The following table lists service WSDL definitions (assuming that AEM Forms is deployed on the local host and the post is 8080).

AEM Forms Process WSDL definitions

You must specify the Application name and the Process name within the WSDL definition to access a WSDL that belongs to a process created in Workbench. Assume that the name of the application is MyApplication and the name of the process is EncryptDocument. In this situation, specify the following WSDL definition:

 http://localhost:8080/soap/services/MyApplication/EncryptDocument?wsdl

 http://localhost:8080/soap/services/MyApplication/[<folderA>/.../<folderZ>/]EncryptDocument?wsdl

Accessing new functionality using web services

New AEM Forms service functionality can be accessed using web services. For example, in AEM Forms, the ability to encode attachments using MTOM is introduced. (See Invoking AEM Forms using MTOM.)

To access new functionality introduced in AEM Forms, specify the lc_version attribute in the WSDL definition. For example, to access new service functionality (including MTOM support), specify the following WSDL definition:

 http://localhost:8080/soap/services/MyApplication/EncryptDocument?wsdl&lc_version=9.0.1

Web service BLOB data type

AEM Forms service WSDLs define many data types. One of the most important data types exposed in a web service is a BLOB type. This data type maps to the com.adobe.idp.Document class when working with AEM Forms Java APIs. (See Passing data to AEM Forms services using the Java API.)

A BLOB object sends and retrieves binary data (for example, PDF files, XML data, and so on) to and from AEM Forms services. The BLOB type is defined in a service WSDL as follows:

 <complexType name="BLOB">
     <sequence>
         <element maxOccurs="1" minOccurs="0" name="contentType"
             type="xsd:string"/>
         <element maxOccurs="1" minOccurs="0" name="binaryData"
             type="xsd:base64Binary"/>
         <element maxOccurs="1" minOccurs="0" name="attachmentID"
             type="xsd:string"/>
         <element maxOccurs="1" minOccurs="0" name="remoteURL"
             type="xsd:string"/>
         <element maxOccurs="1" minOccurs="0" name="MTOM"
             type="xsd:base64Binary"
             xmime:expectedContentTypes="*/*"
             xmlns:xmime="https://www.w3.org/2005/05/xmlmime"/>
         <element maxOccurs="1" minOccurs="0" name="swaRef"
             type="tns1:swaRef"/>
         <element maxOccurs="1" minOccurs="0" name="attributes"
             type="impl:MyMapOf_xsd_string_To_xsd_anyType"/>
     </sequence>
 </complexType>

The MTOM and swaRef fields are supported only in AEM Forms. You can use those new fields only if you specify a URL that includes the lc_version property.

Supplying BLOB objects in service requests

If an AEM Forms service operation requires a BLOB type as an input value, create an instance of the BLOB type in your application logic. (Many of the web service quick starts located in Programming with AEM forms show how to work with a BLOB data type.)

Assign values to fields that belong to the BLOB instance as follows:

Accessing data in BLOB objects returned from services

The transmission protocol for returned BLOB objects depends on several factors, which are considered in the following order, stopping when the main condition is satisfied:

As described in the first condition, you can ensure the transmission type for any returned documents by extending the SOAP endpoint URL with a suffix as follows:

     https://<your_serverhost>:<your_port>/soap/services/<service
     name>?blob=base64|dime|mime|http|mtom|swaref

Here is the correlation between transmission types and the field from which you obtain the data:

MTOM transmission of base64-encoded byte arrays

In addition to the BLOB object, the MTOM protocol supports any byte-array parameter or byte-array field of a complex type. This means that client SOAP frameworks supporting MTOM can send any xsd:base64Binary element as an MTOM attachment (instead of a base64-encoded text). AEM Forms SOAP endpoints can read this type of byte-array encoding. However, the AEM Forms service always returns a byte-array type as a base64-encoded text. The output byte-array parameters do not support MTOM.

AEM Forms services that return a large amount of binary data use the Document/BLOB type rather than the byte-array type. The Document type is much more efficient for transmitting large amounts of data.

Web service data types web-service-data-types

The following table lists Java data types and shows the corresponding web service data type.

Creating Java proxy classes using JAX-WS creating-java-proxy-classes-using-jax-ws

You can use JAX-WS to convert a Forms service WSDL to Java proxy classes. These classes enable you to invoke AEM Forms services operations. Apache Ant lets you create a build script that generates Java proxy classes by referencing a AEM Forms service WSDL. You can generate JAX-WS proxy files by performing the following steps:

See also

Creating Java proxy classes using Apache Axis

Invoking AEM Forms using Base64 encoding

Invoking AEM Forms using BLOB data over HTTP

Invoking AEM Forms using SwaRef

Creating Java proxy classes using Apache Axis creating-java-proxy-classes-using-apache-axis

You can use the Apache Axis WSDL2Java tool to convert a Forms service into Java proxy classes. These classes enable you to invoke Forms service operations. Using Apache Ant, you can generate Axis library files from a service WSDL. You can download Apache Axis at the URL https://ws.apache.org/axis/.

You can generate Axis Java library files by performing the following steps:

See also

Creating Java proxy classes using JAX-WS

Invoking AEM Forms using Base64 encoding

Invoking AEM Forms using BLOB data over HTTP

Invoking AEM Forms using Base64 encoding invoking-aem-forms-using-base64-encoding

You can invoke a AEM Forms service using Base64 encoding. Base64 encoding encodes attachments that are sent with a web service invocation request. That is, BLOB data is Base64 encoded, not the entire SOAP message.

“Invoking AEM Forms using Base64 encoding” discusses invoking the following AEM Forms short-lived process named MyApplication/EncryptDocument by using Base64 encoding.

When this process is invoked, it performs the following actions:

Creating a .NET client assembly that uses Base64 encoding creating-a-net-client-assembly-that-uses-base64-encoding

You can create a .NET client assembly to invoke a Forms service from a Microsoft Visual Studio .NET project. To create a .NET client assembly that uses base64 encoding, perform the following steps:

Creating a proxy class

You can create a proxy class that is used to create the .NET client assembly by using a tool that accompanies Microsoft Visual Studio. The name of the tool is wsdl.exe and it is located in the Microsoft Visual Studio installation folder. To create a proxy class, open the command prompt and navigate to the folder that contains the wsdl.exe file. For more information about the wsdl.exe tool, see the MSDN Help.

Enter the following command at the command prompt:

 wsdl https://hiro-xp:8080/soap/services/MyApplication/EncryptDocument?WSDL&lc_version=9.0.1

By default, this tool creates a CS file in the same folder that is based on the name of the WSDL. In this situation, it creates a CS file named EncryptDocumentService.cs. You use this CS file to create a proxy object that lets you invoke the service that was specified in the invocation URL.

Amend the URL in the proxy class to include ?blob=base64 to ensure that the BLOB object returns binary data. In the proxy class, locate the following line of code:

 "https://hiro-xp:8080/soap/services/MyApplication/EncryptDocument";

and change it to:

 "https://hiro-xp:8080/soap/services/MyApplication/EncryptDocument?blob=base64";

The Invoking AEM Forms using Base64 Encoding section uses MyApplication/EncryptDocument as an example. If you are creating a .NET client assembly for another Forms service, ensure that you replace MyApplication/EncryptDocument with the name of the service.

Developing the .NET client assembly

Create a Visual Studio Class Library project that produces a .NET client assembly. The CS file that you created using wsdl.exe can be imported into this project. This project produces a DLL file (the .NET client assembly) that you can use in other Visual Studio .NET projects to invoke a service.

Referencing the .NET client assembly

Place your newly created .NET client assembly on the computer where you are developing your client application. After you place the .NET client assembly in a directory, you can reference it from a project. Also reference the System.Web.Services library from your project. If you do not reference this library, you cannot use the .NET client assembly to invoke a service.

Invoking a service using a .NET client assembly that uses Base64 encoding

You can invoke the MyApplication/EncryptDocument service (which was built in Workbench) using a .NET client assembly that uses Base64 encoding. To invoke the MyApplication/EncryptDocument service, perform the following steps:

Invoking a service using Java proxy classes and Base64 encoding invoking-a-service-using-java-proxy-classes-and-base64-encoding

You can invoke an AEM Forms service using Java proxy classes and Base64. To invoke the MyApplication/EncryptDocument service using Java proxy classes, perform the following steps:

See also

Quick Start: Invoking a service using Java proxy files and Base64 encoding

Creating a .NET client assembly that uses Base64 encoding

Invoking AEM Forms using MTOM invoking-aem-forms-using-mtom

You can invoke AEM Forms services by using the web service standard MTOM. This standard defines how binary data, such as a PDF document, is transmitted over the Internet or intranet. A feature of MTOM is the use of the XOP:Include element. This element is defined in the XML Binary Optimized Packaging (XOP) specification to reference the binary attachments of a SOAP message.

The discussion here is about using MTOM to invoke the following AEM Forms short-lived process named MyApplication/EncryptDocument.

When this process is invoked, it performs the following actions:

The discussion here is about using MTOM withthin a Microsoft .NET project to invoke AEM Forms services. The .NET framework used is 3.5, and the development environment is Visual Studio 2008. If you have Web Service Enhancements (WSE) installed on your development computer, remove it. The .NET 3.5 framework supports a SOAP framework named Windows Communication Foundation (WCF). When invoking AEM Forms by using MTOM, only WCF (not WSE) is supported.

Creating a .NET project that invokes a service using MTOM creating-a-net-project-that-invokes-a-service-using-mtom

You can create a Microsoft .NET project that can invoke a AEM Forms service using web services. First, create a Microsoft .NET project by using Visual Studio 2008. To invoke a AEM Forms service, create a Service Reference to the AEM Forms service that you want to invoke within your project. When you create a Service Reference, specify a URL to the AEM Forms service:

 http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL&lc_version=9.0.1

Replace localhost with the IP address of the J2EE application server hosting AEM Forms. Replace MyApplication/EncryptDocument with the name of the AEM Forms service to invoke. For example, to invoke a Rights Management operation, specify:

http://localhost:8080/soap/services/RightsManagementService?WSDL&lc_version=9.0.1

The lc_version option ensures that AEM Forms functionality, such as MTOM, is available. Without specifying the lc_version option, you cannot invoke AEM Forms using MTOM.

After you create a Service Reference, data types associated with the AEM Forms service are available for use within your .NET project. To create a .NET project that invokes an AEM Forms service, perform the following steps:

Invoking a service using MTOM in a .NET project invoking-a-service-using-mtom-in-a-net-project

Consider the MyApplication/EncryptDocument process that accepts an unsecured PDF document and returns a password-encrypted PDF document. To invoke the MyApplication/EncryptDocument process (which was built in Workbench) by using MTOM, perform the following steps:

See also

Quick Start: Invoking a service using MTOM in a .NET project

Accessing multiple services using web services

Creating an ASP.NET web application that invokes a human-centric long-lived process

Invoking AEM Forms using SwaRef invoking-aem-forms-using-swaref

You can invoke AEM Forms services using SwaRef. The content of the wsi:swaRef XML element is sent as an attachment inside a SOAP body that stores the reference to the attachment. When invoking a Forms service by using SwaRef, create Java proxy classes by using the Java API for XML Web Services (JAX-WS). (See Java API for XML Web Services.)

The discussion here is about invoking the following Forms short-lived process named MyApplication/EncryptDocument by using SwaRef.

When this process is invoked, it performs the following actions:

The discussion below is about how to invoke Forms services by using SwaRef within a Java client application. The Java application uses proxy classes created by using JAX-WS.

Invoke a service using JAX-WS library files that use SwaRef invoke-a-service-using-jax-ws-library-files-that-use-swaref

To invoke the MyApplication/EncryptDocument process by using Java proxy files created using JAX-WS and SwaRef, perform the following steps:

See also

Quick Start: Invoking a service using SwaRef in a Java project

Invoking AEM Forms using BLOB data over HTTP invoking-aem-forms-using-blob-data-over-http

You can invoke AEM Forms services using web services and passing BLOB data over HTTP. Passing BLOB data over HTTP is an alternative technique instead of using base64 encoding, DIME, or MIME. For example, you can pass data over HTTP in a Microsoft .NET project that uses Web Service Enhancement 3.0, which does not support DIME or MIME. When using BLOB data over HTTP, input data is uploaded before the AEM Forms service is invoked.

“Invoking AEM Forms using BLOB Data over HTTP” discusses invoking the following AEM Forms short-lived process named MyApplication/EncryptDocument by passing BLOB data over HTTP.

When this process is invoked, it performs the following actions:

Creating a .NET client assembly that uses data over HTTP creating-a-net-client-assembly-that-uses-data-over-http

To create a client assembly that uses data over HTTP, follow the process specified in Invoking AEM Forms using Base64 encoding. However, amend the URL in the proxy class to include ?blob=http instead of ?blob=base64. This action ensures that data is passed over HTTP. In the proxy class, locate the following line of code:

 "http://localhost:8080/soap/services/MyApplication/EncryptDocument";

and change it to:

 "http://localhost:8080/soap/services/MyApplication/EncryptDocument?blob=http";

Referencing the .NET clienMyApplication/EncryptDocumentt assembly

Place your new .NET client assembly on the computer where you are developing your client application. After you place the .NET client assembly in a directory, you can reference it from a project. Reference the System.Web.Services library from your project. If you do not reference this library, you cannot use the .NET client assembly to invoke a service.

Invoking a service using a .NET client assembly that uses BLOB data over HTTP

You can invoke the MyApplication/EncryptDocument service (which was built in Workbench) using a .NET client assembly that uses data over HTTP. To invoke the MyApplication/EncryptDocument service, perform the following steps:

Invoking a service using Java proxy classes and BLOB data over HTTP invoking-a-service-using-java-proxy-classes-and-blob-data-over-http

You can invoke an AEM Forms service using Java proxy classes and BLOB data over HTTP. To invoke the MyApplication/EncryptDocument service using Java proxy classes, perform the following steps:

Invoking AEM Forms using DIME invoking-aem-forms-using-dime

You can invoke AEM Forms services using SOAP with attachments. AEM Forms supports both MIME and DIME web service standards. DIME lets you send binary attachments, such as PDF documents, along with invocation requests instead of encoding the attachment. The Invoking AEM Forms using DIME section discusses invoking the following AEM Forms short-lived process named MyApplication/EncryptDocument using DIME.

When this process is invoked, it performs the following actions:

This process is not based on an existing AEM Forms process. To follow along with the code examples, create a process named MyApplication/EncryptDocument**using Workbench. (See Using Workbench.)

Creating a .NET project that uses DIME creating-a-net-project-that-uses-dime

To create a .NET project that can invoke a Forms service using DIME, perform the following tasks:

Installing Web Services Enhancements 2.0

Install Web Services Enhancements 2.0 on your development computer and integrate it with Microsoft Visual Studio .NET. You can download Web Services Enhancements 2.0 from the Microsoft Download Center.

From this web page, search for Web Services Enhancements 2.0 and download it onto your development computer. This download places a file named Microsoft WSE 2.0 SPI.msi on your computer. Run the installation program and follow the online directions.

Creating a web reference to an AEM Forms service

After you install Web Services Enhancements 2.0 on your development computer and create a Microsoft .NET project, create a web reference to the Forms service. For example, to create a web reference to the MyApplication/EncryptDocument process and assuming that Forms is installed on the local computer, specify the following URL:

     http://localhost:8080/soap/services/MyApplication/EncryptDocument?WSDL

After you create a web reference, the following two proxy data types are available for you to use within your .NET project: EncryptDocumentService and EncryptDocumentServiceWse. To invoke the MyApplication/EncryptDocument process using DIME, use the EncryptDocumentServiceWse type.

Reference the WSE library

Create a web reference to a Forms service

Invoking a service using DIME in a .NET project

You can invoke a Forms service using DIME. Consider the MyApplication/EncryptDocument process that accepts an unsecured PDF document and returns a password-encrypted PDF document. To invoke the MyApplication/EncryptDocument process using DIME, perform the following steps:

Creating Apache Axis Java proxy classes that use DIME creating-apache-axis-java-proxy-classes-that-use-dime

You can use the Apache Axis WSDL2Java tool to convert a service WSDL into Java proxy classes so that you can invoke service operations. Using Apache Ant, you can generate Axis library files from a AEM Forms service WSDL that lets you invoke the service. (See Creating Java proxy classes using Apache Axis.)

The Apache Axis WSDL2Java tool generates JAVA files that contain methods that are used to send SOAP requests to a service. SOAP requests received by a service are decoded by the Axis-generated libraries and turned back into the methods and arguments.

To invoke the MyApplication/EncryptDocument service (which was built in Workbench) using Axis-generated library files and DIME, perform the following steps:

See also

Quick Start: Invoking a service using DIME in a Java project

Using SAML-based authentication using-saml-based-authentication

AEM Forms supports various web service authentication modes when invoking services. One authentication mode is specifying both a user name and password value using a basic authorization header in the web service call. AEM Forms also supports SAML assertion-based authentication. When a client application invokes an AEM Forms service using a web service, the client application can provide authentication information in one of the following ways:

AEM Forms does not support standard certificate-based authentication but it does support certificate-based authentication in a different form.

The identity of AEM forms users can be represented through a SAML assertion signed using a secret key. The following XML code shows an example of a SAML assertion.

 <Assertion xmlns="urn:oasis:names:tc:SAML:1.0:assertion"
     xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
     xmlns:samlp="urn:oasis:names:tc:SAML:1.0:protocol"
     AssertionID="fd4bd0c87302780e0d9bbfa8726d5bc0" IssueInstant="2008-04-17T13:47:00.720Z" Issuer="LiveCycle"
     MajorVersion="1" MinorVersion="1">
     <Conditions NotBefore="2008-04-17T13:47:00.720Z" NotOnOrAfter="2008-04-17T15:47:00.720Z">
     </Conditions>
     <AuthenticationStatement
         AuthenticationInstant="2008-04-17T13:47:00.720Z"
         AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:unspecified">
         <Subject>
             <NameIdentifier NameQualifier="DefaultDom">administrator</NameIdentifier>
             <SubjectConfirmation>
                 <ConfirmationMethod>urn:oasis:names:tc:SAML:1.0:cm:sender-vouches</ConfirmationMethod>
             </SubjectConfirmation>
         </Subject>
     </AuthenticationStatement>
     <ds:Signature >
         <ds:SignedInfo>
             <ds:CanonicalizationMethod Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#"></ds:CanonicalizationMethod>
             <ds:SignatureMethod    Algorithm="https://www.w3.org/2000/09/xmldsig#hmac-sha1"></ds:SignatureMethod>
             <ds:Reference URI="#fd4bd0c87302780e0d9bbfa8726d5bc0">
                 <ds:Transforms>
                     <ds:Transform Algorithm="https://www.w3.org/2000/09/xmldsig#enveloped-signature"></ds:Transform>
                     <ds:Transform Algorithm="https://www.w3.org/2001/10/xml-exc-c14n#">
                         <ec:InclusiveNamespaces
                             PrefixList="code ds kind rw saml samlp typens #default">
                         </ec:InclusiveNamespaces>
                     </ds:Transform>
                 </ds:Transforms>
                 <ds:DigestMethod Algorithm="https://www.w3.org/2000/09/xmldsig#sha1"></ds:DigestMethod>
                 <ds:DigestValue>hVrtqjWr+VzaVUIpQx0YI9lIjaY=</ds:DigestValue>
             </ds:Reference>
         </ds:SignedInfo>
         <ds:SignatureValue>UMbBb+cUcPtcWDCIhXes4n4FxfU=</ds:SignatureValue>
     </ds:Signature>
 </Assertion>

This example assertion is issued for an administrator user. This assertion contains the following noticeable items:

A client application can retrieve the assertion from any AEM Forms AuthenticationManager API which returns an AuthResult object. You can obtain an AuthResult instance by performing one of the following two methods:

a AEM forms user can be authenticated using a SAML token that is obtained. This SAML assertion (xml fragment) can be send as part of the WS-Security header with the web service call for user authentication. Typically, a client application has authenticated a user but has not stored the user credentials. (Or the user has logged on to that client through a mechanism other than using a user name and password.) In this situation, the client application has to invoke AEM Forms and impersonate a specific user which is allowed to invoke AEM Forms.

To impersonate a specific user, invoke the AuthenticationManager.getAuthResultOnBehalfOfUser method using a web service. This method returns an AuthResult instance which contains the SAML assertion for that user.

Next, use that SAML assertion to invoke any service that requires authentication. This action involves sending the assertion as part of the SOAP header. When a web service call is made with this assertion, AEM Forms identifies the user as the one represented by that assertion. That is, the user specified in the assertion is the user who is invoking the service.

Using Apache Axis classes and SAML-based authentication using-apache-axis-classes-and-saml-based-authentication

You can invoke an AEM Forms service by Java proxy classes that were created using the Axis library. (See Creating Java proxy classes using Apache Axis.)

When using AXIS that uses SAML-based authentication, register the request and response handler with Axis. Apache Axis invokes the handler before sending an invocation request to AEM Forms. To register a handler, create a Java class that extends org.apache.axis.handlers.BasicHandler.

Create an AssertionHandler with Axis

The following Java class, named AssertionHandler.java, shows an example of a Java class that extends org.apache.axis.handlers.BasicHandler.

 public class AssertionHandler extends BasicHandler {
        public void invoke(MessageContext ctx) throws AxisFault {
            String assertion = (String) ctx.getProperty(LC_ASSERTION);

            //no assertion hence nothing to insert
            if(assertion == null) return;

            try {
                MessageElement samlElement = new MessageElement(convertToXML(assertion));
                SOAPHeader header = (SOAPHeader) ctx.getRequestMessage().getSOAPHeader();
                //Create the wsse:Security element which would contain the SAML element
                SOAPElement wsseHeader = header.addChildElement("Security", "wsse", WSSE_NS);
                wsseHeader.appendChild(samlElement);
                //remove the actor attribute as in LC we do not specify any actor. This would not remove the actor attribute though
                //it would only remove it from the soapenv namespace
                wsseHeader.getAttributes().removeNamedItem("actor");
            } catch (SOAPException e) {
                throw new AxisFault("Error occured while adding the assertion to the SOAP Header",e);
            }
        }
 }

Register the handler

To register a handler with Axis, create a client-config.wsdd file. By default, Axis looks for a file with this name. The following XML code is an example of a client-config.wsdd file. See Axis documentation for more information.

 <deployment xmlns="https://xml.apache.org/axis/wsdd/" xmlns:java="https://xml.apache.org/axis/wsdd/providers/java">
     <transport name="http" pivot="java:org.apache.axis.transport.http.HTTPSender"/>
      <globalConfiguration >
       <requestFlow >
        <handler type="java:com.adobe.idp.um.example.AssertionHandler" />
       </requestFlow >
      </globalConfiguration >
 </deployment>

Invoke an AEM Forms service

The following code example invokes an AEM Forms service using SAML-based authentication.

 public class ImpersonationExample {
        . . .
        public void  authenticateOnBehalf(String superUsername,String password,
                String canonicalName,String domainName) throws UMException, RemoteException{
            ((org.apache.axis.client.Stub) authenticationManager).setUsername(superUsername);
            ((org.apache.axis.client.Stub) authenticationManager).setPassword(password);

            //Step 1 - Invoke the Auth manager api to get an assertion for the user to be impersonated
            AuthResult ar = authenticationManager.getAuthResultOnBehalfOfUser(canonicalName, domainName, null);
            String assertion = ar.getAssertion();
            //Step 2 - Setting the assertion here to be picked later by the AssertionHandler. Note that stubs are not threadSafe
            //hence should not be reused. For this simple example we have made them instance variable but care should be taken
            //regarding the thread safety
            ((javax.xml.rpc.Stub) authorizationManager)._setProperty(AssertionHandler.LC_ASSERTION, assertion);
        }

        public Role findRole(String roleId) throws UMException, RemoteException{
            //This api would be invoked under bob's user rights
            return authorizationManager.findRole(roleId);
        }

        public static void main(String[] args) throws Exception {
            ImpersonationExample ie = new ImpersonationExample("http://localhost:5555");
            //Get the SAML assertion for the user to impersonate and store it in stub
            ie.authenticateOnBehalf(
                    "administrator", //The Super user which has the required impersonation permission
                    "password", // Password of the super user as referred above
                    "bob", //Cannonical name of the user to impersonate
                    "testdomain" //Domain of the user to impersonate
                    );

            Role r = ie.findRole("BASIC_ROLE_ADMINISTRATOR");
            System.out.println("Role "+r.getName());
        }
 }

Using a .NET client assembly and SAML-based authentication using-a-net-client-assembly-and-saml-based-authentication

You can invoke a Forms service by using a .NET client assembly and SAML-based authentication. To do so, you must use the Web Service Enhancements 3.0 (WSE). For information about creating a .NET client assembly that uses WSE, see Creating a .NET project that uses DIME.

The WSE architecture uses Policies, Assertions, and SecurityToken data types. Briefly, for a web service call, specify a policy. A policy can have multiple assertions. Each assertion can contain filters. A filter is invoked at certain stages in a web service call and, at that time, they can modify the SOAP request. For full details, see the Web Service Enhancements 3.0 documentation.

Create the Assertion and Filter

The following C# code example creates filter and assertion classes. This code example creates a SamlAssertionOutputFilter. This filter is invoked by the WSE framework before the SOAP request is sent to AEM Forms.

 class LCSamlPolicyAssertion : Microsoft.Web.ServicES4.Design.PolicyAssertion
 {
        public override Microsoft.Web.ServicES4.SoapFilter CreateClientOutputFilter(FilterCreationContext context)
        {
           return new SamlAssertionOutputFilter();
        }
        . . .
 }


 class SamlAssertionOutputFilter : SendSecurityFilter
 {
        public override void SecureMessage(SoapEnvelope envelope, Security security)
        {
           // Get the SamlToken from the SessionState
           SamlToken samlToken = envelope.Context.Credentials.UltimateReceiver.GetClientToken<SamlToken>();
           security.Tokens.Add(samlToken);
        }
 }

Create the SAML Token

Create a class to represent the SAML assertion. The main task that this class performs is convert data values from string to xml and preserve white space. This assertion xml is later imported into the SOAP request.

 class SamlToken : SecurityToken
 {
        public const string SAMLAssertion = "https://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1";
        private XmlElement _assertionElement;

        public SamlToken(string assertion)
             : base(SAMLAssertion)
        {
           XmlDocument xmlDoc = new XmlDocument();
           //The white space has to be preserved else the digital signature would get broken
           xmlDoc.PreserveWhitespace = true;
           xmlDoc.LoadXml(assertion);
           _assertionElement = xmlDoc.DocumentElement;
         }

         public override XmlElement GetXml(XmlDocument document)
         {
            return (XmlElement)document.ImportNode(_assertionElement, true);
         }
        . . .
 }

Invoke an AEM Forms service

The following C# code example invokes a Forms service by using SAML-based authentication.

 public class ImpersonationExample
 {
        . . .
        public void AuthenticateOnBehalf(string superUsername, string password, string canonicalName, string domainName)
        {
            //Create a policy for UsernamePassword Token
            Policy usernamePasswordPolicy = new Policy();
            usernamePasswordPolicy.Assertions.Add(new UsernameOverTransportAssertion());

            UsernameToken token = new UsernameToken(superUsername, password, PasswordOption.SendPlainText);
            authenticationManager.SetClientCredential(token);
            authenticationManager.SetPolicy(usernamePasswordPolicy);

            //Get the SAML assertion for impersonated user
            AuthClient.AuthenticationManagerService.AuthResult ar
                = authenticationManager.getAuthResultOnBehalfOfUser(canonicalName, domainName, null);
            System.Console.WriteLine("Received assertion " + ar.assertion);

            //Create a policy for inserting SAML assertion
            Policy samlPolicy = new Policy();
            samlPolicy.Assertions.Add(new LCSamlPolicyAssertion());
            authorizationManager.SetPolicy(samlPolicy);
            //Set the SAML assertion obtained previously as the token
            authorizationManager.SetClientCredential(new SamlToken(ar.assertion));
        }

        public Role findRole(string roleId)
        {
            return authorizationManager.findRole(roleId);
        }

        static void Main(string[] args)
        {
            ImpersonationExample ie = new ImpersonationExample("http://localhost:5555");
            ie.AuthenticateOnBehalf(
                 "administrator", //The Super user which has the required impersonation permission
                 "password", // Password of the super user as referred above
                 "bob", //Cannonical name of the user to impersonate
                 "testdomain" //Domain of the user to impersonate
                 );

         Role r = ie.findRole("BASIC_ROLE_ADMINISTRATOR");
            System.Console.WriteLine("Role "+r.name);
     }
 }

Related considerations when using web services related-considerations-when-using-web-services

Sometimes issues occur when invoking certain AEM Forms services operations by using web services. The objective of this discussion is to identify those issues and provide a solution, if one is available.

Invoking service operations asynchronously invoking-service-operations-asynchronously

If you attempt to asynchronously invoke an AEM Forms service operation, such as the Generate PDF’s htmlToPDF operation, a SoapFaultException occurs. To resolve this issue, create a custom-binding XML file that maps the ExportPDF_Result element and other elements into different classes. The following XML represents a custom binding file.

 <bindings
        xmlns:xsd="https://www.w3.org/2001/XMLSchema"
        xmlns:jxb="https://java.sun.com/xml/ns/jaxb" jxb:version="1.0"
        xmlns:wsdl="https://schemas.xmlsoap.org/wsdl/"
      wsdlLocation="http://localhost:8080/soap/services/GeneratePDFService?wsdl&async=true&lc_version=9.0.0"
        xmlns="https://java.sun.com/xml/ns/jaxws">
        <enableAsyncMapping>false</enableAsyncMapping>
        <package name="external_customize.client"/>
        <enableWrapperStyle>true</enableWrapperStyle>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='ExportPDF_Result']">
            <jxb:class name="ExportPDFAsyncResult">
            </jxb:class>
        </bindings>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='CreatePDF_Result']">
            <jxb:class name="CreatePDFAsyncResult">
            </jxb:class>
        </bindings>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='HtmlToPDF_Result']">
            <jxb:class name="HtmlToPDFAsyncResult">
            </jxb:class>
        </bindings>
        <bindings node="/wsdl:definitions/wsdl:types/xsd:schema[@targetNamespace='https://adobe.com/idp/services']/xsd:element[@name='OptimizePDF_Result']">
            <jxb:class name="OptimizePDFAsyncResult">
            </jxb:class>
        </bindings>
        <!--bindings node="//wsdl:portType[@name='GeneratePDFService']/wsdl:operation[@name='HtmlToPDF_Result']">
            <jxb:class name="HtmlToPDFAsyncResult"/>
        </bindings-->
 </bindings>

Use this XML file when creating Java proxy files by using JAX-WS. (See Creating Java proxy classes using JAX-WS.)

Reference this XML file when executing the JAX-WS tool (wsimport.exe) by using the - b command line option. Update the wsdlLocation element in the binding XML file to specify the URL of AEM Forms.

To ensure that asynchronous invocation works, modify the end point URL value and specify async=true. For example, for Java proxy files that are created with JAX-WS, specify the following for the BindingProvider.ENDPOINT_ADDRESS_PROPERTY.

https://server:port/soap/services/ServiceName?wsdl&async=true&lc_version=9.0.0

The following list specifies other services that need a custom binding file when invoked asynchronously:

Differences in J2EE application servers differences-in-j2ee-application-servers

Sometimes a proxy library created using a specific J2EE application server does not successfully invoke AEM Forms that is hosted on a different J2EE application server. Consider a proxy library that is generated using AEM Forms that is deployed on WebSphere. This proxy library cannot successfully invoke AEM Forms services that are deployed on the JBoss Application Server.

Some AEM Forms complex data types, such as PrincipalReference, are defined differently when AEM Forms is deployed on WebSphere as compared to the JBoss Application Server. Differences in the JDKs used by the different J2EE application services are the reason why there are differences in WSDL definitions. As a result, use proxy libraries that are generated from the same J2EE application server.

Accessing multiple services using web services accessing-multiple-services-using-web-services

Due to namespace conflicts, data objects cannot be shared between multiple service WSDLs. Different services can share data types and, therefore the services share the definition of these types in the WSDLs. For example, you cannot add two .NET client assemblies that contain a BLOB data type to the same .NET client project. If you attempt to do so, a compile error occurs.

The following list specifies data types that cannot be shared between multiple service WSDLs:

To avoid this problem, it is recommended that you fully-qualify the data types. For example, consider a .NET application that references both the Forms service and Signature service using a service reference. Both service references will contain a BLOB class. To use a BLOB instance, fully-qualify the BLOB object when you declare it. This approach is shown in the following code example. For information about this code exampe, see Digitally Signing Interactive Forms.

The following C# code example signs an interactive form that is rendered by the Forms service. The client application has two service references. The BLOB instance that is associated with the Forms service belongs to the SignInteractiveForm.ServiceReference2 namespace. Likewise, the BLOB instance that is associated with the Signature service belongs to the SignInteractiveForm.ServiceReference1 namespace. The signed interactive form is saved as a PDF file named LoanXFASigned.pdf.

 ???/**
     * Ensure that you create a .NET project that uses
     * MS Visual Studio 2008 and version 3.5 of the .NET
     * framework. This is required to invoke a
     * AEM Forms service using MTOM.
     *
     * For information, see "Invoking AEM Forms using MTOM" in Programming with AEM forms
     */
 using System;
 using System.Collections.Generic;
 using System.Linq;
 using System.Text;
 using System.ServiceModel;
 using System.IO;

 //A reference to the Signature service
 using SignInteractiveForm.ServiceReference1;

 //A reference to the Forms service
 using SignInteractiveForm.ServiceReference2;

 namespace SignInteractiveForm
 {
        class Program
        {
            static void Main(string[] args)
            {
                try
                {
                    //Because BLOB objects are used in both service references
                    //it is necessary to fully-qualify the BLOB objects

                    //Retrieve the form -- invoke the Forms service
                    SignInteractiveForm.ServiceReference2.BLOB formData = GetForm();

                    //Create a BLOB object associated with the Signature service
                    SignInteractiveForm.ServiceReference1.BLOB sigData = new SignInteractiveForm.ServiceReference1.BLOB();

                    //Transfer the byte stream from one Forms BLOB object to the
                    //Signature BLOB object
                    sigData.MTOM = formData.MTOM;

                    //Sign the Form -- invoke the Signature service
                    SignForm(sigData);
                }
                catch (Exception ee)
                {
                    Console.WriteLine(ee.Message);
                }
            }

            //Creates an interactive PDF form based on a XFA form - invoke the Forms service
            private static SignInteractiveForm.ServiceReference2.BLOB GetForm()
            {

                try
                {
                    //Create a FormsServiceClient object
                    FormsServiceClient formsClient = new FormsServiceClient();
                    formsClient.Endpoint.Address = new System.ServiceModel.EndpointAddress("https://hiro-xp:8080/soap/services/FormsService?blob=mtom");

                    //Enable BASIC HTTP authentication
                    BasicHttpBinding b = (BasicHttpBinding)formsClient.Endpoint.Binding;
                    b.MessageEncoding = WSMessageEncoding.Mtom;
                    formsClient.ClientCredentials.UserName.UserName = "administrator";
                    formsClient.ClientCredentials.UserName.Password = "password";
                    b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
                    b.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
                    b.MaxReceivedMessageSize = 2000000;
                    b.MaxBufferSize = 2000000;
                    b.ReaderQuotas.MaxArrayLength = 2000000;

                    //Create a BLOB to store form data
                    SignInteractiveForm.ServiceReference2.BLOB formData = new SignInteractiveForm.ServiceReference2.BLOB();
                    SignInteractiveForm.ServiceReference2.BLOB pdfForm = new SignInteractiveForm.ServiceReference2.BLOB();

                    //Specify a XML form data
                    string path = "C:\\Adobe\Loan.xml";
                    FileStream fs = new FileStream(path, FileMode.Open);

                    //Get the length of the file stream
                    int len = (int)fs.Length;
                    byte[] ByteArray = new byte[len];

                    fs.Read(ByteArray, 0, len);
                    formData.MTOM = ByteArray;

                    //Specify a XML form data
                    string path2 = "C:\\Adobe\LoanSigXFA.pdf";
                    FileStream fs2 = new FileStream(path2, FileMode.Open);

                    //Get the length of the file stream
                    int len2 = (int)fs2.Length;
                    byte[] ByteArray2 = new byte[len2];

                    fs2.Read(ByteArray2, 0, len2);
                    pdfForm.MTOM = ByteArray2;

                    PDFFormRenderSpec renderSpec = new PDFFormRenderSpec();
                    renderSpec.generateServerAppearance = true;

                    //Set out parameter values
                    long pageCount = 1;
                    String localValue = "en_US";
                    FormsResult result = new FormsResult();

                    //Render an interactive PDF form
                    formsClient.renderPDFForm2(
                        pdfForm,
                        formData,
                        renderSpec,
                        null,
                        null,
                        out pageCount,
                        out localValue,
                        out result);

                    //Write the data stream to the BLOB object
                    SignInteractiveForm.ServiceReference2.BLOB outForm = result.outputContent;
                    return outForm;
                }
                catch (Exception ee)
                {
                    Console.WriteLine(ee.Message);
                }
                return null;
            }

            //Sign the form -- invoke the Signature service
            private static void SignForm(SignInteractiveForm.ServiceReference1.BLOB inDoc)
            {

                try
                {
                    //Create a SignatureServiceClient object
                    SignatureServiceClient signatureClient = new SignatureServiceClient();
                    signatureClient.Endpoint.Address = new System.ServiceModel.EndpointAddress("https://hiro-xp:8080/soap/services/SignatureService?blob=mtom");

                    //Enable BASIC HTTP authentication
                    BasicHttpBinding b = (BasicHttpBinding)signatureClient.Endpoint.Binding;
                    b.MessageEncoding = WSMessageEncoding.Mtom;
                    signatureClient.ClientCredentials.UserName.UserName = "administrator";
                    signatureClient.ClientCredentials.UserName.Password = "password";
                    b.Security.Transport.ClientCredentialType = HttpClientCredentialType.Basic;
                    b.Security.Mode = BasicHttpSecurityMode.TransportCredentialOnly;
                    b.MaxReceivedMessageSize = 2000000;
                    b.MaxBufferSize = 2000000;
                    b.ReaderQuotas.MaxArrayLength = 2000000;

                    //Specify the name of the signature field
                    string fieldName = "form1[0].grantApplication[0].page1[0].SignatureField1[0]";

                    //Create a Credential object
                    Credential myCred = new Credential();
                    myCred.alias = "secure";

                    //Specify the reason to sign the document
                    string reason = "The document was reviewed";

                    //Specify the location of the signer
                    string location = "New York HQ";

                    //Specify contact information
                    string contactInfo = "Tony Blue";

                    //Create a PDFSignatureAppearanceOptions object
                    //and show date information
                    PDFSignatureAppearanceOptionSpec appear = new PDFSignatureAppearanceOptionSpec();
                    appear.showDate = true;

                    //Sign the PDF document
                    SignInteractiveForm.ServiceReference1.BLOB signedDoc = signatureClient.sign(
                        inDoc,
                        fieldName,
                        myCred,
                        HashAlgorithm.SHA1,
                        reason,
                        location,
                        contactInfo,
                        appear,
                        true,
                        null,
                        null,
                        null);

                    //Populate a byte array with BLOB data that represents the signed form
                    byte[] outByteArray = signedDoc.MTOM;

                    //Save the signed PDF document
                    string fileName = "C:\\Adobe\LoanXFASigned.pdf";
                    FileStream fs2 = new FileStream(fileName, FileMode.OpenOrCreate);

                    //Create a BinaryWriter object
                    BinaryWriter w = new BinaryWriter(fs2);
                    w.Write(outByteArray);
                    w.Close();
                    fs2.Close();
                }

                catch (Exception ee)
                {
                    Console.WriteLine(ee.Message);
                }
            }
        }
 }

Services starting with the letter I produce invalid proxy files services-starting-with-the-letter-i-produce-invalid-proxy-files

The name of some AEM Forms generated proxy classes are incorrect when using Microsoft .Net 3.5 and WCF. This issue occurs when proxy classes are created for the IBMFilenetContentRepositoryConnector, IDPSchedulerService or any other service whose name starts with the letter I. For example, the name of the generated client in case of IBMFileNetContentRepositoryConnector is BMFileNetContentRepositoryConnectorClient. The letter I is missing in the generated proxy class.