10.1.6.2

Edit

Create project

Maven archetypes are templates enabling to create projects based on a set of core files quickly. The article contains information on the ODF 2 Full Archetype.

tip

To generate a Maven project from the command line, you must have Java 1.8 and Maven 3.X installed. The preparation steps are as follows:

  1. Download and install the latest JDK 8.X. To verify availability from the command line, use the java -version command.
  2. Download and install the latest Maven 3.X. To verify availability from the command line, use the mvn -version command.

Configure the Maven's settings.xml file located in the C:/User/[USER_HOME]/.m2 folder. If you have already installed IA Cloud Developer, the file should have been updated automatically. Otherwise, make sure it contains the following configuration:

  <servers>
    <!-- Nexus Credentials for Maven to download WF dependencies to build project. Read only permissions are needed for this user -->
    <server>
      <id>wf-dependencies</id>
      <username>odf-user</username>
      <password>Workfusion!5</password>
    </server>
  </servers>
  
  <profiles>
    <profile>
      <id>wf-repo</id>
      <repositories>
        <repository>
          <id>wf-dependencies</id>
          <url>https://repository.workfusion.com/content/groups/dependencies</url>
        </repository>
        <repository>
          <id>wf-archetypes</id>
          <url>https://repository.workfusion.com/content/repositories/archetypes</url>
        </repository>
      </repositories>
    </profile>
  </profiles>
  
  <activeProfiles>
    <activeProfile>wf-repo</activeProfile>
  </activeProfiles>

If you don't have the .m2 folder and settings.xml, create it manually in the C:/Users/[USER_HOME] folder.

If you use custom Nexus—not https://repository.workfusion.com—your default settings.xml file should look like this:

settings.xml

  <servers>
    <!-- Nexus Credentials for Maven to download WF dependencies to build project. Read only permissions are needed for this user -->
    <server>
      <id>wf-dependencies</id>
      <username>odf-user</username>
      <password>*****</password>
    </server>
  </servers>
  
  <profiles>
    <profile>
      <id>wf-repo</id>
      <repositories>
        <repository>
          <id>wf-dependencies</id>
          <!-- URL to nexus with dependencies, like https://repository.workfusion.com/content/repositories/wf-dependencies -->
          <url>dependenciesUrl</url>
        </repository>
        <repository>
          <id>wf-archetypes</id>
          <!-- URL to nexus with archetypes, like https://repository.workfusion.com/content/repositories/archetypes -->
          <url>archetypesUrl</url>
        </repository>
      </repositories>
    </profile>
  </profiles>
  
  <activeProfiles>
    <activeProfile>wf-repo</activeProfile>
  </activeProfiles>

Generate project from command line

The command line is the default way to create an ODF 2 project.

tip

There are also standard Eclipse and IDEA ways to generate the Maven project from archetype. Both these approaches do not support some currently used Maven features. So we recommend creating a project using the command line.

Maven provides two ways of generating new projects from the command line—using either interactive or non-interactive modes.

Use interactive mode

In the interactive mode, perform the following actions:

  1. Start with a simple generate command. Specify the rest of the options:
mvn archetype:generate -DarchetypeGroupId=com.workfusion.odf2 -DarchetypeArtifactId=full-archetype -DarchetypeVersion=X.X.X.X

There are the following entities for Maven to understand which archetype to use:

  • archetypeGroupId=com.workfusion.odf2: group ID of the ODF 2 Full Archetype
  • archetypeArtifactId=full-archetype: artifact ID of the ODF 2 Full Archetype
  • archetypeVersion=X.X.X.X: version of the ODF 2 Full Archetype

The archetype version equals to the ODF 2 version. For more details, refer to the compatibility matrix page.

  1. When you perform the command, specify the following properties:
  • groupId: group ID that uniquely identifies your project across all projects. The group ID should follow Java's package name rules. This means it starts with a reversed domain name you control, for example, org.apache.maven, org.apache.commons, com.mycompany.mylob.
  • artifactId: name of the JAR without a version in Maven archetypes. If you create it, you can choose any name you want with lowercase letters and no strange symbols. In our case, artifactId is used to name the folder where your project is generated. Also, it is used as a prefix in the names of all generated modules. For example, if artifactId is set to invoices, the following six modules are generated:
    • invoices-core
    • invoices-intake-bcb
    • invoices-processing-bcb
    • invoices-submission-bcb
    • invoices-errorhandling-bcb
    • invoices-package
      Finally, artifactId is used to name the JARs built by Maven for each of these modules.
  • version: Maven's version of the project to be created. Do not use SNAPSHOT or dates in it. Follow simple versioning patterns like 1, 5.3, 8.4.5. The Maven version is used to define a Use Case version.
  • package: Java package to be used in the project; by default, Maven suggests the same value as specified in groupId. It is used as a package path (split by points) in your project. Define it like com.mycompany.mylob.
  • usecase-code: Use Case code to be associated with the project. It is used as a technical ID of the Use Case, for example, as a part of the name for each Data Store created for this Use Case. Use only Latin lowercase symbols without spaces, for example, inv, star, kmk, and so on.
  • usecase-name: Use Case name to be associated with the project and used as a human-readable name. Use upper and lower case Latin symbols, spaces, and digits—this is essentially a string for representation. Keep it relatively short (up to 32 characters) to avoid breaking markup on the UI, for example, KYC Latin America.

Also, there are two optional properties with predefined values. You can modify these values any time later within the created project:

  • control-tower-url: URL of the remote Control Tower instance where the Use Case is deployed for testing. The default value is https://instance.workfusion.com. You can easily change it in pom.xml later.
  • nexus-url: URL of the Nexus server. The default value is http://localhost:18081 that is the Nexus server from the local IA Cloud Developer. You can easily change it in pom.xml later.
  1. As soon as all properties are set, Maven asks for confirmation—either yes or no.
    • If all looks good, type Y for Maven to start building a project.
    • If something is set incorrectly and you want to get back to the configuration, type N to get back to the properties setup.
tip

You can change the described above values in IDE once the project is generated. Some values are easy to change (like version, usecase-code, usecase-name) as they are defined in pom.xml. Some are used to generate project modules and Java packages, so that the change will require some refactoring in IDE.

To avoid changing right after the project start, make sure to understand the usage of parameters. In case of wrong naming, it is easier to quickly re-generate a project with correct values.

Use non-interactive mode

The second option is to use the non-interactive mode. In this case, specify all required properties together with the generate command.

mvn archetype:generate -DarchetypeGroupId=com.workfusion.odf2 -DarchetypeArtifactId=full-archetype -DarchetypeVersion=X.X.X.X -DgroupId=com.example -DartifactId=example-project -Dversion=1.0 -Dpackage=com.example -Dusecase-code=uc-code -Dusecase-name=uc-name -Dcontrol-tower-url=https://instance.workfusion.com -DinteractiveMode=false

The archetype version equals to the ODF 2 version. For more details, refer to the compatibility matrix page.

You can see all the properties from the example above in one line. The interactiveMode=false property sets off the interactive mode. In this case, Maven doesn't ask anything and starts building a project straight away. Before doing that, Maven prompts all parameters and values to be used to the console:

[INFO] ----------------------------------------------------------------------------
[INFO] Using the following parameters for creating a project from Archetype: full-archetype:X.X.X.X
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: artifactId, Value: example-project
[INFO] Parameter: version, Value: 1.0
[INFO] Parameter: package, Value: com.example
[INFO] Parameter: packageInPathFormat, Value: com/example
[INFO] Parameter: package, Value: com.example
[INFO] Parameter: version, Value: 1.0
[INFO] Parameter: usecase-code, Value: uc-code
[INFO] Parameter: groupId, Value: com.example
[INFO] Parameter: control-tower-url, Value: https://instance.workfusion.com
[INFO] Parameter: nexus-url, Value: http://localhost:18081
[INFO] Parameter: artifactId, Value: example-project
[INFO] Parameter: usecase-name, Value: uc-name
caution

During the Archetype generation, you may experience an exception related to Groovy code generation with Grapes.

View the exception

[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 34.816 s
[INFO] Finished at: 2021-06-21T17:07:59+02:00
[INFO] ------------------------------------------------------------------------
[ERROR] Failed to execute goal org.apache.maven.plugins:maven-archetype-plugin:3.1.2:generate (default-cli) on project standalone-pom: startup failed:
[ERROR] General error during conversion: Error grabbing Grapes -- [download failed: org.slf4j#slf4j-api;1.6.6!slf4j-api.jar]
[ERROR]
[ERROR] java.lang.RuntimeException: Error grabbing Grapes -- [download failed: org.slf4j#slf4j-api;1.6.6!slf4j-api.jar]
[ERROR]         at sun.reflect.NativeConstructorAccessorImpl.newInstance0(Native Method)
[ERROR]         at sun.reflect.NativeConstructorAccessorImpl.newInstance(NativeConstructorAccessorImpl.java:62)
[ERROR]         at sun.reflect.DelegatingConstructorAccessorImpl.newInstance(DelegatingConstructorAccessorImpl.java:45)
[ERROR]         at java.lang.reflect.Constructor.newInstance(Constructor.java:423)
[ERROR]         at org.codehaus.groovy.reflection.CachedConstructor.invoke(CachedConstructor.java:83)
[ERROR]         at org.codehaus.groovy.reflection.CachedConstructor.doConstructorInvoke(CachedConstructor.java:77)
[ERROR]         at org.codehaus.groovy.runtime.callsite.ConstructorSite$ConstructorSiteNoUnwrap.callConstructor(ConstructorSite.java:84)

To fix the issue, clean up your local workstation Grapes cache by deleting the C:\Users\[USERNAME]\.groovy\grapes folder's contents.

← Backward compatibilityNext →