Page Comparison

...

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.

Validation XMLs

mandatory - element is mandatory in the request if this attribute = "true"

key - key of the element

type - type of the element (possible values:
c - ComplexValueDTO
s - StringValueDTO
b - BooleanValueDTO
d - DateValueDTO
f - DoubleValueDTO
l - LongValueDTO)

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

Attributes:

...

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.

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>
  <version>2.4</version><classifier>webapp</classifier>
  <type>war</type>
  <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):

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

<dependency><build>
  <groupId>com.cdrator.integration.<finalName>simyo-workflow-soap</groupId>finalName>
  <artifactId>rator-soap-workflow</artifactId><plugins>
    <plugin>
  <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.integrationmaven.soap<plugins</groupId>
      <artifactId>rator-maven-soaprenamer-workflow<plugin</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:

...

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>
<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
  <S:Body>
    <ns2:executeMethod xmlns:ns2="http://soap.CDRator.com/">
 <request>
    <hookpointKey>SOAP_CREATE_PAYMENT</hookpointKey>
    <values>
     <arg0> <value mandatory="true" type="c" key="CONTEXT" desc="Context object, mandatory  <hookpointKey>YOUR_HOOKPOINT_KEY</hookpointKey>
        <values xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="ns2:complexValueDTO"in each request.">
          <key>CONTEXT</key><values>
          <value xsi:typemandatory="ns2:stringValueDTOtrue">             <key>LANGUAGE</key>
   type="s" key="LANGUAGE" regexp="[A-Z]{2}" desc="Language code. EN, FR, DK, SE, etc. Used for displaying error messages." />
        <value>EN</value>  <value         </value>mandatory="true" type="s" key="OPERATOR" regexp="[a-z]{2,10}" desc="Operator information." />
          <value xsi:type="ns2:stringValueDTO">
      "s" key="BRAND_ID" desc="Id of the brand if applicable." />
     <key>OPERATOR</key>   </values>
      </value>
     <value>eka</value> <value mandatory="true" type="c" key="ACCOUNT_PAYMENT" class="com.CDRator.billing.financial.AccountPayment" desc="The account payment to  </value>store.">
        <values>
</values>       </arg0>   <value mandatory="true" type="l" key="AMOUNT" desc="Amount paid." />
      </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> <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 mandatory="true" type="cs" key="CONTEXTPAYMENT_ID" desc="Context object, mandatory in each request.">
/>
    </values>
       <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:

</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."/>

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>
        ...
        <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.

...