Signature Appliance SOAP API: User management with Java NetBeans

This recipe demonstrates how to setup a Java NetBeans project to use the Signature Appliance SOAP API.

API Recipe source files are available on GitHub.

NetBeans is an alternative to the “hand-rolled” Java setup example shown in the SOAP API Quick Start page.

User Management API Support

The example uses the Web Services User Management API to fetch a user list from the signature appliance. The username for the appliance must include administrative privileges. Please note that your developer sandbox username does not include administrative privileges.

To use the User Management functions during your development, please contact your account executive for access to a different appliance.

NetBeans Project description

This project was written in the NetBeans IDE 7.1.2. on a Windows 7 machine with Java 1.7.0_05 installed. The NetBeans IDE takes care of some technical details on your behalf and hides the details.

In our example, the WSDL definition XML file that serves as a contract between the client side and the signature appliance, and the way it is used to generate the client side stubs, are automatically handled by the NetBeans IDE.

The IDE uses the standard ‘wsimport’ Java tool to generate the client-side stub Java classes that will be used by our example app.

The NetBeans final project layout

Adding and configuring the Web Services reference

After the WSDL is added to the project, the NetBeans IDE will examine the server’s certificate and ask if each certificate in the chain of trust should be added as a trusted certificate to the JRE certificate store.

The certificate chain for your DocuSign Signature Appliance will be different from this example and may use fewer or more intermediary certificates below the root certificate.

All the certificates shown in this example were needed by the “IDE TrustManager” when retrieving the wsdl to build the client side stubs.

In our tests, the IDE’s certificate approval requests stopped before the root certificate. We suspect that the NetBeans IDE Trust Manager wants to store all of the intermediate certificates even if it already has the root certificate in the trust store.


Add the WSDL file to the project


Add the Signature Appliance’s cert to the trust store


Add an intermediary cert to the trust store


Add the root cert to the trust store

The NetBeans IDE invokes the wsimport java tool to create the stubs for the web services client init:

wsimport-init:
Created dir: C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\build\\generated-sources\\jax-ws
wsimport-client-spml:
Created dir: C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\build\\generated\\jax-wsCache\\spml
command line: wsimport -d C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\build\\generated\\jax-wsCache\\spml -extension -Xnocompile -Xendorsed -keep -s C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\build\\generated\\jax-wsCache\\spml -catalog C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\catalog.xml -verbose C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\xml-resources\\web-service-references\\spml\\wsdl\\prime.cosigntrial.com_8080\\SAPIWS\\spml.asmx.wsdl -wsdllocation https://prime.cosigntrial.com:8080/SAPIWS/spml.asmx?WSDL
parsing WSDL...
generating code...
com\\arx\\sapiws\\spml\\_1\\Add.java
com\\arx\\sapiws\\spml\\_1\\AddGroup.java
...
oasis\
ames\\tc\\spml\\_2\\_0\\search\\SearchResponseType.java
oasis\
ames\\tc\\spml\\_2\\_0\\search\\package-info.java
Copying 98 files to C:\\Users\\avivs\\Documents\\NetBeansProjects\\CoSignSapiUMBasicSample\\build\\generated-sources\\jax-ws
BUILD SUCCESSFUL (total time: 5 seconds)

The Example App

The example fetches user information from the signature appliance. A command line interface is used, the user enters:

  • The number of users to be fetched
  • user name for an administrative user
  • password

Code excerpt

The Java code that accesses the server and fetches the user information

// ....
String howManyUsersToFetch = args[0];   //number of users to get from cosign server
String AdminName = args[1];             //cosign admin user
String AdminPassword = args[2];         //cosign admin user password
int nUsersToFetch = Integer.parseInt(howManyUsersToFetch);
 
// prepare CoSignLogonData
CoSignLogonData coSignLogonData = new CoSignLogonData();
coSignLogonData.setUser(AdminName);
coSignLogonData.setPassword(AdminPassword);
 
// build a search request
SearchRequestType searchRequest = new SearchRequestType();
searchRequest.setCoSignLogonData(coSignLogonData);
searchRequest.setMaxSelect(nUsersToFetch);
searchRequest.setReturnData(ReturnDataType.DATA);
searchRequest.setExecutionMode(ExecutionModeType.SYNCHRONOUS);
 
// build the spml client
SPML spmlClient = new SPML(new URL("https://prime.cosigntrial.com:8080/SAPIWS/spml.asmx"));
SPMLSoap SPMLSoapClient = spmlClient.getSPMLSoap();
 
// perform the search
SearchResponseType searchResponse = SPMLSoapClient.search(searchRequest);
ErrorCode errCode = searchResponse.getError();
if (errCode == null)
{
    // print result
    List psoList = searchResponse.getPso();
    for (int i = 0; i