View source for SMILA/Documentation/HowTo/How to filter and access record data in BPEL

This tutorial shows how to add [[SMILA/Glossary#R|record]] [[SMILA/Glossary#A|attributes]] to a BPEL workflow object and read or write them. Note that this procedure is only necessary if you want to make record data available for being used in BPEL, e.g. to evaluate conditions in the BPEL pipeline or to pass data to external webservices. It is not required for the usage of [[SMILA/Glossary#P|pipelets]]. 

== Adding record data to the BPEL workflow object==

Because the workflow object contains the record IDs only, it is not possible by default to access the data contained in a record. However, you can configure the [[SMILA/Glossary#B|blackboard service]] to add particular attributes and annotations to the workflow object to make theme available for being used in BPEL. This is achieved by providing the file <tt>org.eclipse.smila.blackboard/RecordFilters.xml</tt> in the global configuration folder and defining a filter named ''workflow-object'' that lists all attributes and annotations that you want to have access to in BPEL. The name of this filter is defined by the ''record.filter'' parameter set in the configuration file of the processing service found at <tt>org.eclipse.smila.processing.bpel/processor.properties</tt>. If you wish to write data to attributes you will have to add them to the filter likewise. 

=== Example ===

The following listing shows an exemplary configuration of the file <tt>RecordFilters.xml</tt>. It adds a couple of attributes (e.g. ''Filename'', ''Path'', ''LastModifiedData'', ...) to the workflow object. For some of the attributes the ''keepAnnotations'' parameter is set to ''"true"'' to define that the object should include the annotations of the corresponding attribute too.
<source lang="xml">
<RecordFilters>
  <Filter name="workflow-object">
    <Attribute name="Filename"/>
    <Attribute name="Path"/>
    <Attribute name="LastModifiedDate"/>
    <Attribute name="Url"/>
    <Attribute name="Title"/>
    <Attribute name="Extension"/>
    <Attribute name="Size"/>
    <Attribute name="MimeType"/>
  </Filter>
</RecordFilters>
</source>

== Using records in BPEL ==
Next to the configuration of the attribute/annotation filter mentioned above, you will have to make sure that the following requirements are met if you wish to access records in BPEL:
* The XML namespaces for <tt>processor</tt> and <tt>record</tt> must be defined.
* The processor ''processor.wsdl'' must be imported.
* A variable (e.g. ''request'') must be defined that contains the ''ProcessorMessage''.

Here are the corresponding XML snippets:
<source lang="xml">
<process ...  xmlns:proc="http://www.eclipse.org/smila/processor" xmlns:rec="http://www.eclipse.org/smila/record" ... >
    ...
  <import location="processor.wsdl" namespace="http://www.eclipse.org/smila/processor"
    importType="http://schemas.xmlsoap.org/wsdl/" />
    ...
  <variables>
    <variable name="request" messageType="proc:ProcessorMessage" />
  </variables>
    ...
</process>
</source>

Provided that you added the filter configuration and ensured the requirements above it is possible to access records and their contents via the variable ''request''. This variable contains an array of records. Each record can be accessed via its index number (starting at 1). So to be able to process all records, you will have to wrap the record access and execution of any business logic in a loop.

Here are some templates to access (read or write):
* an attribute value: <tt>$<variable>.records/rec:Record[position()=<index>]/rec:Val[@key="<Attribute-Name>"]</tt>

For more details on the XML schemas and the WSDL see the files <tt>id.xsd</tt>, <tt>record.xsd</tt>, and <tt>processor.wsdl</tt> in the folder <tt>configuration/org.eclipse.smila.processing.bpel/pipelines</tt>.

=== Examples ===

==== Reading an attribute ====
The value of the attribute ''Title'' is read from the first record and stored in the variable ''input.param''.
<source lang="xml">
...
<assign name="copy-attribute-to-variable">			
    <copy>
        <from>$request.records/rec:Record[position()=1]/rec:Val[@key="Title"]</from>
        <to>$input.param</to>
    </copy>
</assign>
...
</source>

==== Writing an attribute ====
The value of the variable ''response.param'' is stored in the attribute ''Title'' of the second record. 

<source lang="xml">
...
<assign name="copy-variable-to-attribute">
    <copy>
        <from>$response.param</from>
        <to>$request.records/rec:Record[position()=2]/rec:Val[@key="Title"]/text()</to>
    </copy>
</assign>
...
</source>

Note that in standard BPEL the target element that you want to write data to, must already exist before text can be stored in it, thus it is not possible to add new attributes, literal, and values to the workflow object this simply.

=== Examples in SMILA source code ===

Have a look at the pipelines of the standard configuration in <tt>[https://dev.eclipse.org/svnroot/rt/org.eclipse.smila/trunk/core/SMILA.application/configuration/org.eclipse.smila.processing.bpel/pipelines SMILA.application/configuration/org.eclipse.smila.processing.bpel/pipelines]</tt> or the test pipelines in bundle <tt>[https://dev.eclipse.org/svnroot/rt/org.eclipse.smila/trunk/core/org.eclipse.smila.processing.bpel.test/configuration/org.eclipse.smila.processing.bpel/pipelines org.eclipse.smila.processing.bpel.test/configuration/org.eclipse.smila.processing.bpel/pipelines]</tt>. You can find lots of examples for usage of BPEL control structures and XPath queries in there.