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
© Copyright 2024