Page Comparison

Requirements for the workflow:

...

1. Workflows started by the SOAP method should contain only inProcess activities

...

1. and be completely executed by the Tomcat, since SOAP methods are synchronous and should return the result

...

1. within relatively short period of time.
   

...

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

...

1. 
   
2. The 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.
   

...

1. 
   
2. 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 the SOAP workflow framework you will have to include the Maven artifact in your pom.xml file as a runtime dependency.

...

If you are adding the SOAP workflow functionality to a an existing customer project, then it is the best to implement this as a project module, e. 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):

...

<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 The last thing to mention about this artifact is that starting from version 2.0 it uses JAX-WS for exposing endpoint end-point and providing WSDL document.

if If you are trying try 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 that your set up setup is correct, build the project using Maven and try to deploy the built WAR file on Tomcat. If the deployment was is successful, then go to the following address using in your browser:

• http://<host>:<port>/your-application/InvokerService

...

You should see the minimal description of your endpointend-point. 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 end-point description page, then please refer to log files, there might be some issues regarding parameter tree configuration.

Configuring

...

Parameters

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

...

If you set the parameter SOAP.MONITORING.ENABLE_RATOR_MONITORING_HANDLER to T, then the 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:

...

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 to the location of the validation XML files are located using the parameter SOAP.VALIDATION.PATH_TO_XMLS.

Note: The recent Recent versions of this framework support loading XML files from a specific folder in CLASSPATH called SOAP_XML, e. E.g.:

• <...>/Tomcat/webapps/your-soap-application/WEB-INF/classes/SOAP_XML

...

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

...

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

...

If you try to make the call to InvokerServer using this request, the framework should try to start the workflow having that has 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 , that 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 seeappears, 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 to describe the structure of the data.

...

The ComplexValueDTO must have a 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:

...

• 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, the description in the documentation will be created from the KEY
• class - class name, can be specified for complex values. If it is specified, the 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 cannot be used for this purpose, additional attribute ("setter") has to be specified
• setter - used to specify for specifying the setter method name in case it can not cannot be generated from the key (for the complex objects which should be translated to CDRator objects automatically)
• method - used to specify for specifying the getter method name in case it can not cannot 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 an idea of 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 whether key A is set and has a 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 are 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 in designing your workflows , make sure that those the keys you have specified are present in the workflow context, before the workflow execution has is finished.