How to Create a Data Services application for the Experience Server that returns data

In Our development guide for Experience Service, there is an good example about “Create a Data Services application for the Experience Server that returns data”, see link here. It described all the details necessary for the project. However, there are a few places that could be confusing for users that are not familiar with CRX/CQ and Maven. In this blog I have re-organized and simplified the steps to make it easier to follow, and added Note in the places where it could be easy to make mistake or get confused. I have also put Troubleshooting Tips at the end. I hope this will make deploying to Experience Services easier for you.

I have divided the task into three sections:

  • Prepare the development environment:
  • Create and configure server-side project
  • Create and configure client side project

If this is the first time you work with data service 4.5 version(running on CQ servlet), please make sure you go through the first section to get your environment set up correctly for your future development.

[Note] Step 6 to 8 is for using Maven to build and deploy the app. If you want to load you class/Jar and app directly into OSGI without using the template application and maven, you can skip these steps and follow the link here, then go to step 9.

  • Prepare the development environment:

  • 1. Download the Flash Builder 4.5 installer from here and install the software as described in Flash Builder 4.5 Release (Note, for MAC, you need to do more configuration. See here

    2. Install plug-ins for Flash Builder, see here.

    3. Setting up Maven in your development environment (If you don’t want to build the project via maven for developing test, you don’t have to configure this at this time)

      a. Download maven from http://maven.apache.org/download.html
      b. After extract Maven to your machine, for example, c:/apache-maven-3.0.3, create an environment variable named M3_HOME, and point to c:/ apache-maven-3.0.3.

    4. Install and config ADEP Experience Services

      a. Download the Experience Services Quickstart JAR file from here . The file name should be something like adep-ria-quickstart-10-0-all-all.jar
      b. Make sure you have jdk1.6.0_26 or higher installed on your machine (but 1.7 is not supported). And set JAVA_HOME to point to the jdk1.6.0_26, and Path= %JAVA_HOME%\bin;
      c. Create a directory to run your ADEP Experience Services. For example, create c:/dataService_sample, and copy adep-ria-quickstart-10-0-all-all.jar into directory and rename it to adep-ria-quickstart-10-0-all-all-p4502.jar. (This will make the Experience Services to use port 4502).
      d. Start Experience Services by double click on adep-ria-quickstart-10-0-all-all-p4502.jar. This will take several minutes to install. Once it is done installing, a license page will come up, or you can access it by http://localhost:4502 . Log in using your Adobe ID and password to Retrieve License Key. (Note: the Adobe ID is the account you use to download any adobe software to access adobe lab or shared package. If you don’t have an account yet, you can go to http://labs.adobe.com/ to create one.)
      Once you get the license key and put in the license page, you will see ADEP Experience Services login page. Use admin/admin to login.
      e. From the welcome page, click on “packages”, scroll down and find dataservices-sdk-pkg-4.5.0-0050.zip. Clicks on dataservices-sdk-pkg-4.5.0-0050.zip, then click download to save it on your machine. Then do the same to download dataservices-example-app-template.zip

    Make sure you have all above installed and configured before you start to create or deploy your data service project.

  • Create your data service application server-side--using remote to return data
  • 5. Create your Java server-side class. For this example, we create a simple class named EchoService.java like this:

    package com.adobe.myexample;
    public class EchoService {
    public String sayHello(String val){
    return "Adobe Digital Enterprise Platform says: " +val ;
    }
    }

    Note: To compile your class, you need to have dataservices-bundle.jar in your classpath. (EchoService doesn’t need this because it is not using any of the data service classes). The dataservices-bundle.jar can be obtained from the dataservices-sdk-pkg-4.5.0-0050.zip you downloaded on step 4.e. It is under:[ZIP location]\dataservices-sdk-pkg\jcr_root\etc\aep\sdks\riaservices\dataservices\4.5.0\java

    6. To place the application files in the template application
    Extract dataservices-example-app-template.zip you got from 4.e to a folder on your machine, say c:/template:

      a. copy dataservices-bundle.jar and put into the template application’s lib folder.
      b. Under the sourceCode\src\main\java folder, create a folder structure that reflects the Java package structure. For this example, it is: sourceCode\src\main\java\com\adobe\myexample.
      c. Place EchoService.java file in the myexample folder.
      d. Open pom.xml file under sourceCode folder, scroll down and find the following section:


       <Export-Package>
          com.sample,
       </Export-Package>

    And change it to:

       <Export-Package>
          com.sample,
          com.adobe.myexample
       </Export-Package>

    Note: there are multiple mop.xml file in the template app, make sure you modify the one under sourceCode folder, otherwise your app will not be built correctly.

    7. Using Maven to build the package:
    Open command prompt under c:/ template, enter the following command:
    %M3_HOME%\bin\mvn clean install

    Make sure the build was successful by looking at the log. After the build was successful, it will create a zip file dataservices-example-app-bundle-1.0-SNAPSHOT.jar under c:/ template/package/target

    8. Deploy your app to Experience Services:

      a. Go back to http://locahost:4502, click on Packages, then click “Upload package” from the menu, then select dataservices-example-app-bundle-1.0-SNAPSHOT.jar under c:/ template/package/target.
      Click on dataservices-example-app-bundle-1.0-SNAPSHOT.jar that’s displayed there, then click Install.

    Note, make sure you click install, otherwise the jar is not loaded into the experience services.

      b. To confirm your package was deployed, to go OSGI console by http://localhost:4502/system/console/bundles (or you can go to welcome page, click on OSGI console, then select bundle tag), login using admin/admin
      Then search your bundle to make sure it is here, and click on the arrow beside the [package name to see the details and make sure your class is in there.
      c. To confirm your RDS is enabled: go to http://localhost:4502/system/console/configMgr
      click on “Adobe data Services”, then check enable RDS

    9. Defining the server destination for the echo service

      a. Go to http://localhost:4502/crxde , from left panel, find: /etc/aep/config/dataservices/destinations/remoting Right click on remoting folder, and select create-create file, put the file name as com.adobe.myexample.xml, click OK.
      b. Double click the com.adobe.myexample.xml file, then add the following in the to file (at right)


    <?xml version="1.0" encoding="UTF-8"?>
    <destinations>
      <destination channels="my-amf" id="echo">
        <properties>  
             <source>com.adobe.myexample.EchoService</source>
        </properties>
      </destination>
    </destinations>

    From the top menu, click the Save All button. (Don’t forget about this step).

  • Creating a Flash Builder client project for the Echo service
  • Start flash builder 4.5 (make sure the Modeler plug-in is installed by step #2)

    10. Before you create a flash builder project for your app, verify you can see the destination you created in step #9 :

      a. Change perspective to Data Model from flash builder by clicking Window, Open Perspective, Data Model,
      b. Search echo in the Remoting destinations folder.

    11. the a Flex Project for ADEP Experience Services application

      a. create a project “Flex Project for ADEP Experience Services”
      b. From the RDS server, select Experience Server (localhost)
      The host name for RDS is localhost, port is 4502, user account admin/admin.
      c. Click Test Connection button to verify connection. If it can’t connect, check and make sure the service is started (see step#4.d), and RDS is enabled (see step #8.c)
      d. Put the client code from the doc sample
      e. Run the client code from flash builder

    Troubleshooting Tips:

      1. Get Fault: “cannot create class of type ‘com.adobe.myexample.EchoService’”

    This indicates your class is not loaded into the OSGI. Double check Step 5, 6, 7, 8, and reinstall your package.

      2. Get “connection failed” error

    This ould be caused your RDS not enabled or configured correctly, see step 11.c. It also could be channel/destination configure issue, you may want to double check your channel/destination configure to make sure all the sytax and spell are correct.

      3. Get error indicating my-streaming-amf:

    go to
    http://localhost:4502/crxde , open /etc/aep/config/dataservices/services-config.xml from the left panel, you can see the section:

          <default-channels>
               <channel ref="my-streaming-amf"/>        
               <channel ref="my-polling-amf"/>      
               <channel ref="my-amf"/>
         </default-channels>


    Move
    <channel ref="my-amf"/>

    to be the first item in there, and restart the server and re-run the client code, this should get rid of the error.