Workflows in the SOAP calls

Requirements for the workflow:

1. Workflows started by the SOAP method should contain only inProcess activities, and be completely executed by the Tomcat, since SOAP methods are synchronous and should return the result with in relatively short period of time.

2. Hash table which is returned as the result of the workflow execution must contain only values of type long, double, String, Date or Hashtable.

3. Hash table which is returned as the result of the workflow execution must contain the values with the following keys used in the ResponseDTO to identify the status of the SOAP call: STATUS, ERROR_LEVEL, ERROR_MESSAGE.

4. In most of the cases SOAP calls are used as a part of direct user interaction so the response time should be fast, which means embedded inProcess workflow should be executed within the corresponding time frames.

Getting started

In order to get started with SOAP workflow framework you will have to include the Maven artifact in your pom.xml file as a runtime dependency.

<dependency>
  <groupId>com.cdrator.integration.soap</groupId>
  <artifactId>rator-soap-workflow</artifactId>
  <version>2.4</version>
  <scope>runtime</scope>
</dependency>

If you are adding the SOAP workflow functionality to a existing customer project, then it is the best to implement this as a project module. E.g.: SIMYO/modules/workflowSoap/pom.xml. Note that usually the artifact dependency is specified in the parent pom.xml file with the version specified (e.g.: SIMYO/pom.xml):

<dependency>
  <groupId>com.cdrator.integration.soap</groupId>
  <artifactId>rator-soap-workflow</artifactId>
  <version>2.4</version>
</dependency>

and in the module pom.xml file with the scope (e.g.: SIMYO/modules/workflowSoap/pom.xml):

<dependency>
  <groupId>com.cdrator.integration.soap</groupId>
  <artifactId>rator-soap-workflow</artifactId>
  <scope>runtime</scope>
</dependency>

Also, don't forget to include the following dependency to build the deployable WEB application WAR file:

<dependency>
  <groupId>com.cdrator.integration.soap</groupId>
  <artifactId>rator-soap-workflow</artifactId>
  <classifier>webapp</classifier>
  <type>war</type>
  <scope>runtime</scope>
</dependency>

In addition to that, configure the build process, Maven renamer and Maven WAR plugins. The example build section configuration might look like this:

<build>
  <finalName>simyo-workflow-soap</finalName>
  <plugins>
    <plugin>
      <groupId>com.cdrator.maven.plugins</groupId>
      <artifactId>rator-maven-renamer-plugin</artifactId>
    </plugin>
    <plugin>
      <artifactId>maven-war-plugin</artifactId>
      <configuration>
        <outputDirectory>${project.parent.build.directory}</outputDirectory>
      </configuration>
    </plugin>
  </plugins>
</build>

Last thing to mention about this artifact is that starting from version 2.0 it uses JAX-WS for exposing endpoint and providing WSDL document.

if you are trying to create the separate project that uses SOAP workflow framework, then just include the dependencies in the main pom.xml file and configure the build section to create the correct WAR file.

In order to test if your set up is correct, build the project using Maven and try to deploy the built WAR file on Tomcat. If the deployment was successful, then go to the following address using your browser: http://<host>:<port>/your-application/InvokerService. You should see the minimal description of your endpoint. Note that this applies to the framework versions starting from 2.0 (JAX-WS based web services). If you want to get the WSDL document, then try to access the following URL: http://<host>:<port>/your-application/InvokerService?wsdl. You should be able to see the valid WSDL document. If the application was deployed without errors, but you are unable to access WSDL or endpoint description page, then please refer to log files, there might be some issues regarding parameter tree configuration.

Configuring parameters

Before starting to create the workflows and build your service layer. You should consider configuring the following parameters:

If you set the parameter SOAP.MONITORING.ENABLE_RATOR_MONITORING_HANDLER to T, then framework monitoring handler will try to store the log record in the SOAP_MONITORING table. If there is no such table then you might use the following script to create one:

CREATE TABLE SOAP_MONITORING
(
  ID                NUMBER                      NOT NULL,
  CREATE_DATE       DATE,
  WEB_SERVICE_NAME  VARCHAR2(200 BYTE),
  WEB_METHOD_NAME   VARCHAR2(200 BYTE),
  ELAPSED           NUMBER,
  SERVICE_OUTCOME   NUMBER,
  REQUEST_XML       CLOB,
  RESPONSE_XML      CLOB,
  ERROR_CODE        VARCHAR2(100 CHAR),
  ERROR_MESSAGE     VARCHAR2(200 CHAR),
  HOOKPOINT_KEY     VARCHAR2(100 CHAR)
);

ALTER TABLE SOAP_MONITORING ADD (PRIMARY KEY (ID));

If you want to store the SOAP request/response XML documents in the fields SOAP_MONITORING.REQUEST_XML and SOAP_MONITORING.RESPONSE_XML then you have to set the parameter SOAP.MONITORING.ENABLE_XML_PERSISTENCY to T.

If you want to enable the SOAP request validation using XML validation files then you have to set the parameter SOAP.VALIDATION.IS_ENABLED to Y and specify the path where the validation XML files are located using parameter SOAP.VALIDATION.PATH_TO_XMLS.

Note: The recent versions of this framework support loading XML files from a specific folder in CLASSPATH called SOAP_XML. E.g.: <...>/Tomcat/webapps/your-soap-application/WEB-INF/classes/SOAP_XML.

After you have designed you workflow and specified hookpoint keys, then you might start calling the service and invoking the workflows.

The most basic request structure should include the elements specified in the following table:

Request:

CONTEXT:

And the example SOAP request for this structure would look like:

<?xml version="1.0" encoding="UTF-8"?>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:executeMethod xmlns:ns2="http://soap.CDRator.com/">
      <arg0>
        <hookpointKey>YOUR_HOOKPOINT_KEY</hookpointKey>
        <values xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:complexValueDTO">
          <key>CONTEXT</key>
          <value xsi:type="ns2:stringValueDTO">
            <key>LANGUAGE</key>
            <value>EN</value>
          </value>
          <value xsi:type="ns2:stringValueDTO">
            <key>OPERATOR</key>
            <value>eka</value>
          </value>
        </values>
      </arg0>
    </ns2:executeMethod>
  </S:Body>
</S:Envelope>

If you try to make the call to InvokerServer using this request, the framework should try to start the workflow having the provided hookpoint key.

Note: For every hookpoint key you call, you will have to provide the validation XML file with the same name as the hookpoint key. That means, if you want to invoke the workflow with the hookpoint key 'YOUR_HOOKPOINT_KEY', then there should be a validation XML for this call named <path_to_xml_files>/YOUR_HOOKPOINT_KEY.xml.

Validation XML structure

One of the basic validation XMLs could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<soapcall>
  <request>
    <hookpointKey>SOAP_CREATE_PAYMENT</hookpointKey>
    <values>
      <value mandatory="true" type="c" key="CONTEXT" desc="Context object, mandatory in each request.">
        <values>
          <value mandatory="true" type="s" key="LANGUAGE" regexp="[A-Z]{2}" desc="Language code. EN, FR, DK, SE, etc. Used for displaying error messages." />
          <value mandatory="true" type="s" key="OPERATOR" regexp="[a-z]{2,10}" desc="Operator information." />
          <value type="s" key="BRAND_ID" desc="Id of the brand if applicable." />
        </values>
      </value>
      <value mandatory="true" type="c" key="ACCOUNT_PAYMENT" class="com.CDRator.billing.financial.AccountPayment" desc="The account payment to store.">
        <values>
          <value mandatory="true" type="l" key="AMOUNT" desc="Amount paid." />
          <value mandatory="true" type="d" key="PAYMENT_DATE" desc="Date of the payment." />
          <value mandatory="true" type="s" key="REFERENCE" desc="Payment reference." />
          <value type="b" key="IS_VALID" />
        </values>
      </value>
    </values>
  </request>
  <response>
    <values>
      <value type="s" key="PAYMENT_ID" />
    </values>
  </response>
</soapcall>

As you can see, it includes, the hookpoint key and the value structure definition as well as what values will be returned in the SOAP response document.

There are 6 possible data types that can describe the structure of the data.

c - ComplexValueDTO
s - StringValueDTO
b - BooleanValueDTO
d - DateValueDTO
f - DoubleValueDTO
l - LongValueDTO

All data types except the ComplexValueDTO are basic, atomic data types and are specified with the following tag:

<value mandatory="true|false" type="s|d|l|b|f" regexp="[pattern if any]" key="VALUE_KEY" desc="Provide a brief description."/>

The ComplexValueDTO must have class key that specifies what kind of object is passed to the request. It may also have a list of values, those are the object attributes and can be any kind of data type. Example tag structure:

<value mandatory="true|false" type="c" key="VALUE_KEY" class="fully qualified class name, e.g.: com.example.Dummy" desc="A brief description if any.">
    <values>
        <value mandatory="true|false" type="s|d|l|b|f|c" regexp="[pattern if any]" key="VALUE_KEY" desc="Provide a brief description."/>
        ...
        <value>...</value>
    </values>
</value>

Attributes that describe the data structure and the constraints:

• mandatory - element is mandatory in the request if this attribute = "true"
• key - key of the element
• regexp - regular expression, which could be used to validate string input parameters
• desc - description, used for generating the documentation from XML. If it is missing, description in documentation will be created from the KEY
• class - class name, can be specified for complex values. If it is specified, instance of the class will be created and passed to the workflow instead of the hash table. Setters will be used to set the values, and the names of the method is generated from the key. If the key can not be used for this purpose, additional attribute ("setter") has to be specified
• setter - used to specify setter method name in case it can not be generated from the key (for the complex objects which should be translated to CDRator objects automatically)
• method - used to specify getter method name in case it can not be generated from the key (for the cases when in response CDRator objects should be translated to ComplexObjectDTO automatically)
• list - attribute of the complex object, if = "true", complex object is translated to array list, valid both in request and response

Take a look at the ACCOUNT_PAYMENT object definition above to get the idea how the object validation is organized.

Note: If you will make validation for nested complex types, then those objects and their attributes will be validated recursively. This gives a lot of flexibility and freedom to your service layer, but if you need to make some kind of very specific validation, e.g.: you want to check if key A is set and has value only if key B equals to TRUE. This is a limitation of the framework and should be implemented in the workflow as this is more business logic related validation rather than data structure related.

After the validation XML file is created and being used by the framework, the validation utility will expect the workflow context to have the described data types. If any of the described keys will be missing or will fail to pass validation, then the framework will return the SOAP response with the corresponding error message.

The section which describes the message response (the response tag) tells the framework to look for the specified keys in the workflow context and return the corresponding values in the SOAP response message. This means that, when designing your workflows, make sure that those keys you have specified are present in the workflow context before the workflow execution has finished.