Web Services

Introduction

The two industry-standard Web Service types are Simple Object Access Protocol (SOAP) and Representational State Transfer (REST). Both are supported by Appway using the WebServices extension.

Usage

Web Services are generally used to integrate with a third-party application. This can be either as a host or a client. Currently, Appway only supports the latter. For example, in a corporate environment where numerous applications need to use customer information, it would be very difficult to maintain this information if each application were to keep its own copy. If a customer changes address, it would be necessary to make the amendments in multiple times. Using Web Services, a single application could be the owner of that data and all of the other applications request the information from that application through a web service interface, likewise for updating that data.

Fundamental Differences

SOAP is a formal specification/contract between two communicating parties that defines the structure of the data flowing back and forth in XML. SOAP Services are defined using a Web Service Definition Language (WSDL) file. In SOAP, a service exposes a series of operations/actions. Each of these operations may expect different data and the format of that data is specified in the WSDL or associated XSD files. The messages that flow back and forth contain an Envelope in which is kept the body of the message, the data expected by the operation or the response expected from the operation.

Figure 1: SOAP Service

REST, however, doesn't have any particular constraints on the data format. In that respect, it should be considered more as an architecture than a formalization. Generally speaking, the data structures used are either JSON or XML but could equally be any data format. The REST architecture is based upon the HTTP 1.1 specification which offers a series of methods for interrogating (GET), adding (PUT), updating (POST) and deleting (DELETE) records/data from a host as well as some additional utility methods.

Figure 2: REST Service

SOAP

SOAP Introduction

The SOAP extension allows you to call a web service based on the Simple Object Access Protocol (SOAP) through an Integration Link or a script.

An import wizard lets you import Data Classes and service definitions from a WSDL file. A service client is created as a Data Class (name ending in "CLIENT"). This service client contains the methods that can be used to call the corresponding service. A SOAP service can either be called through the Integration Link's "SOAP Client" component, or through a script.

The extension also contains a service testing tool and an exception browser for diagnosis and debugging.

Before reading this section, familiarize yourself with the SOAP standard (Wikipedia article on SOAP) and the WS-I Basic Profile v1.1.

To install SOAP, follow the product documentation on installing regular Appway extensions. Once started, the extension adds the following functionality to the Appway Platform:

• Import wizard to handle import tasks
• "SOAP Client" Integration Link component to call services from Integration Links
• Data Classes representing the base service client and SOAP elements:
  • ServiceClient – Base Data Class for all service clients created when importing a WSDL file.
  • Fault – Base Data Class for the SOAP "Fault" element.
  • SOAP11_Fault – SOAP "Fault" element for SOAP version 1.1 services; extends the "Fault" Data Class.
  • SOAP12_Fault – SOAP "Fault" element for SOAP version 1.2 services, extends the "Fault" Data Class.
  • SOAPHeaderElement – Allows the definition of SOAP headers, for example for cookie handling.
• Set of functions to execute, test and debug service calls:
  • SOAPCall() – Used by the service client Data Class to execute a SOAP call. Do not use this function directly. Instead, use the service client methods to invoke a service method.

• SOAPConvertToDataEntity() – Converts the body of a SOAP response into a data entity; useful for testing.
• SOAPConvertToXML() – Converts a data entity to XML using the mappings defined by the Data Class created by a service; useful for testing.
• SOAPGetMessage() – Method to create and retrieve a message as would be created using SOAPCall().
• SOAPThrowBusinessException() – Throws a com.nm.extensions.webservices.soap.BusinessException; useful for exception handling in Integration Links and Processes.
• XSDToDataClass() – Imports an XML Schema Definition (XSD) and creates Data Classes based on that XSD; useful for debugging.
• Service test tool for script-based testing of imported services
• Exception browser listing the last exception to occur during each service function call within the last 30 minutes.

Supported XML Concepts

Namespaces

The SOAP extension uses and creates namespace-aware XML documents. For namespace handling, it uses namespace prefixes which are prepended to the ID of the Data Classes generated.

It is up to the user to define the proper namespace prefixes in case a service is re-imported.

Schema Import and Schema Include

The WSDL importer allows you to import service descriptions referencing the XML schemas used in the service with xsd:import or xsd:include.

The schemaLocation property is mandatory for custom schema references. These must, however, be included in the types section of the WSDL. Recursive import and include are supported.

 <xsd:import namespace="myURI" schemaLocation="/my/loation/myschema.xsd" > 

Code 1: Example import

Complex Type and Element

A top-level complex type definition or a top-level element definition with an embedded anonymous complex type triggers the creation of a Data Class with the corresponding name.

<xs:complexType name="ClientRelationship">
    <xs:sequence>
        <xs:element name="team" type="Team" minOccurs="0" maxOccurs="1"/>
        <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <xs:element name="client" type="Client" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
</xs:complexType>

<!-- equivalent definition -->
<xs:element name="ClientRelationship">
<xs:complexType>
        <xs:sequence>
            <xs:element name="team" type="Team" minOccurs="0" maxOccurs="1"/>
            <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
            <xs:element name="client" type="Client" minOccurs="1" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

    <!-- equivalent definition -->
    <xs:element name="ClientRelationship" type="ClientRelationship"/>
<xs:complexType name="ClientRelationship">
    <xs:sequence>
        <xs:element name="team" type="Team" minOccurs="0" maxOccurs="1"/>
        <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <xs:element name="client" type="Client" minOccurs="1" maxOccurs="unbounded"/>
    </xs:sequence>
</xs:complexType>

Code 2: XML type definition

The definitions above trigger the creation of a Data Class called "ClientRelationship":

Class ClientRelationship Begin
    Property['team', Team, 'none'];
    Property['name', String, 'none'];
    Property['client', Client, 'indexed'];
End

Code 3: Data Class definition

Nested / Anonymous Complex Type

A nested / anonymous complex type triggers the creation of a new Data Class whenever a definition of that style is found. The name of the new "anonymous" class is derived from the property name.

<xs:complexType name="ClientRelationship">
    <xs:sequence>
    <xs:element name="team" type="Team" minOccurs="0" maxOccurs="1"/>
    <xs:element name="name" type="xs:string" minOccurs="1" maxOccurs="1"/>
        <xs:element name="client" minOccurs="1" maxOccurs="unbounded">
            <xs:complexType>
            ...
            </xs:complexType>
        </xs:element>
    </xs:sequence>
</xs:complexType>

Code 4 : XML nested anonymous complex type definition

Class ClientRelationship Begin
    Property['team', Team, 'none'];
    Property['name', String, 'none'];
    Property['client', ClientRelationship_Client, 'indexed'];
End

Code 5: Data Class anonymous complex type definition

Extensions

Using xsd:extension triggers the creation of a Data Class extending the related base type.

<xsd:complexType name="AddressValidationRequest">
    <xsd:complexContent>
        <xsd:extension base="awPostal:ServiceRequest">
            <xsd:sequence>
                <xsd:element name="clientPostalAddress" type="awCore:ClientPostalAddress" minOccurs="0" maxOccurs="1"/>
            </xsd:sequence>
        </xsd:extension>
    </xsd:complexContent>
</xsd:complexType>

Code 6: XML extended type definition

Class AddressValidationRequest extends ServiceRequest Begin
...
End

Code 7: Data Class extending a base type

Simple Type

Simple type definitions generate new primitive types which extend the corresponding base type translated to a Data Class name.

<xsd:simpleType name="guid">
    <xsd:restriction base="xs:string">
        <xsd:pattern value="[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}"/>
    </xsd:restriction>
</xsd:simpleType>

Code 8: Simple type definition

Type guid extends String Begin
  JavaType java.lang.String;
End

Code 9: Primitive Type definition

Note: Patterns or enumerations defined in the XSD simple type are not enforced or checked by the SOAP extension.

anyType

The anyType is also supported to allow for runtime defined types to be supplied as the value for an element. Below are examples of both the schema definition for this and the XML that is represents.

<s:complexType name="quotes">
 <s:sequence>
   <s:element minOccurs="0" maxOccurs="1" name="client" type="s:anyType"/>
 </s:sequence>
</s:complexType>

<s:quotes>
  <s:client xsi:type="xsi:physicalPerson">
    <s:firstName>John</s:firstName>
  </s:client>
</s:quotes>

Nillable

Nillable elements are frequently used in XML lists either to create NIL placeholder elements if the index of an element in a list is important, or to emphasize that a value has been set to NIL.

<xs:element name="Folder">
    <xs:complexType>
        <xs:sequence>
            <xs:element name="file" nillable="true" type="xs:string" minOccurs="0" maxOccurs="unbounded"/>
        </xs:sequence>
    </xs:complexType>
</xs:element>

Code 12: Schema defining a nillable element

There is no special handling for nillable in the class definition. When creating a document, however, the nillable element will result in a tag with the attribute xsi:nil if the corresponding data entity property is NULL.

Class Folder Begin
        Property['file',String','indexed'];
    End

    Folder $f:=new Folder;
    $f.file:=['a',null,'b']:String

Code 13: Example data class definition

// xml output for $f
<Folder>
    <file>a</file>
    <file xsi:nil="true"/>
    <file>b</file>
</Folder>

Code 14: Example nillable output

Note: An empty collection does not trigger any tag creation.

Attributes

Complex Types with xs:attribute definitions trigger the creation of Data Class properties for each attribute.

<xs:complexType name="Message">
    <xs:sequence>
        <xs:element name="listOfAccounts" type="aw:ListOfAccounts" minOccurs="0"  maxOccurs="1"/>
    </xs:sequence>
    <xs:attribute type="xs:string" name="MessageId"/>
    <xs:attribute type="xs:string" name="MessageType"/>
    <xs:attribute type="xs:string" name="IntObjectName"/>
    <xs:attribute type="xs:string" name="IntObjectFormat"/>
</xs:complexType>

Code 15: Example Complex Type with attribute definitions

Class Message Begin
    Property['listOfAccounts', ListOfAccounts, 'none'];
    Property['MessageId', String, 'none'];
    Property['MessageType', String, 'none'];
    Property['IntObjectName', String, 'none'];
    Property['IntObjectFormat', String, 'none'];
End

Code 16: Data class properties for the complex type

Extension Configuration

In the Extensions menu, right-click on the SOAP extension to open its configuration dialog. The following properties can be configured:

New SOAP extension versions maintain compatibility with previous imported services by adding the version used for the import in the service client definition.

For more information on versioning, see the SOAP Version Compatibility section.

If the SOAP extension version cannot be found in the service client, then Appway will look for the property soapExtension.clientVersion in the following configurations:

• Service Client ENV property
• Workflow instance attribute
• Appway configuration property
• Extension configuration property.

Importing a SOAP Service Definition

The WSDL Import Wizard allows you to import a new service definition or overwrite an existing one.

The wizard can be accessed under Data & Integration > Integration > SOAP and clicking on the menu and selecting Import WSDL. It will guide you through the following steps:

• Import a WDSL file
• Set any optional settings
• Upload any required XSD files
• Select a service and the corresponding port
• Define namespace aliases
• Define connection and read timeouts
• Import Data Classes and create a service client

Import Service Definition

WSDL files contain service definitions as well as the definitions of the XML structures used by each service. XML structures may be referenced using xsd:import or xsd:include statements. The Import Wizard analyzes the WSDL and asks for any missing files.

Upload or Download a WDSL file

To start importing a service definition:

1. Data & Integration > Integration > SOAP. Click on the Import WSDL button (a wizard opens).

2. Set the import options:

   

   Figure 4: Import Options

3. Set the optional settings:

   

   Figure 5: Optional Settings

|

Import Referenced XSDs

After choosing a WDSL file, the Upload Schemas dialog allows you to upload any missing imported or included XML schema.

1. If any schema files are missing, upload them or enter a URL where they can be found.
2. Click Upload missing XSD to load the selected schema files.
3. Once all schema files are loaded, the service can be imported. Click Next.

Figure 6: Missing Referenced XSDs

Figure 7: Complete Referenced XSDs

Select Service and Port

While a WSDL may contain many different service definitions, the WebServices extension allows you to import one service at a time. One service may have many service methods, which will all be imported.

1. Select one of the services defined in the WSDL file to be imported.

   

   Figure 8: Select Service

2. Click Next.

3. Choose the SOAP port to be used.

   

   Figure 9: Choose Port

4. Click Next.

Set Target Package

All the Data Classes imported for the SOAP Web Service can be placed in a Package. The target Package always includes the service client Data Class, while there is a further step where Data Classes from different namespaces can be assigned to alternative packages. The target Package can be the Base Package.

1. Select the Package Name input field to provide focus (a scrollable list of all the available Packages is shown).

2. Select a Package from the dropdown or start typing the Package name to filter the list.

3. Click Next.

Set Connection and Read Timeouts

Connection timeouts and read timeouts can be specified for each individual method, if the value is set to 0 then the value used will either be that set at the extension level as previously described or if they are not specified there, the extensions will use its default values which are 5000ms for connection timeout and 10000 for read timeout.

Figure 10: Connection and Read Timouts

Define Namespace Prefixes and Packages

A unique prefix per XML namespace must be defined. This prefix will be used for all Data Classes that have been imported from the same namespace.

1. Define a prefix for each XML namespace. Each namespace will be assigned by default to the target Package defined two steps before.
2. Optionally, specify a different Package per namespace (a scrollable dropdown appears when the input is in focus).
3. Once namespace prefixes are defined, click Next.

Figure 11: Define Namespace Prefixes

Define Visibility Conditions

Whenever the 'namespace to Package' mapping provided in the previous step points to the target Package, this step allows to define the Package-level visibility of the imported Data Classes. However, if a different Package is selected in the mapping or the Base Package is selected, then the visibility condition is set to visible by default and the step is skipped.

Note: Changing the 'namespace to Package' mapping or setting the target Package to the Base Package results in disabling this step.

1. Select the radio button corresponding to the desired visibility level for the Data Classes (All Visible or All Hidden)

2. Click Next to confirm the choice.

Review

The Review dialog gives a preview of the classes that will be imported as Data Classes. The namespaces and the timeouts for the different service methods.
The first row listed is the service client Data Class. The following rows are the Data Classes that have been defined according to the WSDL file's type definition section.

1. Click Import to update the repository with the new Data Class definitions.
2. Click Previous prior to clicking Import to make changes to any of the choices made previously during the import.

Figure 12: Example Defined Classes

Calling a SOAP Service

There are two ways to call a SOAP service: through an Integration Link (SOAP Client component), or through a Script.

Integration Link Service Call

1. Drag the SOAP Client component into the Integration Link's composition area.

2. Configure the component by choosing the service you wish to call and selecting one of its methods.

   

Figure 13: Choosing service and method

3. If the service method requires parameters, a new tab appears, allowing you to define the method's arguments.

   

Figure 14: Setting service call parameters

4. The Settings tab allows you to define the fine-grained behavior of the SOAP extension.

   

Figure 15: Configuring the SOAP client

Table 10: SOAP Client Settings

5. The Headers tab lets you define any SOAP envelope headers you wish to add to SOAP messages as an Indexed Collection of SoapHeaderElements.

   

Figure 16: Adding SOAP headers

6. Finally, the Authentication tab lets you define Username and Password to be used for authentication purposes.

   

Scripted Service Call

When importing a service, a service client Data Class is created (name ending in "CLIENT"). Instantiate this Data Class and use its methods to call the corresponding service methods.

Consider a "Global Weather" service as an example being created in the Base Package. This service defines the method "GetCitiesByCountry" which takes a country name as parameter and returns the cities found for the given country. A script to call this service method would look like this:

String $serviceURL := '...URL to Global Weather service...';
String $countryName := null;
//
// Instantiate the service client Data Class
//
GW_GlobalWeatherCLIENT $gW_GlobalWeatherCLIENT := NewObject(GW_GlobalWeatherCLIENT, $serviceURL);
//
// Call the GetCitiesByCountry method
//
GW_GetCitiesByCountryResponse $ret := $gW_GlobalWeatherCLIENT.GetCitiesByCountry($countryName);

Code 21: Example scripted service call

Use the service client instance properties below to define additional settings for the service call.

SOAP Version Compatibility

Web service compatibility with SOAP standards is constantly improving. Sometimes, interface-breaking changes may be necessary to support new features.

The SOAP extension addresses this issue by versioning the XML translators and WSDL/XSD class import objects.

This extension-internal versioning mechanism makes sure that services which have been imported with a specific SOAP version will be allowed to run with the exact same version even after a new release of the SOAP extension has been uploaded.

Service Client Compatibility

The service client is marked with the extension version valid at the time of the client's creation.
For example, have a look at the GetQuote method below. The $env map contains a new key called 'clientVersion' pointing at the extension version which was used for creating the service client Data Class.

Function GetQuote() : qod.GetQuoteResponse Begin
    qod.GetQuote $qod_GetQuote := NewObject(qod.GetQuote);
    Named Any $env := {
    ...
    'clientVersion'='1.11.1', 
    ...
    }:Any;
    Any $retValue := SOAPCall($this, $env, $qod_GetQuote, false);
    Return CAST(qod.GetQuoteResponse, $retValue);
End

Code 22 : Example use of extension version

Resolving Versions

When executing a SOAP call, the version for XML translators is resolved based on the following priorities:

1. SOAP call environment map key clientVersion, if defined in the client method
2. Workflow instance attribute soapExtension.clientVersion, if available
3. Appway configuration soapExtension.clientVersion, if available
4. Extension configuration soapExtension.clientVersion, if available
5. Default (newest available version)

SOAP Service Administration and Diagnosis

The Service Client Overview displays detailed information about each SOAP service. To access the list of Service Clients, go to the administration section of the studio and select Data & Integration > Integration > SOAP.

Select one of the imported services, details are displayed in three tabs.

The General tab contains general information about the service:

Table 13: General Service Settings

The Methods tab displays an overview of the methods available for a specific service:

Column	Description
Methods	Name of methods delivered by the service
Test Button	Click to open up a test script for executing calls to the service (see section 7.1 for more on testing)
Connection Timeout	Defines the timeout in milliseconds when connecting to the server. This property can also be defined as a general Appway configuration, in which case it overrides the extension configuration. These values can also be defined at method level for each service when imported or subsequently through the administration UI. Default: 5000
Read Timeout	Defines the timeout in milliseconds when waiting for a response after connecting to the server. This property can also be defined as a general Appway configuration, in which case it overrides the extension configuration. These values can also be defined at method level for each service when imported or subsequently through the administration UI. Default: 10000

Table 14: Service Methods

The Classes tab gives an overview of all Data Classes imported for a specific service:

Service Call Testing

1. Go to the Studio and select Data & Integration > Integration > SOAP and click on the name of the service you want to test in the list.
2. On the Methods tab, click Test next to the service method you wish to test. The Interactive Script Editor opens up, automatically pre-filled with a test script.
3. Insert the required service method parameters. Initially, they are set to NULL.
4. Run the script to execute the service method call. A report containing the SOAP request and response is created and appears in the Interactive Script Editor's output area.

Figure 21: Expression Editor

If we modify the code, we can retrieve the Request and Response messages and output their content to the result to see exactly what was sent and received by the service call.

PRINTLN('SOAP Request: \n');
String $serviceURL := 'http://wsf.cdyne.com/WeatherWS/Weather.asmx';
Tns_WeatherCLIENT $tns_WeatherCLIENT := NewObject(Tns_WeatherCLIENT, $serviceURL);
Tns_GetWeatherInformationResponse $ret := $tns_WeatherCLIENT.GetWeatherInformation();
com.nm.sdk.utils.SerializableWrapper $content := CAST('com.nm.sdk.utils.SerializableWrapper', $tns_WeatherCLIENT.collaterals['requestMessage']);
javax.xml.soap.SOAPMessage $msg := CAST('javax.xml.soap.SOAPMessage', $content.getObject());
javax.xml.soap.MimeHeaders $headers := $msg.getMimeHeaders();
javax.xml.soap.MimeHeader $header;
java.util.Iterator $i := $headers.getAllHeaders();
PRINTLN('MimeHeaders:\n');
While $i.hasNext() Do 
javax.xml.soap.MimeHeader $mh := CAST('javax.xml.soap.MimeHeader', $i.next());
PRINTLN($mh.getName() & ':' & $mh.getValue());
End
If $msg.getSOAPPart() != null Then 
PRINTLN('\nSOAP Part: \n');
PRINTLN(PrintXmlDocument($msg.getSOAPPart().getDocumentElement(), false));
End
PRINTLN('\n\n====================================================================================\n\n');
PRINTLN('\nSOAP Response: ');
$content := CAST('com.nm.sdk.utils.SerializableWrapper', $tns_WeatherCLIENT.collaterals['responseMessage']);
$msg := CAST('javax.xml.soap.SOAPMessage', $content.getObject());
$headers := $msg.getMimeHeaders();
$i := $headers.getAllHeaders();
PRINTLN('MimeHeaders:\n');
While $i.hasNext() Do 
javax.xml.soap.MimeHeader $mh := CAST('javax.xml.soap.MimeHeader', $i.next());
PRINTLN($mh.getName() & ':' & $mh.getValue());
End
If $msg.getSOAPPart() != null Then 
PRINTLN('\nSOAP Part: \n');
PRINTLN(PrintXmlDocument($msg.getSOAPPart().getDocumentElement(), false));
End
PRINTLN('');

Code 23: Example service call test

Here, the content of the result window shows the headers and the SOAP Message used for the request.

Figure 22: Service Test Example

Runtime Exceptions

The last occurrence of any runtime exception occurring while executing the service call is logged per invoked method in the SOAP extension's Exception Browser.

Click on one of the exceptions to inspect more details. The detailed view contains information such as exception time, user, service, service method, stack trace, etc.

Figure 23: Exception Details

MTOM support - SOAP Attachments

The Appway WebServices extension supports the W3C SOAP Message Transmission Optimization Mechanism (MTOM) standard as defined in the following specifications:
http://www.w3.org/TR/soap12-mtom/http://www.w3.org/TR/SOAP-attachmentshttp://www.w3.org/Submission/WS-MTOMPolicy/http://www.w3.org/TR/2005/REC-xop10-20050125/)

In a typical WSDL definition supporting MTOM, there are two key elements within the service definition:

• MTOM policy
• Policy reference

An MTOM policy is a SOAP policy that contains an OptimizedMimeSerialization element. The element specifies that the service may support MTOM for some of its operations. An example of an MTOM Policy is shown below:

<wsp:Policy wsu:Id="SOAPAttachmentServicePortBinding_MTOM_Policy">
  <ns1:OptimizedMimeSerialization xmlns:ns1="http://schemas.xmlsoap.org/ws/2004/09/policy/optimizedmimeserialization">
</ns1:OptimizedMimeSerialization>
</wsp:Policy>

An operation that supports MTOM needs to specify a policy reference within the binding definitions to enable MTOM for all its operations. For instance, the following binding defines two operations that support MTOM:

<binding name="SOAPAttachmentServicePortBinding" type="tns:AppwayAttachmentsWebService">
  <wsp:PolicyReference URI="#SOAPAttachmentServicePortBinding_MTOM_Policy"></wsp:PolicyReference>
  <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document"></soap:binding>
  <operation name="operation1">
  </operation>
  <operation name="operation2">
  </operation>
</binding>

In the import wizard, Appway will automatically replace all the xs:base64Binary elements with SOAPAttachment primitive type.
SOAPAttachment is a new primitive type that is made available by the extension which represents a single SOAP binary attachment. The SOAPAttachment type provides the following methods:

• setPath: sets the path of the file to be used as attachment for the SOAP request.
• getContentBase64: returns the content of the attachment encoded with Base64.
• getContent: returns the content of the attachment with the default system charset.
• writeContentToPath: writes the content of the attachment (the binary data in it) to the specified file path.

WS-I Basic Profile v1.1 Support

The below sections specify how the WebServices extension supports the WS-I Basic Profile v1.1. See here for general information on the Basic Profile.

Supported Binding Styles

The WebServices extension supports the following WS-I Basic Profile 1.1 complaint binding styles:

• Document/literal/wrapped

Other binding styles are not supported:

• Document/literal
• RPC/literal

XML Schema - Supported Elements and Restrictions

See the following tables for an overview of XSD elements and restrictions and if the WebServices extension supports them: XSD Elements

XSD Restrictions/Facets for Datatypes

For more information on XSD elements and restrictions, see here.

Note: Not supported XSD restrictions are ignored by the WebServices extension. The only restriction which is enforced is minOccurs, but only if the extension configuration property "mandatory.elements.enforce” is set to true (default: false).

REST

REST Introduction

The Representational State Transfer (REST) extension allows the Appway Platform to communicate with RESTful web services in JSON or XML format. It is an architecture definition allowing two systems to communicate in an agreed data format and structure over HTTP.

For the original description of the REST architecture, see Hypertext Transfer Protocol -- HTTP/1.1 by the Internet Society (1999). Learn more about REST APIs via the tutorial Using HTTP Methods for RESTful Services by RestApiTutorial.com.

The REST extension allows you to convert a Data Class into XML or JSON data and vice versa, and to send or receive this data through HTTP requests.

For example, to display tweets posted by the company CEO in the Workspace, you can integrate Appway with Twitter through a REST interface. As depicted in the diagram below, Appway sends a request which is translated into JSON or XML format. Twitter receives the request and sends a corresponding response, again either in JSON or XML format. That response is finally translated back into an Appway Data Class instance.

Figure 24: Diagram "Sending and receiving REST messages"

• RestClient Integration Link component: can be set to re-use the same service configuration in multiple Processes. Contains properties to set the data interchange format, translate to and from Data Classes, and call HTTP request methods.
• RestClient Primitive Type: for scripted integration, it is configured for a particular service within a Process. Contains functions to set the data interchange format, translate to and from Data Classes, and call HTTP request methods.
• Mutual Authentication extension (installed as part of the REST extension package): contains an SSL Trust Manager and SSL Key Manager to handle the handshake between the client and the server and verify that a trust relationship can be negotiated.

Connection Configuration

REST communication with an external service can take place over normal HTTP or over HTTPS / SSL. Use SSL if a secure connection is required and the remote service supports this protocol.

Keys and certificates for an SSL connection can be added through the Mutual Authentication extension (included in the REST extension package). If you intend to use SSL for connecting to a service with server authentication, add a certificate for the Certificate authority that created the server's certificate, or any certificate in the chain, including the server certificate to your "Trust Store". If you intend to connect to a client authenticating service, a key is required in addition to the certificate. Add your key to the "Key Store" and associate this key with the given host in the extensions configuration. See the Mutual Authentication Extension documentation for more on configuring secure connections.

Supported HTTP Methods

The REST extension supports the HTTP request methods GET, POST, POSTXFORM, PUT, PATCH, DELETE, HEAD and OPTIONS. TRACE is not supported.

HTTP methods can be called through the "Rest Client" Integration Link component or the "RestClient" Primitive Type (see Chapters 5 and 6 below).

Jersey or Apache CXF services provide a WADL file which defines all of the operations available for a given service. This can be useful when defining your REST service client because it contains all the settings you require.

An example URL for Apache CXF where you can retrieve a WADL file is http://dev.numcom.local/myapp?_wadl.

Data Interchange Format

A REST service defines its own interface and, in particular, which data interchange format it requires. If multiple formats are supported, the client can choose one of them, or list its preferences and get the first available match.

JSON

JavaScript Object Notation (JSON) is a data interchange text format based on a subset of the JavaScript Programming Language. It is built on two structures:

• Collection of name/value pairs, realized as Data Class in Appway
• Ordered list of values, realized as Indexed collection in Appway

For example, this is the JSON equivalent of a Data Class instance with three properties including an Indexed collection:

{
    'id': '1234',
    'name': 'Mister Fantastic',
    'contacts': ['Invisible Woman', 'The Human Torch', 'The Thing']
}

Code 26: JSON object example

When using JSON as your inbound or outbound format in Services you create using the wizard, data class instances will be converted automatically to JSON for you and the JSON is automatically converted into data class instances, respectively.

In the script language, you can use the TranslateTo() and TranslateFrom() methods to convert Appway data class instances both to and from JSON. This is explained later in this section.

Figure 25: Corresponding Data Class

Read more about JSON at json.org.

XML

Extensible Markup Language (XML) is a flexible text format derived from SGML. It is a markup construct consisting of a name/value pair which exists within a start-tag or empty-element tag.

For example, this is the XML equivalent of a Data Class instance with three properties, including an Indexed collection:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE person SYSTEM "http://types.yourcompany.com/dtd/person.xsd">
<person>
    <id>1234</id>
    <name>Mister Fantastic</name>
    <contacts>Invisible Woman, The Human Torch, The Thing</contacts>
</person>

Code 27: XML object example

Figure 26: Corresponding Data Class

Read more about XML at www.w3.org.

XMLAttributes

If, in your XML elements, some of the DataClass properties should be represented as attributes of the tag, this can be achieved by editing the metadata of the data class. For example, to specify that the ID should be an attribute of the person tag, you would add an entry in the metadata like this:

If the format being used is XML or JSON, then for outgoing data, the data class instances will be automatically converted into their equivalent XML structures through calls to the function TranslateTo(). Incoming data will be converted into data class instances from the equivalent XML structures through calls to the function TranslateFrom().

BINARY

Binary data is sent and received as an ISO8859-1 encoded String which allows a binary file to be stored as a series of bytes. The conversion into this format is not handled automatically and must be handled by the Appway developer.

RAW

If RAW is chosen as the inbound or outbound format, then whatever you pass to the service call or receive will be assumed to be a String and will be written onto the output stream or read from the input stream. How that is subsequently handled is up to the Appway developer.

RAW_JSON

If RAW_JSON is the outbound format, then the content type is automatically set to be JSON and the value passed is written directly to the output stream.

RAW_XML

If RAW_XML is the outbound format, then the content type is automatically set to be XML and the value passed is written directly to the output stream.

Translating to and from JSON/XML

The TranslateTo() function lets you convert Appway data structures into the required format before sending a request to the remote service. You can use it in the Payload field of the Rest Client Integration Link component or directly in a scripted call.

To convert a response back into a Data Class, use the Response Class field in the Rest Client component. For a scripted call, use the TranslateFrom() function.

TranslateTo()

The function TranslateTo() converts a Data Class or Primitive Type into a String in the format required by the REST service (JSON or XML).

TranslateTo($entity, $format, $patterns)

For more information on setting patterns, see the section Adding Patterns.

Example in a scripted integration:

String $payload := TranslateTo($person, 'json')

String $payload := TranslateTo($person, 'xml')

Example in a "Rest Client" Integration Link component:

Figure 27 : REST Client Integration Link

TranslateFrom()

The TranslateFrom() function converts the body of a JSON or XML response into an Appway entity. It returns a constructed and populated instance of the Data Class or Primitive Type specified.

TranslateFrom($responseBody, $dataclassId, $format, $patterns)

For more information on setting patterns, see the section Adding Patterns.

Examples for TranslateFrom():

MyPackage:Person $person := TranslateFrom($return, 'MyPackage:Person', 'json')

TranslateFrom($client.httpGet('people', null), 'Indexed MyPackage:Person', 'json')

String $returnVal := $client.httpGet('people/person', 'id=1');
MyPackage:Person $p := TranslateFrom($returnVal, 'MyPackage:Person', 'json');

Example Pattern Usage – JSON

For JSON, use the patterns for handling null values in the $patterns parameter as follows:

Named String $patterns := NewNamed(String);
$patterns['number'] := 'Nullable:true';
TranslateFrom('[null, 123]', Indexed Integer, 'json', $patterns);

This returns an Indexed of Integer with values 'null' and '123'. Without the pattern, the default behavior is:

TranslateFrom('[null, 123]', Indexed Integer, 'json')

This returns an Indexed of Integer with values '0' and '123'.

The default value for Boolean values is 'false', for floating numbers it is '0.0'.

Example Pattern Usage – XML

Usage of the patterns for handling null values for XML in the $patterns parameter is similar to their usage for JSON.

For the sake of this example, let's assume we have a Data Class called 'TestDataClass' with the fields 'str', 'int', 'double' and 'bool' of the types String, Integer, Double, and Boolean respectively.

Use the new patterns as follows:

String $xml := '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<TestDataClass xmlns="http://appway.com.com/hr">
<str></str>
<int></int>
<double></double>
<bool></bool>
</TestDataClass>';
Named String $patterns := NewNamed(String);
$patterns['number'] := 'Nullable:true';
$patterns['boolean'] := 'Nullable:true,true:1|yes|true,false:0|no|false';
TranslateFrom('[null, 123]', TestDataClass, 'xml', $patterns); 

This returns the Data Class:

TestDataClass{bool=null, double=null, int=null, str=} 

Note: 'str' becomes an empty string, not null.

The same XML, without the new patterns, returns the Data Class:

TestDataClass{bool=true, double=0.0, int=0, str=}

The default value for Boolean values is 'true' and not 'false' as it is for JSON. For floating numbers, it is the same as for JSON: '0.0'.

REST UI

Creating a Service

To create a preconfigured REST Service Client, go to the Data & Integration section of the Studio and select the menu item REST under the heading Integration. Click on the Add Service menu item.

After clicking on Add Service, you will be presented with a dialog where you should specify the necessary parameters to define a REST Client.

Figure 29: Defining the REST Service's properties

Table 26: Add REST Service parameters

Adding Headers

You can add headers that will be applied to all method calls on the service here. These headers could be cookies or any HTTP header, although the mime type headers are normally specified during the creation of methods and stored in the method definition.

Figure 30: Adding headers global to all service methods

The headers can be overwritten by adding an additional header with the same key.

Adding Methods

Figure 31: Creating a service method

Adding Parameters

When adding parameters to methods it is useful to always specify a description so that other developers can later understand the intention of the parameter and also because this value is also visible as a tool tip, as you will see later in the section on integration links, which can be seen when clicking on the question mark next to a method parameter.

Figure 32: Adding a parameter definition to a service method

Adding Headers

Headers defined in the method dialog will override header definitions on the service level. The generated REST method allows providing dynamic headers that will be merged with the default ones provided in the Add Method dialog. Dynamic headers override the default ones, in case the key names overlap.

Figure 33: Adding a header definition to a service method

Adding Patterns

Inbound and outbound patterns are provided to the TranslateFrom and TranslateTo Script functions, as described in the respective sections on these functions.

Figure 33b: Adding a header definition to a service method

Editing Existing Methods

You can edit methods from the method tab of the chosen service. Simply click on the pencil button to the right of the method name as in figure 32.

You could also right click and use the context menu as in figure 33.

The interface for editing a method definition, its parameters and its headers is identical to the one you used to create the method as you can see in figure 34.

Integration Link REST Calls

The Rest Client Integration Link component lets you configure a REST call, including the data interchange format and translation to and from Appway data structures. You can then reuse this specific interface to a REST service in processes using the Integration Link Task or via script by using the CallIntegrationLink function

Figure 37: Using the REST Client integration link component

Figure 38: Setting the parameters for the service call

Figure 39: Context aware help from the definition of the service method parameters

Figure 40: Headers tab for assigning a dynamic header to be used in the request of the REST method

For a more fine-grained control over REST calls executed from an Integration Link, there is a version of the Rest Client Integration Link component named RAW Rest Client.

The details of this component are given below:

The following options are available on the General Tab:

The following options are available on the Authentication Tab:

The following options are available on the Proxy Tab:

REST Response Headers

The Rest Client and the deprecated RAW Rest Client Integration Link components set the REST response headers returned by the REST service call into Exchange Message headers. To retrieve them, use the Exchange Message header 'restClientResponseHeaders'. To retrieve the REST response headers, the following code could be used from the exchange object returned by an Integration Link using the Rest Client component:

$exchange.getIn().getHeader('restClientResponseHeaders')

The value returned is a Named String collection and it contains all the headers returned by the REST call.

Scripted REST Calls

To set up a REST service interface with a script, use the RestClient Primitive Type. Instantiate it and configure it for a particular service before calling an HTTP method. An instance can be stored in a Process variable and then reused throughout that Process.

Each new instance of the RestClient object requires a base URL as parameter, from which relative URLs can be calculated.

RestClient $restClient := NewObject(RestClient, 'http://localhost:8080/myapp/')

Note that the "/" trailing on the base URL is mandatory. Use the NewObject() function as opposed to the "new" keyword, since a parameter must be passed to the constructor for the RestClient object.

Format

Set the data interchange format for communication with the remote service. For more information, see Data Interchange Format.

Use either of the following methods on the RestClient instance:

• If the format is JSON: .setJSONFormat()
• If the format is XML: .setXMLFormat()

Both methods take no parameters and return nothing. For example:

$restClient.setJSONFormat()

or

$restClient.setXMLFormat()

HTTP Requests

The set of methods in this section allow you to send an HTTP request to the service configured. See Supported HTTP Methods for an overview.

To convert a value to and from JSON or XML use the functions TranslateTo() and TranslateFrom() as described in Translating to and from JSON/XML.

GET

The RestClient method .httpGet() retrieves data from the specified URL with the criteria specified in the query string or given a DataMap (Named Collection) of parameter name value pairs.

$restClient.httpGet($url, $queryString)

Example: Request data corresponding to an instance of the Data Class "Person" with the id "1".

String $returnVal := $restClient.httpGet('people/person', 'id=1');
Person $p := TranslateFrom($returnVal, 'Person', 'json');

Alternative form of GET

$restClient.httpGet($url, $datamap)

Example: Request data corresponding to an instance of the Data Class "Person" with the id "1". The id parameter will be substituted in the URL. The name parameter will be sent as a part of the request formatted as a JSON structure.

Named String $datamap := {'id'='1', name=''Pluto'}:String
String $returnVal := $restClient.httpGet('people/person/{id}', $datamap);
Person $p := TranslateFrom($returnVal, 'Person', 'json');

POST

The RestClient method .httpPost() modifies data in the target entry given the specified URL, conditions in the query string, and the content to be updated.

$restClient.httpPost($url, $query, $content)

Example:

$restClient.httpPost('people', '', $payload)

Alternative form of POST

$restClient.httpPost($url, $datamap, $content)

Example:

$restClient.httpPost('people/person/{id}', $datamap, $content)

POST BINARY

The RestClient method .httpPostBinary() performs an HTTP POST and stores the binary result in a file.

$restClient.httpPostBinary($url, $query, $content, $path)`

HTTP POST OCTET-STREAM

The RestClient methods .httpPostOctetStream() perform an HTTP POST with an octect-stream message as payload.

$restClient.httpPostOctetStream($url, $query, $content, $path)

MULTIPARTPOST

The four RestClient methods .httpMultipartPost()perform an HTTP POST with a multipart message as the payload.

$restClient.httpMultipartPost(String,Named String,Named Any)

$restClient.httpMultipartPost(String,Named String,Named Any,Named String)

$restClient.httpMultipartPost(String,String,Named Any)

$restClient.httpMultipartPost(String,String,Named Any,Named String)

PATCH

The PATCH method can be used to only update selected parts of specific data.

Assume you have a structure containing 30 properties. Using the PATCH method, you can create a structure that only contains the properties that have been changed, thus reducing the data sent to the service.

Please note that many REST services do not implement the PATCH feature since it is very difficult to implement on the client side (requires the client to keep track of changes) and on the service side (requires the service to implement partial update capabilities).

The PATCH method uses the same parameter and calling methods, including alternative URL parameters, as the POST method.

XForm

The RestClient method .httpPostWithXForm() modifies XForm-encoded data in the target entry given the specified URL, conditions in the query string, and the content to be updated.

$restClient.httpPostWithXForm($url, $query, $content)

Alternative form of XForm

$restClient.httpPostWithXForm($url, $datamap, $content)

PUT

The RestClient method .httpPut() adds an entry for the target resource, given the specified URL, conditions in the query string, and the content to be added. Any current representation of the target entry is replaced.

$restClient.httpPut($url, $query, $content)

Alternative form of PUT

$restClient.httpPut($url, $datamap, $content)

DELETE

The RestClient method .httpDelete() removes the target resource.

$restClient.httpDelete($url, $querystring)

Example:

$restClient.httpDelete('people', 'id=1234')

Alternative form of DELETE The RestClient method ".httpDelete()" removes the target resource.

$restClient.httpDelete($url, $querystring)

Example:

$restClient.httpDelete('people', 'id=1234')

HEAD

The RestClient method .httpHead() gets the HTML header information available for the target resource.

$restClient.httpHead($url, $querystring)

Example:

String {
    Content-Length=40,
    Content-Type='application/json',
    Date='Fri, 29 Nov 2013 10:16:39 GMT'
}

Example:

$restClient.httpHead('people/person', 'id=1234')

Alternative form of HEAD The RestClient method .httpHead() gets the HTML header information available for the target resource.

$restClient.httpHead($url, $querystring)

Example:

String {
    Content-Length=40,
    Content-Type='application/json',
    Date='Fri, 29 Nov 2013 10:16:39 GMT'
}

Example:

$restClient.httpHead('people/person', 'id=1234')

OPTIONS

The RestClient method .httpOptions() requests a list of the HTTP methods available for the target resource.

$restClient.httpOptions('people', 'id=1234')

Example:

$restClient.httpOptions('people', null)

Alternative form of OPTIONS The RestClient method .httpOptions() requests a list of the HTTP methods available for the target resource.

$restClient.httpOptions('people', 'id=1234')

Example:

$restClient.httpOptions('people', null)

Example REST Call Script

Person $p := new Person;

$p.id := '1234';

$p.name := 'Pluto';

$p.surname := 'Dog';

//

// 

RestClient $restClient := NewObject(RestClient, 'http://localhost:8088/myapp/')

$restClient.setJSONFormat();

//

//Update a resource

$restClient.httpPost('people', null, TranslateTo($p, 'json'));

1. Create a "Person" Data Class with the following properties defined:
   • id (String)
   • firstname (String)
   • surname (String)
2. Create an instance of this Data Class, either through a script or in the Test Data editor:
   Copy

   Person $person := NewObject(
       'Person',   //The type of the new instance.
       '1234',     //Value of the id property of the new instance.
       'Pluto',    //Value of the name property of the new instance.
       'Dog'   //Value of the surname property of the new instance.
   );
   

3. Create a new REST client instance:
   Copy

   RestClient $restClient := NewObject(RestClient, 'http://localhost:8088/myapp/')
   

4. Set the format of the data interchange with the remote service to JSON:
   Copy

   $restClient.setJSONFormat()
   

5. Update the entry on the person with the ID "1234" on the target system:
   Copy

   $restClient.httpPost('people', null, TranslateTo($p, 'json'))
   

REST Configuration Parameters

The following configuration parameters are available:

• webservices.blank.as.plus By default, white spaces in user defined query parameters are encoded with '%20' during a REST call. The encoded value for white spaces can be changed to '+' instead of '%20' for the Appway Rest Client. This can be configured with the extension configuration parameter named webservices.blank.as.plus. If set to 'false' or if absent, white spaces are encoded with '%20', otherwise with '+'.

REST Best Practices

Information on Failed REST Calls

You often need to provide users with detailed information about why a REST call failed. To extract more information from an exception thrown during a REST call, use the ExceptionRootCause function from the Try/Catch block in the Appway script language.

To get the specific status code returned by the server, use the getStatusCode() method from the REST client.

By default, the REST client always throws an exception if the response code returned by the service does not belong to the ranges 2xx or 3xx.

Example showing the usage of ExceptionRootCause and getStatusCode():

RestClient $restClient := new RestClient;

$restClient.setBaseURI('http://localhost');

Try

   Return $restClient.httpGet('/service', null);

Catch

   Integer $statusCode := $restClient.getStatusCode();

   PRINTLN($statusCode);

   Exception $rootException := ExceptionRootCause($exception);

   PRINTLN($rootException);

End

Application Server Specific Issues

WebLogic Server

Oracle have their own implementation in WebLogic for the javax.xml.soap.MessageFactory and for the javax.xml.wsdl.WSDLFactory. Their implementations however are not compliant with standards and have a number of issues detailed here.

MessageFactory

The Oracle WebLogic implementation doesn't conform to the specification for SOAPEnvelopes in SOAP 1.2. There is a workaround for this which involves telling the virtual machine which implementation to use for the MessageFactory interface. This can be done by setting a system property at startup of the application server.
This is done by using the following java runtime argument

-Djavax.xml.soap.MessageFactory=javax.xml.soap.MessageFactory 

WSDLFactory

The Oracle WebLogic implementation for the WSDLFactory has a fundamental problem, when you pass an input source from which to retrieve WSDL and XSD files, it completely ignores this input source and tries to use the default URL input source regardless. In the case of the cluster we have to supply an input source capable of retrieving the cluster files instead of retrieving files directly from the filesystem and the WebLogic implementation doesn't allow this. There is a workaround for this which involves telling the virtual machine which implementation to use for the WSDLFactory interface. This can be done by setting a system property at startup of the application server.

This is done by using the following java runtime argument

-Djavax.wsdl.factory.WSDLFactory=com.ibm.wsdl.factory.WSDLFactoryImpl

General Notes

WebServices Move Tool

The WebServices extension supports moving REST or SOAP services into Packages. Moving a REST or SOAP service created with the WebServices extension implies updating the metadata of Data Classes and Primitive Types created during the first import of the service.

Moving a REST or SOAP service created with the WebServices extension is seamlessly integrated with the Move Business Objects tool available on the Package Maintenance Tab. The extension participates in the move process in two phases:

1. Initial validation
2. Post-move changes

The initial validation phase verifies that the target Package of the service and its related Data Classes (for example the classes representing the SOAP model) satisfy a set of validation constraints. If any of these validation constraints are violated, an error message describes the error and prevents continuing with the next steps of the wizard.

The post-move changes operation updates the metadata of Data Classes and Primitive Types belonging to the service according to their target package.

Note that, while move operations are supported, renaming (i.e. refactoring) a REST o SOAP service Data Class is not supported. In that case metadata would not be updated automatically. We recommend that you avoid renaming such Data Classes.

Moving a REST service

Moving a REST service is performed by dragging and dropping the Data Class representing the service from Package A to Package B as you would normally do when moving another Business Object using the built-in Move Business Objects tool.

SOAP Move Tool

Moving a SOAP service in Appway requires the user to move Data Classes and Primitive Types connected to the service so that the following constraint is satisfied:

• All Primitive Types and Data Classes belonging to the same SOAP Client must be moved into the same target Package.

The initial validation step warns the user if the condition above is not satisfied and informs the user to change the move selection to satisfy the condition before proceeding.

Example: You have a SOAP service (in the 'Base' Package) with the following Primitive Types:

• Tns1_MyPrimitiveType1 (namespace: domain.com/primitives)
• Tns2_MyPrimitiveType2 (namespace: domain.com/commons)

and the following Data Classes:

• Tns1_MyComplexType1 (namespace: domain.com/types)
• Tns2_MyComplexType1 (namespace: domain.com/commons)
• Tns3_MyComplexType1 (namespace: domain.com/types)
• Tns4_MySOAPServiceClient (namespace: domain.com/base)

A possible and valid move operation could result in the following configuration:

As the example shows, all Data Classes / Primitive Types belonging to the same SOAP Client are grouped together in the same logical Appway Package.

Primitive Types with Value Store Splitting

When defined as a property of a wrapping DataClass and persisted, the following Primitive Types that are exposed by the WebServices extension are serialized/deserialized as a null value when the Value Store Splitting feature is enabled:

• DataEntityConversionUtils
• RestClient
• SOAPAttachment

For this reason, ensure that all instances of any of the Primitive Types listed above are not null before using them in a Process.

Upgrade Notes

The SOAP and the REST extensions have been replaced by the WebServices extension. This is a drop-in replacement for the latest versions of both extensions (SOAP 5.3 and REST 2.0). If the newest versions of the SOAP and REST extensions are installed on your system before upgrading, they should first be removed, then the WebServices extension should be installed, and all existing services should require no further action.