Guides and Tutorials

Getting Started with Nuxeo IDE

Here we want to add some server side Java logic that will update the contract's renegotiation date. In our exemple it will simply take the contract's start date and add three months to it, but you can think of integrating any custom logic in your Java class, including a connection to an external webservice or an ERP.

Prerequisites

Step 1 - Install Nuxeo IDE

From Eclipse Marketplace

This procedure can only be used for Nuxeo 6.0 and later versions. For Nuxeo 5.8, please refer to the installation from the Eclipse Menu.

  1. In Eclipse, go into the Help, Eclipse Marketplace menu.
  2. The Eclipse Marketplace window opens. Search for Nuxeo, select Nuxeo IDE and click on the Install button.
  3. Nuxeo IDE and Nuxeo Shell are automatically selected and downloaded.
  4. When Nuxeo IDE and Nuxeo Shell are downloaded, click on the Next button.
  5. Accept license when prompted. Installation begins. After a few seconds, a security warning is prompted.
  6. On the security warning window, click on OK. Installation continues.
  7. Restart Eclipse when prompted.
  8. Nuxeo IDE is installed. A new button is available in the Eclipse toolbar:
  9. Open the Nuxeo perspective: Using the open perspective button or from the Window, Perspective menu. Choose the Nuxeo perspective.

    A new set of tabs will then be available to interact with your projects and your Nuxeo Platform server.

From Eclipse Menu

  1. Open the install dialog from the Eclipse menu: Help > Install New Software...
  2. Click on Add... button and enter the Update Site URL (stable for the latest released version, or development for a development snapshot) and name and click the OK button.
  1. If nothing appears, uncheck the Group items by category box.
  2. Check both Nuxeo IDE and Nuxeo Shell and click Next.
  3. Follow the wizard: accept license when prompted and click Next until the software is downloaded.
  4. Restart Eclipse when prompted. Nuxeo IDE is installed. A new button is available in the Eclipse toolbar:
  5. Open the Nuxeo perspective: Using the open perspective button at the top right corner from the Eclipse window or from the Window, Perspective menu. Choose the Nuxeo perspective.

    A new set of tabs will then be available to interact with your projects and your Nuxeo Platform server.

Step 2 - Register a Nuxeo Online Services Account

To configure a Nuxeo Online Services account:

  1. Open Eclipse preferences (Window, Preferences menu in Windows and Linux or from Eclipse, Preferences in Mac OS) and go to Nuxeo > Nuxeo Connect. The Host name is already filled in with Nuxeo Connect address.
  2. Type your Nuxeo Online Services login and password and click on the Connect button. The lists of Studio projects associated to your account is displayed. No need to choose something from the list here, it serves only for information purpose.
  3. Click on OK. The Preferences window closes. You can now go to the "Nuxeo Studio" tab to browse your Studio customizations.

Step 3 - Register a Nuxeo SDK

  1. Open the Nuxeo SDK preference page (Window / Preferences / Nuxeo / Nuxeo SDK menu on Windows and Linux or Eclipse / Preferences / Nuxeo / Nuxeo SDK on Mac OS).
  2. Click on Add and browse to your Nuxeo Platform SDK directory.
  3. Check that SDK in the list and click on the OK button to finish. The checkbox marks the Nuxeo Platform SDK version to use in the Eclipse workspace. You can easily switch from a Nuxeo Platform SDK version to another, for instance when testing your developments against a newer Nuxeo Platform version.

Step 4 - Install Nuxeo Generator

From a command line prompt, type:

npm install -g yo generator-nuxeo

The Nuxeo Generator lets you easily scaffold common Nuxeo components like empty projects, Packages, Automation Operations, Services... This saves you time writing boilerplate code to focus on your code instead of the structure.

We'll use it to generate a new Nuxeo project and an operation.

Step 5 - Implement an Operation

We want to create an operation that indicates the date of renegotiation of a contract, by fetching the document's start date and adding three months to it.

An operation is a Java class in which you can put custom business logic. It is usually used on top of existing Studio operations; either when the business logic you need to implement is too complicated to be created and maintained through a regular automation chain, or when the operation does not simply exist yet.

Once created, the operation can be exposed in Nuxeo Studio and used as any other operation, in automation chains and automation scripts. See the Automation section for more information about operations.

Create Your Nuxeo Plugin Project

From a command line:

  1. Create an empty folder to store your project.

    mkdir contract-mgt-project
    cd contract-mgt-project
    
  2. Generate the project structure.

    yo nuxeo
    
  3. Fill in the prompted parent project creation ("Multi module"):

    ? Use a parent artifact (for instance your company's BOM or the org.nuxeo.ecm.distribution:nuxeo-distribution POM)? y
    ? Parent Group id: org.nuxeo.ecm.distribution
    ? Parent Artifact id: nuxeo-distribution
    ? Parent Version: (leave the default option here)
    ? Project group id: com.bigcorp.contractmgt
    ? Project Artifact id: contract-mgt-project-parent
    ? Project version: 1.0-SNAPSHOT
    ? Project description: Contract management parent.
    
  4. Fill in the prompted project itself ("Single module"):

    ? Project Group id: com.bigcorp.contractmgt
    ? Project Artifact id: contract-mgt-project-core
    ? Project version: 1.0-SNAPSHOT
    ? Project description: Contract management project.
    

    Now that the project is generated, it can be used in any IDE.

  5. Generate Eclipse configuration files.

    mvn install
    
    # The following parameters (downloadSources, downloadJavadocs and useProjectReferences) are optional
    # For details, see Maven Eclipse Plugin documentation: https://maven.apache.org/plugins/maven-eclipse-plugin/eclipse-mojo.html
    mvn eclipse:clean eclipse:eclipse -DdownloadSources=true -DdownloadJavadocs=true -Declipse.useProjectReferences=true
    
    # Linux and OS X users should run the following script to make Eclipse use different build directories than Maven:
    curl -o- https://raw.githubusercontent.com/nuxeo/nuxeo/master/fixeclipse|bash
    # A cross-platform script is also available for Windows users:
    # curl -o- https://raw.githubusercontent.com/nuxeo/nuxeo/master/scripts/fixeclipse.py|python
    
  6. Import the project in Eclipse:

    1. Select File / Import / General / Existing Projects into Workspace.
    2. Browse to your project root folder (contract-mgt-project), then click Finish.
  7. Convert the project to a Nuxeo project: right-click on the project name, then choose Nuxeo / Convert to Nuxeo Project.

Code Your Operation

  1. Generate an operation code template:

    yo nuxeo operation
    
  2. You are prompted for a few details:

    ? Operation package: com.bigcorp.contractmgt
    ? Operation class name: ContractUpdater
    ? Operation label: Contract Updater
    
  3. In Eclipse, right-click on the project and press refresh (F5). You get something like this for the operation, in src/main/java:

    package com.bigcorp.contractmgt;
    import org.apache.commons.lang3.StringUtils;
    import org.nuxeo.ecm.automation.core.Constants;
    import org.nuxeo.ecm.automation.core.annotations.Context;
    import org.nuxeo.ecm.automation.core.annotations.Operation;
    import org.nuxeo.ecm.automation.core.annotations.OperationMethod;
    import org.nuxeo.ecm.automation.core.annotations.Param;
    import org.nuxeo.ecm.core.api.CoreSession;
    import org.nuxeo.ecm.core.api.DocumentModel;
    import org.nuxeo.ecm.core.api.PathRef;
    /**
     *
     */
    @Operation(id=ContractUpdater.ID, category=Constants.CAT_DOCUMENT, label="Contract Updater", description="Describe here what your operation does.")
    public class ContractUpdater {
        public static final String ID = "Document.ContractUpdater";
        @Context
        protected CoreSession session;
        @Param(name = "path", required = false)
        protected String path;
        @OperationMethod
        public DocumentModel run() {
            if (StringUtils.isBlank(path)) {
                return session.getRootDocument();
            } else {
                return session.getDocument(new PathRef(path));
            }
        }
    }
    
  4. Time to fill the skeleton and start coding. Here is the final result:

    /**
     * @author mlumeau
     */
    package com.bigcorp.contractmgt;
    import java.util.Calendar;
    import org.nuxeo.ecm.automation.core.Constants;
    import org.nuxeo.ecm.automation.core.annotations.Operation;
    import org.nuxeo.ecm.automation.core.annotations.OperationMethod;
    import org.nuxeo.ecm.automation.core.collectors.DocumentModelCollector;
    import org.nuxeo.ecm.core.api.DocumentModel;
    import org.nuxeo.ecm.core.api.NuxeoException;
    @Operation(id = ContractUpdater.ID, category = Constants.CAT_DOCUMENT, label = "Contract Updater", description = "On a contract, sets the reminder date to three months after its start date.")
    public class ContractUpdater {
    
        public static final String ID = "Sample.ContractUpdater";
        static final String CONTRACT_TYPE = "Contract";
        static final String CONTRACT_SCHEMA = "contract";
        static final String CONTRACT_START = CONTRACT_SCHEMA + ":start";
        static final String CONTRACT_REMINDER = CONTRACT_SCHEMA
                + ":reminder";
    
        @OperationMethod(collector = DocumentModelCollector.class)
        public DocumentModel run(DocumentModel input) throws NuxeoException {
            if (!(CONTRACT_TYPE.equals(input.getType()))) {
                throw new NuxeoException("Operation works only with "
                        + CONTRACT_TYPE + " document type.");
            }
    
            Calendar start = (Calendar) input.getPropertyValue(CONTRACT_START);
            Calendar reminder = (Calendar) start.clone();
            reminder.add(Calendar.MONTH, 3);
            input.setPropertyValue(CONTRACT_REMINDER, reminder.getTime());
            return input;
        }
    }
    

Update the Unit Test

A unit test comes along in src/test/java. You will need it to pass in order to compile and deploy your project.

  1. Replace it with the following code:

    package com.bigcorp.contractmgt;
    import static org.junit.Assert.assertEquals;
    import static org.junit.Assert.assertNotNull;
    import static org.junit.Assert.assertNull;
    import java.util.Calendar;
    import java.util.GregorianCalendar;
    import javax.inject.Inject;
    import org.junit.Test;
    import org.junit.runner.RunWith;
    import org.nuxeo.ecm.automation.test.AutomationFeature;
    import org.nuxeo.ecm.core.api.CoreSession;
    import org.nuxeo.ecm.core.api.DocumentModel;
    import org.nuxeo.ecm.core.test.DefaultRepositoryInit;
    import org.nuxeo.ecm.core.test.annotations.Granularity;
    import org.nuxeo.ecm.core.test.annotations.RepositoryConfig;
    import org.nuxeo.runtime.test.runner.Deploy;
    import org.nuxeo.runtime.test.runner.Features;
    import org.nuxeo.runtime.test.runner.FeaturesRunner;
    @RunWith(FeaturesRunner.class)
    @Features(AutomationFeature.class)
    @RepositoryConfig(init = DefaultRepositoryInit.class, cleanup = Granularity.METHOD)
    // Replace "your.studio.project.symbolic.name"
    // With "studio.extensions.MAVEN-ARTIFACT-ID". You can find your project's MAVEN-ARTIFACT-ID in Settings > Application Information
    // It is likely to start with studio.extensions
    @Deploy({"com.bigcorp.contractmgt.contract-mgt-project-core", "your.studio.project.symbolic.name"})
    public class TestContractUpdater {
          @Inject
          protected CoreSession session;
          @Test
          public void shouldCallTheAutomationChain() {
              // Create a contract, currently stored in memory
              DocumentModel doc = session.createDocumentModel("/default-domain", "my-test-doc", ContractUpdater.CONTRACT_TYPE);
              GregorianCalendar now = new GregorianCalendar();
              doc.setPropertyValue(ContractUpdater.CONTRACT_START, now);
    
              // At this stage, the reminder date should be empty
              assertNull(doc.getPropertyValue(ContractUpdater.CONTRACT_REMINDER));
    
              // We'll save the document in the database
              // That should trigger an event handler that will set the reminder date
              doc = session.createDocument(doc);
              session.save();
    
              // Now we'll check that the reminder date is set as expected
              GregorianCalendar reminder = (GregorianCalendar) doc.getPropertyValue(ContractUpdater.CONTRACT_REMINDER);
              assertNotNull("Reminder date is not set, check your automation chain.", reminder);
              assertEquals("Reminder date is not set in three months from now", now.get(Calendar.MONTH) + 3, reminder.get(Calendar.MONTH));
          }
    }
    
  2. Now replace your.studio.project.symbolic.name with studio.extensions.MAVEN-ARTIFACT-ID. You can find your project's MAVEN-ARTIFACT-ID in Settings > Application Information.

If you try running the test (in Eclipse, right-click on your project and choose Run As, JUnit Test), you will notice that the test fails because we miss things in our Studio project. We need to add them to make the test pass; that's test driven development.

Send the Operation in Studio

  1. Click on the Export Operation button on the Nuxeo Studio tab of the left menu.
  2. Select the Studio project in the drop down menu, and the Eclipse project to look for operation. Then click Next.
    You should now see your operation under the service category in automation. Which means we can now finish our automation chain.

Step 6 - Create Your Chain in Nuxeo Studio

Step 1: Create an automation chain

  1. In the Studio menu Automation > Automation Chains, click on New.
  2. Call your chain ContractUpdater.
  3. Keep the Fetch > Context Document(s) operation and add your own operation, available in Document > ContractUpdater.
    **
  4. Click on Save.

Step 2: Create an Event Handler

You now have to create an Event Handler in order to call your operation when a contract is created.

  1. In the Studio menu Automation > Event Handlers, click on New.
  2. Call the event handler SetReminderDate.
  3. Fill in the creation wizard:
    • Events: Select About to create.
    • Current document has one of the types: Select your document type Contract.
    • Event Handler Execution: Choose your automation chain ContractUpdater.
  4. Click on Save.

Now, you can try it on your server either by running the unit tests, or by testing manually.

Step 7 - Test the Code

The code can either be tested through unit tests, or manually.

Using Unit Tests

  1. In Eclipse, click on the Refresh button on the Nuxeo Studio tab of the left menu ().

  2. Go back to the Project Explorer tab, right-click on your project, and choose Run As, JUnit Test. The tests should now pass.

Using unit tests is the recommended way to ensure a feature is working as expected. Unit tests are triggered automatically whenever you compile your project using Maven, and as such they help you in maintaining a high quality level.

Testing Manually

Creating a Deployment Profile

At this stage we want to create a new default profile, called "My Projects" that includes the contract-mgt-project.

  1. Go into the Nuxeo Server tab (on the bottom right).
  2. Click on the button in the tab toolbar. The button tooltip is "Select projects to deploy on server".
  3. Click on Add.
  4. Enter a name (in the right panel) for your deployment profile. Example: "My Projects”.
  5. In the left panel click on the newly created profile.
  6. In the right panel, check the projects that will be deployed with this profile.
  7. If you want the new profile to be the default deployment profile, check it.
  8. Click on the OK button.
  9. Here is what you should get:
    Now every time you start the Nuxeo server or you click on the Reload projects on server button in the Nuxeo Server tab toolbar, the projects selected in the current profile will be (re)deployed on the server.

Starting the Server

To start the server:

  1. Click on the Run button in the toolbar ().
  2. Wait until the server starts.
  3. When done (i.e when the Stop button is enabled), open a browser and login using the 'Administrator/Administrator' account.

    You can open the browser by clicking the Browse button ().

  4. Click on the Reload projects on server button in the Nuxeo Server tab ().
  5. In Nuxeo Platform, create a new contract with the following information:
    • Title: Maintenance Contract
    • Contract Owner: Nuxeo
    • Starting Date: Choose today's dateYou should end up with something like this:

That's it! You are ready to develop on the Nuxeo Platform.

What to do Next

You should learn to package and deploy your application in a Nuxeo Platform instance.

2 months ago manonlumeau Previous/Next Links: Removed unnecessary qualification for 710
3 months ago Manon Lumeau Fix version override
4 months ago manonlumeau NXDOC-1831: remove opensocial parameters
3 years ago Manon Lumeau 60
3 years ago Manon Lumeau 59
3 years ago Manon Lumeau 58
3 years ago Manon Lumeau 57
3 years ago Bertrand Chauvin 56 | Fix parent version for parent POM
3 years ago Bertrand Chauvin 55 | Fix SDK link
3 years ago Solen Guitter 54 | Update to LTS 2015 SDK
4 years ago Manon Lumeau 53
4 years ago Bertrand Chauvin 52 | Fixed typos
4 years ago Bertrand Chauvin 51 | typo
4 years ago Bertrand Chauvin 50 | typo
4 years ago Bertrand Chauvin 49
4 years ago Bertrand Chauvin 48 | Updated intro
4 years ago Bertrand Chauvin 47 | Complete / Fix / Refactor doc
4 years ago Bertrand Chauvin 46 | Complete doc until step 3
4 years ago Bertrand Chauvin 45 | Rename step
4 years ago Bertrand Chauvin 44 | Update SDK link
4 years ago Bertrand Chauvin 43 | Update prerequisites
4 years ago Julien Carsique 42 | update site URLs
4 years ago Solen Guitter 41 | Fix anchors and page layout
4 years ago Manon Lumeau 40
4 years ago Manon Lumeau 39
4 years ago Solen Guitter 38
4 years ago Manon Lumeau 37
4 years ago Solen Guitter 36
4 years ago Bertrand Chauvin 35 | Updated Nuxeo SDK version to HF12
4 years ago Manon Lumeau 34
4 years ago Manon Lumeau 33
4 years ago Manon Lumeau 32
4 years ago Solen Guitter 31
4 years ago Solen Guitter 30 | Add link to previous step, typos
4 years ago Manon Lumeau 29
4 years ago Manon Lumeau 28
4 years ago Manon Lumeau 27
4 years ago Manon Lumeau 26
4 years ago Manon Lumeau 25
4 years ago Manon Lumeau 24
4 years ago Manon Lumeau 23
4 years ago Manon Lumeau 22
4 years ago Manon Lumeau 21
4 years ago Manon Lumeau 20
4 years ago Manon Lumeau 19
4 years ago Manon Lumeau 18
4 years ago Manon Lumeau 17
4 years ago Manon Lumeau 16
4 years ago Manon Lumeau 15
4 years ago Manon Lumeau 14
4 years ago Vladimir Pasquier 13
5 years ago Anne Jubert 12
5 years ago Manon Lumeau 11
5 years ago Manon Lumeau 10
5 years ago Manon Lumeau 9
5 years ago Manon Lumeau 8
5 years ago Manon Lumeau 7
5 years ago Manon Lumeau 5
5 years ago Manon Lumeau 6
5 years ago Manon Lumeau 4
5 years ago Manon Lumeau 3
5 years ago Manon Lumeau 2
5 years ago Manon Lumeau 1
History: Created by Manon Lumeau

We'd love to hear your thoughts!

All fields required