ActiveVOS REST Sample Technical Note

ActiveVOS REST
Sample
Technical Note
© 2012 Active Endpoints Inc. ActiveVOS is a trademark of Active
Endpoints, Inc. All other company and product names are the
property of their respective owners.
2012
0
Content
Introduction .................................................................................................................. 3
About the Project .......................................................................................................... 5
Steps to Deploy and Execute the Project......................................................................... 6
Triggering the CreateParts process to create and insert the database entries .............. 6
Triggering the QueryParts process to query the values ............................................... 7
References .................................................................................................................... 9
About Active Endpoints .................................................................................................. 9
Appendix – aeREST.xsd .................................................................................................10
Copyright © 2012, Active Endpoints, Inc.
Page 2 of 11
Introduction
ActiveVOS enables developers to expose processes as Representational
State Transfer (REST)-based services as well as to create processes that
consume REST services. Using REST, a WSDL interface is not required, but
like SOAP-based orchestrations, one-way and synchronous/synchronous
request-reply message exchange patterns are supported. And, of course
a mix of REST, SOAP, JMS or POJO can be implemented within a single
process.
REST is an architectural style that describes how resources are defined
and addressed. REST consumers and services communicate over HTTP to
exchange representations of resources addressable by a URL.
ActiveVOS generates and receives REST requests on behalf of processes.
When a REST request destined for a process is received, ActiveVOS
converts the request to a normalized representation that allows a
developer to manipulate its content. This mechanism is also used when
invoking a REST service. The aeREST.xsd schema (see the Appendix)
specifies the content of the request, response, and fault messages.
Copyright © 2012, Active Endpoints, Inc.
Page 3 of 11
ActiveVOS allows you to specify communication details of a REST request
message, including for example, the HTTP method to use, the payload
and attachments, and authentication information. The following XML
instance document lists the parameters that can be specified.
<ns2:RESTRequest
xmlns:ns2="http://schemas.activebpel.org/REST/2007/12/01/aeREST.xsd">
<ns2:subdomain />
<ns2:method />
<ns2:pathInfo />
<ns2:params>
<ns2:param name="" value="" />
</ns2:params>
<ns2:headers>
<ns2:header name="" value="" />
</ns2:headers>
<ns2:payload contentType=""></ns2:payload>
<ns2:queryString />
<ns2:authType />
<ns2:ssl />
<ns2:contextPath />
<ns2:requestURI />
</ns2:RESTRequest>
Copyright © 2012, Active Endpoints, Inc.
Page 4 of 11
About the Project
The project that accompanies this document demonstrates the following:
1. How to expose a process as a REST service.
2. How to invoke the REST service with a REST Two Way operation.
3. Other features which are incorporated are:
 Data Access Services
 System logging in case of faults
 Getting a Catalog Resource
 XQuery Constructs – For Loop Usage
A short description of the processes involved in the example project:
#
Name of the
Process Definition
Purpose
1
CreateParts.bpel
This process is the starting point of executing the sample. The process is instantiated
with a string input that represents a table name. The process invokes a wrapper service
through a REST Interface, that includes the Data Access service to drop the table (if
exists), creates a new table with a predefined structure, inserts values to it.
2
PartsService.bpel
In case of inserting the data to the database, the values are retrieved from an XML File
in the ActiveVOS Catalogs. The XML file is deployed from the project location:
project:/RESTImplementation/runtimeParameters/PartsList.xml and the location is
passed as a reference, via the REST Input Parameter to the REST Service
(PartsService.bpel)
This wrapper service acts as a REST Service that has the Data Access Service calls for the
Create, Select, Insert and Drop the contents of the table.
In case of an Insert Call to this service, the service retrieves the location reference of the
xml, retrieves the catalog information by passing the location as an input URI, and loops
through the contents to insert the data to the database table.
3
QueryParts.bpel
In case there is an exception while performing any of the database operations, the
process transfers control to its fault handler and logs the fault detail as an error, via the
ActiveVOS System Logging service. The error message can be viewed from ActiveVOS
Console > Monitor > System Log.
Once the table is loaded with data, this service can be invoked to query the availability
of the parts based on the input (search) condition. This process demonstrates the usage
of XQuery For Loop construct.
Copyright © 2012, Active Endpoints, Inc.
Page 5 of 11
Steps to Deploy and Execute the Project
Triggering the CreateParts process to create and insert
the database entries
1. Import the attached orchestration project to your designer.
2. Deploy RESTImplementation.bpr contained within the project
deploy directory.
3. Login to the ActiveVOS Console and navigate to Admin >
Configure Server> URN Mappings. Add a URN Mapping as
follows:
urn:database  java:comp/env/jdbc/ActiveVOS
4. Next, initiate the ‘CreateParts’ Process with the following steps:
a. Login to ActiveVOS Central –
http://localhost:8080/activevos-central (change the host and
port if it is different in our environment) using either users
from either of the loanreps or loanmgrs group (this
presumes you’ve already installed and deployed the “Human
Approval Completed” tutorial and have configured the
identity service with these two groups and associated user
accounts)
b. Click on Requests tab > select the REST Parts Sample, and
then the Create Parts process request form.
c. Provide a Table Name (e.g. Test1) and click on Send Request
Completed Form.
As an alternative to steps a, b and c, you could also send the following
SOAP request to the endpoint
http://localhost:8080/active-bpel/services/CreatePartsService?wsdl
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:par="http://schemas.activeendpoints.com/demo/schema/Parts/2010/07/PartsDataService.xsd">
<soapenv:Header/>
<soapenv:Body>
<par:LoadTableRequest>
<par:tableName>Parts</par:tableName>
</par:LoadTableRequest>
</soapenv:Body>
</soapenv:Envelope>
Copyright © 2012, Active Endpoints, Inc.
Page 6 of 11
5. You will receive a response – “Values Inserted to the Table
Successfully”, that indicates that the Table is created, and the
values are inserted to it.
If you receive a different response, such as “Values Not inserted to
the Table”, you would need to investigate the process to find out
where it failed.
Triggering the QueryParts process to query the values
1. Initiate the ‘QueryParts’ Process with the following steps:
a. Login to ActiveVOS Central –
http://localhost:8080/activevos-central (change the host and
port if it is different in our environment) using one of the
users of either loanreps or loanmgrs group
b. Click on Requests tab > select the REST Parts Sample, and
then the Query Parts process request form.
c. Provide the details asked for and click on Send Request
Completed Form. Example:
Table Name: As provided in the CreateParts Request
Make: Chevy
Model: Vega
Year: 1972
or
Table Name: As provided in the CreateParts Request
Make: Toyota
Model: Camry
Year: 2004
As an alternative to steps a, b and c, you could also send the following
soap request to the endpoint
http://localhost:8080/active-bpel/services/QueryPartsService?wsdl
Request:
<soapenv:Envelope
xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:par="http://schemas.activeendpoints.com/demo/schema/Parts/2010/01/Parts.xsd">
<soapenv:Header/>
<soapenv:Body>
<par:PartsRequest>
<par:queryTable>abcd</par:queryTable>
Copyright © 2012, Active Endpoints, Inc.
Page 7 of 11
<par:make>Chevy</par:make>
<par:model>Vega</par:model>
<par:year>1972</par:year>
</par:PartsRequest>
</soapenv:Body>
</soapenv:Envelope>
2. You will receive a response listing the search results that shows
the details such as Category, Sku, Desc, and Part Cost.

If the search criteria do not match with what is in the
database you will receive an empty table with ‘No Results’
Copyright © 2012, Active Endpoints, Inc.
Page 8 of 11
References
[1] REST:
http://infocenter.activevos.com/infocenter/ActiveVOS/v91/index.jsp?to
pic=/com.activee.bpel.doc/html/UG26.html
[2] DATA ACCESS SERVICE
http://infocenter.activevos.com/infocenter/ActiveVOS/v91/index.jsp?to
pic=/com.activee.bpel.doc/html/UG28-9.html
http://www.activevos.com/developers/howto#DataJavaShellandRESTInt
egration
[3] Server Log Service
http://infocenter.activevos.com/infocenter/ActiveVOS/v91/index.jsp?to
pic=/com.activee.bpel.doc/html/UG28-7.html
About Active Endpoints
Active Endpoints, Inc. delivers a unique suite of process automation
products and related services to develop, integrate and deploy custom
applications quickly and easily. The company’s products —Socrates and
ActiveVOS empower business users and IT project teams to collaborate
more effectively.
The company has hundreds of customers worldwide from large
enterprises to SMBs, spanning multiple industries such as
telecommunications, government, financial services, and media and
entertainment.
Active Endpoints is headquartered in Waltham, MA with development
facilities in Shelton, CT.
To find out how Active Endpoints can help your business, visit
http://www.activevos.com, call +1 781 547 2900 and press 1 for Sales, or
email us at [email protected].
Copyright © 2012, Active Endpoints, Inc.
Page 9 of 11
Appendix – aeREST.xsd
Find here the aeREST.xsd (as of ActiveVOS 9.1.0.2)
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns:tns="http://schemas.activebpel.org/REST/2007/12/01/aeREST.xsd"
elementFormDefault="qualified"
targetNamespace="http://schemas.activebpel.org/REST/2007/12/01/aeREST.xsd">
<!-- HTTP Method enumeration used for REST -->
<xs:simpleType name="httpMethodType">
<xs:restriction base="xs:string">
<xs:enumeration value="GET"/>
<xs:enumeration value="POST"/>
<xs:enumeration value="PUT"/>
<xs:enumeration value="DELETE"/>
<xs:enumeration value="TRACE"/>
<xs:enumeration value="OPTIONS"/>
</xs:restriction>
</xs:simpleType>
<!-- Error type enumeration used for REST -->
<xs:simpleType name="errorType">
<xs:restriction base="xs:string">
<xs:enumeration value="transport"/>
<xs:enumeration value="system"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="pairType">
<xs:attribute name="name" type="xs:string"/>
<xs:attribute name="value" type="xs:string"/>
</xs:complexType>
<xs:complexType name="paramsType">
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" name="param"
type="tns:pairType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="headersType">
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="0" name="header"
type="tns:pairType"/>
</xs:sequence>
</xs:complexType>
<xs:complexType mixed="true" name="payloadType">
<xs:sequence>
<xs:any minOccurs="0" namespace="##any" processContents="skip"/>
</xs:sequence>
<xs:attribute name="contentType" type="xs:string"/>
</xs:complexType>
<xs:element name="locale">
<xs:complexType>
<xs:simpleContent>
Copyright © 2012, Active Endpoints, Inc.
Page 10 of 11
<xs:extension base="xs:string">
<xs:attribute name="lang" type="xs:string" use="required"/>
<xs:attribute name="country" type="xs:string" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="locales">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" minOccurs="1"
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="RESTRequest">
<xs:complexType>
<xs:sequence>
<xs:element minOccurs="0"
<xs:element name="method"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
<xs:element minOccurs="0"
</xs:sequence>
</xs:complexType>
</xs:element>
ref="tns:locale"/>
name="subdomain" type="xs:string"/>
type="tns:httpMethodType"/>
name="pathInfo" type="xs:string"/>
name="params" type="tns:paramsType"/>
name="headers" type="tns:headersType"/>
name="payload" type="tns:payloadType"/>
name="queryString" type="xs:string"/>
name="authType" type="xs:string"/>
name="ssl" type="xs:boolean"/>
name="contextPath" type="xs:string"/>
name="requestURI" type="xs:string"/>
ref="tns:locales"/>
<xs:element name="RESTResponse">
<xs:complexType mixed="true">
<xs:sequence>
<xs:element minOccurs="0" name="headers" type="tns:headersType"/>
<xs:element minOccurs="0" name="payload" type="tns:payloadType"/>
</xs:sequence>
<xs:attribute name="statusCode" type="xs:int" use="optional"/>
</xs:complexType>
</xs:element>
<xs:element name="RESTFault">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="1" minOccurs="1" name="errorCode" type="xs:int"/>
<xs:element maxOccurs="1" minOccurs="1" name="message"
type="xs:string"/>
<xs:element maxOccurs="1" minOccurs="1" name="messageDetails"
type="xs:string"/>
</xs:sequence>
<xs:attribute name="errorType" type="tns:errorType" use="required"/>
</xs:complexType>
</xs:element>
</xs:schema>
Copyright © 2012, Active Endpoints, Inc.
Page 11 of 11