Copyright 2013 Consona Corporation. All rights reserved www.compiere.com

Table of Contents Compiere SOAP API... 3 Accessing Compiere SOAP... 3 Generate Java Compiere SOAP Client... 3 Using the Java Compiere SOAP Client... 4 Known Restrictions... 4 Licensing... 5 API Use... 5 Multiple Targets... 6 API Specifics... 6 Naming... 6 Data Transport (or Transfer) Object:... 6 Primary Key... 6 Foreign Key... 7 Pick... 7 Processes... 7 Workflow... 8 Security... 8 Authentication... 8 Transport Level Security... 8 Setup... 9 Examples... 9 Copyright 2013 Consona Corporation All rights reserved Page 2

Compiere SOAP API The Compiere SOAP framework allows integration of Compiere with third-party applications, and also enables third-party applications to call Compiere web services. This document allows you to access Compiere SOAP, generate and use the SOAP client. It also deals with the security aspects like authentication and transport level security. Accessing Compiere SOAP Add the file ws.war to Tomcat. You can build the war file from source via the command mvn install from the ws directory, generating the file ws/target/ws.war. Assuming, the base (SOAP Service Point) URL is http://localhost:8888, check the following URLs: http://localhost:8888/ws/soap?wsdl - the WSDL file http://localhost:8888/ws/xsd=1 - the XSD part only The SOAP client for a platform can be generated by pointing to the WSDL file. Generate Java Compiere SOAP Client In package ws-sdk, check the Ant file build.xml for the WSDL location and execute it with Ant. The generated Java client is enhanced by Java/Compiere specific functionality: 1. Convenience constructors, constants and methods (tostring, equals, hashcode) 2. Value Defaults 3. Fluent API (withxx(x)) 4. Date handling The objective is to make the Java SOAP API as convenient as using the direct Compiere API. Note that you might have to explicitly set the JAVA_HOME environment variable to Java 7 JDK for the generation, as we use the latest JAXB version. This requires Java 7 also for the Java SOAP client. You could use the generated Compiere Java SOAP API code, but you might need to regenerate it if you add columns, tables, processes, or pick list values. The Ant build requires a running Compiere server and generates the classes in the package org.compiere.sdk.ad in the directory src/main/java and also downloads and stores the WSDL and XSD file in the directory src/main/resources. For convenience, you can use the class org.compiere/sdk.compiereclient. This class extends org.compiere.sdk.compieresoapimpl, which exposes all SOAP operations and eliminates the need to deal with the JAXB packaging. This class is generated by the class, org.compiere.sdk.generateclientimpl. Copyright 2013 Consona Corporation All rights reserved Page 3

Note: Eventually, this should be run automatically in the Ant build. Using the Java Compiere SOAP Client Here are some examples on how to use the Compiere client: (Without modification, the examples assume the SOAP server is on http://localhost:8888/ws). src/test/java - org.compiere.sdk.it_compiereclient - Basic connection and functionality test src/test/java - org.compiere.sdk.it_orderprocess - Creating an order and processing it to create shipment plus invoice. Known Restrictions 1. The size of the WSDL file is currently 4.7MB. When a Java client is opened, it requests the current version, that is, the server basically serializes the entire dictionary and the client has to parse a sizable file. The options to address this are: a. To use ETags on the server to allow caching in the infrastructure and maybe also internal caching. b. To extend the default request notation from http://localhost/ws/soap?wsdl to a location such as http://localhost/ws/soap/component?wsdl (localhost is just a placeholder for the server URL). This would allow you to build smaller SOAP clients. The challenge is to define the components. 2. The current implementation uses the standard Compiere user credentials (username, password, and role name) to determine the available objects and methods. It might be sensible to generate specific API ID/secret for a given user. The alternative is to define a dedicated user. One of the considerations to use a specific API ID/secret is, if, for example, you want to allow end users to log in through a mobile device. 3. The SOAP API basically exposes the CRUD functionality. The Java API has quite a few convenience methods (for example, setting the business partner on an order sets also payment term, etc. of the customer). Depending on the usage, we may want to provide similar or better functionality with the SOAP API in future. This might include also the ability to create header and lines in one transaction (rather than first saving the header). 4. For pick lists, only the value is exposed in the API, and not the name. For the field, AD_Table.AccessLevel, the API exposes the values, 1, 2, 3, 4, 6, 7, but not the corresponding names, Organization, TenantOnly, TenantPlusOrganization, SystemOnly, SystemPlusTenant, All, due to the restriction that XSD elements only have a name and no description. Copyright 2013 Consona Corporation All rights reserved Page 4

2. It might be possible to tweak the JaxB generation process to expose annotations for values. 3. Fault Handling - Currently Java client does not throw the transaction specific fault (for example. LoginFault), but the more generic SOAPFaultException. The method, CompiereClient.getExceptionMethod(Exception), mitigates this by inspecting the XML elements and providing the information. 4. Defaults - Constants are automatically applied. In contrast to the base product, fields with defaults referencing foreign keys, variables, or formulas are not included. Licensing The SOAP services allow the use of a single technical Compiere user to many real users ( consolidator ). For licensing, the actual users using the SOAP services need to be licensed, even though they do not log in directly. API Use After obtaining the client from the SOAP infrastructure, you need to log in providing the username, password, and role (first role found is used, if not specified). On successful login, this call returns the client, organization, user and role, as well as a Session ID (SID). This SID is a code, which needs to be included in the SOAP SecurityHeader in subsequent calls (or alternatively in the http request header). The session expires on logout or after timeout. It is recommended to always log out explicitly. The Java CompiereClient automatically handles the SID and the SecurityHeader. For a given operation, you can use the raw API from the SOAP Port. For example, QueryResponse CompiereSoap.query(QueryRequest, SecurityHeader) throws QueryFault - or the generated call: QueryResponseType CompiereSoapImpl.query_(String tablename, String sqlwhere, Integer offset, Integer limit) throws QueryFault - or the one provided: List<Dto> CompiereClient.query(String tablename, String sqlwhere, int offset, int limit) The generated option (#2) just handles the security header and exposes all request parameters. The third option returns the actual result directly and handles any exceptions by just logging them and returning null as a result. If you expect an exception, you may want to use option 2. Copyright 2013 Consona Corporation All rights reserved Page 5

Note that the call can also throw the runtime exception, SOAPFaultException, (see restriction above), as well as a Throwable if there are communication or serialization issues. Note: When creating a new object, you may need to set (more) values explicitly than using the standard Java API. Also, the default values might be different than when using the Java API directly. Multiple Targets The target URL of the Java SOAP client is determined by the service location in the WSDL document. If you generate the client by providing the default URL, http://localhost:8888/ws/soap?wsdl, the client will connect to that URL. To enable that you can connect, for example, to development, test, and production servers without regenerating the client, WS-Addressing is used and you can provide the actual target URL when creating the CompiereClient. For example, new Compiere Client (http://prod.company.com/ws/soap). Note that the URL provided is the service point, where the WSDL is retrieved by adding?wsdl to the URL. If no argument is provided, then the service point at the time of the client generation is used. API Specifics Most data structures are directly mapped to the corresponding XML notation. Naming The entity names are converted to XML Standard by removing the underscores. For example, the table AD_Column is converted to ADColumn and the column AD_Column_ID is converted to ADColumnID. Data Transport (or Transfer) Object: The Compiere PO (Persistent Object) representation in the SOAP API is called by its proper technical term: Data Transport (or Transfer) Object. Primary Key The Primary Key is an integer value. All standard Compiere entities comply, but non-standard tables may have String values (that is, you can only use Compiere entities, who have an integer as the Primary Key). Copyright 2013 Consona Corporation All rights reserved Page 6

Foreign Key A Foreign Key extends the Primary Key and also has a label. When you query records, the label is populated, so that you don t need to query a referenced entity to get the name. When saving, the label is ignored. You can convert any Primary Key to a Foreign Key via the method.asfk() - example: column.setadtableid(table.getadtableid().asfk()); Pick Pick list values have an optional label. Like in Foreign Keys, the labels are populated when querying records and ignored when setting values. Pick lists are exposed as classes and their values exposed as static values. There are convenience methods for setting the pick values. Example: The Table AD_Table has the field TableTrxType, which is a pick list. The Pick List is represented in the class ADTableTableTrxType (concatenating table name and field name). The formal setting method is: table.settabletrxtype(new ADTableTableTrxType().withValue(ADTableTableTrxType.M)); This can also be written also as: table.settabletrxtype(new ADTableTableTrxType(ADTableTableTrxType.M)); table.settabletrxtype(adtabletabletrxtype.m); Processes All Compiere processes, which do not directly print (that is, reports) are exposed as SOAP operations. The value of the process is used with a process prefix. For example, C_Year_CreatePeriods is exposed as processcyearcreateperiods. If the process has parameters, the structure is dynamically generated. You call processes via: ProcessResponseType processcyearcreateperiods_(int recordid) throws ProcessFault from the Compiere Client. Copyright 2013 Consona Corporation All rights reserved Page 7

Workflow Any workflow can be started via: Dto CompiereClient.workflow(String docaction, Dto dto) For example: order = (COrder) m_client.workflow(docaction.complete, order); You pass the document action and the data transfer object (saved or updated) to the call and get the updated back. If the returned Dto is null, the workflow did not succeed. Alternatively you could also call: WorkflowResponseType workflow_(string docaction, Dto dto) throws WorkflowFault Security Authentication All SOAP transactions require that the client is authenticated. Therefore, you need to log in providing either username/password/role or API ID and secret. When successfully logged in, the client receives a SID, which needs to be transmitted in following SOAP transactions. The connections are stateless (unless you use SSL, see below), uses POST requests and do not use any cookies. With that, the risk of cross site request forgery (CRSF) is very unlikely. Transport Level Security If you want to secure the SOAP connection, the most effective solution is to use Transport Level Security (that is, https) - see also http://en.wikipedia.org/wiki/ws-security. Note that you need a validated SSL certificate on your server. If you have Apache as front end server, install the certificate there instead of installing it in the web container (for example, Tomcat). For Tomcat SSL configuration, click here. If you do not have a signed certificate, for example, for testing purposes, do the following: Server test certificate 1. Check/run the script ws/testssl.bat to create the certificate. For Tomcat, modify conf/server.xml to activate the SSL connector pointing to the certificate file created in step 1..: <Connector port="8443" protocol="http/1.1" SSLEnabled="true" maxthreads="150" scheme="https" secure="true" Copyright 2013 Consona Corporation All rights reserved Page 8

keystorefile="c:\compiere\trunkcore\ws\test.keystore" keystorepass="tomcat" clientauth="false" sslprotocol="tls" /> 2. Start Tomcat and check the log for errors. SOAP Client 2. Make sure the server is running. Point your client to the SSL port. For example, new CompiereClient(https://localhost:8443/ws/soap); (see IT_CompiereClient.testSSL) 3. You need to install the server certificate if it is not trusted. For example, if your browser does not appear, for example, e.g. https://localhost:8443/ws/soap without complaining. For that, use the program InstallCert.java in ws-sdk/scr/test/java: cd ws-sdk/target/test-classes java InstallCert localhost:8443 Accept the certificate Copy jssecacerts to %JAVA_HOME%/jre/lib/security. Run step 2 again to ensure that the certificate is installed. Setup In the Tenant (Maintain Clients/Tenants) window and the Tenant Info tab, you can enforce using SSL by client/tenant setting the flag Enforce Secure Web Services. By default, you can use username, password and role to use web services in addition to the API Access Key (see below). By setting the flag Require API Key, you can only connect to web services using API access credentials. In the Web Services API Key window, you select a User and Role to generate an API Access Key and Secret. You can regenerate the key/secret independent from changing the user name/password of the user. Note that for successful login, the referenced user and role need to be active. Now, you use the API Access Key as the user name and the API Access Secret as the password when connecting via the SOAP API. Examples Import Price List Reference an existing price list and/or version or create a new price list / version. Once set or created, you can add the prices for a given product via the following: addprice(product, pricelist, pricestd, pricelimit); Copyright 2013 Consona Corporation All rights reserved Page 9

Or you can import a file. It allows you to import a CSV file, Tab/etc. delimited or fixed with formats, you can define the header values (columns to be imported) or it can discover them. It also allows you to define column synonyms (for example, List for ListPrice ). The sequence of the columns in the file is arbitrary. They must contain the product and the limit price. Class: ws-sdk - org.compiere.sdk.app.importpricelist Test: org.compiere.sdk.app.it_importpricelist Copyright 2013 Consona Corporation All rights reserved Page 10