it is

Transcription

1 More complete RESTful Services for Oracle Sales Cloud Sample/Demo Application This sample code builds on the previous code examples of creating a REST Facade for Sales Cloud, by concentrating on six of the main objects people tend to work with on Oracle Sales Cloud, namely: Opportunities Leads Locations Sales Party Person Interactions This application is an extension of a previous blog article it is recommended this article and tutorial are followed first. For this example I won t be taking you through a step by step tutorial on how to build the code, but I will be concentrating on the "features" I've implemented. If you want you can simply run the code as is, or extend it. At this point its worth pointing out that this code is SAMPLEWARE and delivered with no guarantees, warrenties or even support!!! To use the code you will also need to download the Jersey APIS from the jersey website accordingly. Functionality / Features Supports Oracle Sales Cloud Release 7 and JDeveloper Ability to query data in a RESTFul way (using GET/PUT verbs) Data can be queried using JSON or XML data formats URIs can contain parameters which reduce the amount of data which is returned, e.g. only bring back Opportunity IDs and Names URI can contain SIMPLE queries, e.g. where OptyID= Complex queries can be passed in as a POST query when the URI ends in /xmlquery User Credentials, CRM Server, FetchSize and FetchStart can be provided in httpheaders, thus can be encrypted by SSL Default Server can be setup so that credentials are not needed Project can be extended to cover other objects Limitations Read only is implemented, if you want to issue writes (PUTS) or updates then I recommend custom methods for each operation you require.

2 In the future Oracle Sales Cloud will likely have support REST support natively; This software will work fine against future versions of Oracle Sales Cloud but you are probably better off using the native Oracle Sales Cloud REST support when it How to deploy Download Source code Download Jersey 1.x files from This bundle contains a collection of java jar files we need. Expand the zip file and put the following files into a lib directory within the FusionRESTService project. o 2. Within the FusionRESTService Project, edit the fusionconfig.properties and ensure URLs are correct and if desired appropriate username/password is correct. o The username/password properties within this file are mainly used for testing. It defaults the username/password to known values and makes it easy to execute queries against the server using a webbrowser interface. Its unlikely, actually not recommended, that you would set the username/password properties in a real system.

3 o The fusioncrmdefaultendpointurl is the default SalesCloud Server, this is optional 3. Ensure all projects are "build" using Oracle JDeveloper , this can easily be done by doing a ReBuild on the FusionRESTService project o Right Mouse click on the FusionRESTService project, select Rebuild FusionRESTService.jpr o Do not use Oracle JDeveloper x 4. Right mouse click on the FusionRESTService project and select Deploy RestfulFusion. o Either Deploy to a Weblogic Application Server or Deploy to WAR file which you can then deploy to either a Weblogic Application Server or to a Java Cloud Service 5. If you deploy to WAR file you can then deploy to either Weblogic Server or Java Cloud Service Supported Methods Each object supports the same set of methods, so its quite uniform as an API Method URI Query Parameters Query all <Object> GET /jersey/location GET /jersey/opportunity GET /jersey/person GET /jersey/salesparty GET /jersey/saleslead GET /jersey/interaction attributes=<list of comma seperated attribute names> query = Query String Query all <Object> POST /jersey/interaction/xmlquery POST /jersey/location/xmlquery POST /jersey/opportunity/xmlquery POST /jersey/person/xmlquery POST /jersey/salesparty/xmlquery POST /jersey/saleslead/xmlquery POST Payload contains a XML findcriteria query as defined by a SOAP Service, or copied from tools such as SOAP UI Get specific <Object> GET /jersey/interaction/{id} GET /jersey/location/{id} GET /jersey/opportunity/{id} GET /jersey/person/{id} GET /jersey/salesparty/{id} GET /jersey/saleslead/{id} Query all interactions for a specific opportunity GET /jersey/opportunity/{id}/interactions This is a special one off and this subresource method of accessing interactions via opportunities is only available in this instance

4 Query Parameters The following section details query parameters you can add to your REST Attributes o Attributes is a comma delimited list of Level 1 attributes which you wish to query. Example /opportunity?attributes=name,optyid Query o Simple Query using valid ADFBC query operators. Operators supported = =,!=,NOT, NOT BETWEEN,CONTAINS o Only level 1 attributes can be queried o Use. between segments and between predicates o Example /opportunity?query=statuscode.=.open CreatedBy.=.FAAdmin o If simple query isn t flexible enough work for you, then use the advanced query mode instead POST Based query Using POST instead of GET you can supply a SOAP based findcriteria query as the input payload. This gives you complete control and allows you to use any SOAP Query as documented on the various websites Must be the complete SOAP Payload, just like the one you would use in SOAP UI e.g. <soapenv:envelope xmlns:soapenv=" xmlns:typ=" xmlns:typ1=" <soapenv:header/> <soapenv:body> <typ:findopportunity> <typ:findcriteria> <typ1:fetchstart>0</typ1:fetchstart> <typ1:fetchsize>300</typ1:fetchsize> <typ1:filter> <typ1:group> <typ1:uppercasecompare/> <typ1:item> <typ1:uppercasecompare>false</typ1:uppercasecompare> <typ1:attribute>createdby</typ1:attribute> <typ1:operator>contains</typ1:operator> <typ1:value>angelo.santagata</typ1:value> </typ1:item> </typ1:group> </typ1:filter> <typ1:excludeattribute>false</typ1:excludeattribute> <!--Zero or more repetitions:--> </typ:findcriteria>

5 <typ:findcontrol> <typ1:retrievealltranslations>false</typ1:retrievealltranslations> </typ:findcontrol> </typ:findopportunity> </soapenv:body> </soapenv:envelope> Http Headers This lists the available HttpHeaders which can be used Header Name Description Defaults fusionusername Username of user Username in fusionconfig.properties fusionpassword Password of user Password in fusionconfig.properties fusionendpointurl Main URL of Fusion CRM Webservice, without the service name. fusioncrmdefaultendpointurl in fusionconfig.properties e.g. (without double quotes) " fusionfetchstart Sets the fetchstart for query 0 fusionfetchsize How many records to query fusionfetchsize in fusionconfig.properties Accept Tells the backend service what data format to return the results in. Normally set to either application/xml or application/json Depends on client How to extend the sample application The project is build with three layers of projects Projects starting in the prefix "FusionProxy_XXXXX" These are generated WebService Proxies using JDevelopers Webservice proxy wizard. These projects can be regenerated if required. Project Connector Services o This project contains a number of facade classes around the above proxy objects. This is done like so because the webservice proxies can be regenerated and by having this in a separate project ensures that changes arent lost.

6 o Each service is a subclass of the FusionService (.java) superclass, this super class simply defines a structure, common methods that all the facade classes use FusionRESTService o This project contains the user interface tier of the project and contains the actual REST classes In addition there is a project called XJC_Beans, which contains a complete collection of the Java Beans required for the project. This is required to get around a bug in JDeveloper 11.x.x where not all the JAXB Bean objects are created correctly when a project contains multiple projects. See this blog entry for more details ice_proxies To add a new REST Service Method Edit the appropriate REST java class, e.g. RESTfulPersonService.java, and add your required method, with the appropriate Within this method you are free to call the Webservices Facade classes as required. To add support for a different object, e.g. Territory Mgmt 1. Create a new Project to contain a webservice Proxy, call this FusionProxy_<ObjectName> 2. Create a WebService Proxy within this project for your service, ensure that when generating data types you leave the Root Package as blank 3. Create a new WebService Facade class in the connectorservices project o You can use one of the existing java classes as a template and simply change the ClassName o Name of the Webservice Service Class, e.g. FusionSalesLeadsService and the variable The fusionendpointname 4. In the ConnectorServices Dependancies ensure the FusionProxy_<ObjectName> project is added, and you would usually you would select "Build Output" 5. Create a REST Java class in the FusionRESTService project, again you can use one of the existing java classes as a template (e.g. RESTfulInteractionService.java) 6. Ensure fusionconfig.properties contains an entry with the same name as the fusionendpointname and a real FusionCRM endpoint url Enjoy, and Remember This code is SAMPLEWARE and delivered with no guarantees, warranties or support!!! Angelo Santagata Angelo.santagata@oracle.com