Creating a Project using Maven and the Archetype

The smart bundle development involves development of a Digital Service application or a smart library. All the code for an application or a library is packaged and deployed as a bundle deployment package. A bundle has a project structure in the development environment. 

The following video (5:41) provides details on how to create a maven project using BMC Helix Platform SDK and IDE and how to deploy the project to your system.

The video shows an older version of BMC Helix Platform. The previous product name was BMC Helix Innovation Suite. Although there might be minor changes in the UI, the overall functionality remains the same.

 https://youtu.be/_aXeUOGRlNY

To create a new project

To create a new application project or smart library project, use the Maven archetypes (simple archetype or lib archetype) with the BMC Helix Platform SDK. For your projects, decide where you want your project code to reside. We recommended that you do not place the project code at the BMC Helix Platform SDK location. For example, you can create a new directory projects in the root directory.

1. On the command prompt, navigate to the directory to create project.
   For example: C:\projects

2. Create a project for application development or library development.

   • If you want to create a project for application development, run the following command:

     mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-simple -DarchetypeCatalog=local
     

     where,

     Archetype Argument	Description
     -DarchetypeGroupId=com.bmc.arsys	Maven uses BMC archetypes
     -DarchetypeArtifactId=rx-sdk-archetype-simple	Selects the simple application archetype. This sets the POM file to create an application package and generates a working UI.
     -DarchetypeCatalog=local	Uses only the local catalog

   • If you want to create a project for library development, run the following command:

     mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-lib -DarchetypeCatalog=local

     where,

     Archetype Argument	Description
     -DarchetypeGroupId=com.bmc.arsys	Maven uses BMC archetypes
     -DarchetypeArtifactId=rx-sdk-archetype-lib	Selects the library archetype. This sets the POM file to create a library package and does not generates a working UI.
     -DarchetypeCatalog=local	Uses only the local catalog

     For more information on Maven archetype, see  Maven archetype plugin in Maven documentation.

3. The command (for library archetype or simple application archetype) starts the archetype plugin in interactive mode and prompts for the property values.

   Enter the values for the following properties:

   Property	Description	Sample values for application development	Sample values for library development
   groupId	Project group ID. The ID usually follows the naming conventions of Java package names. Important: You must provide the Developer ID as the groupID value. Warning: The com.bmc namespace is reserved for BMC-specific bundles. Make sure that you do not use this namespace in your groupId.	com.example	com.example
   artifactId	Project ID that is used as a part of filename. It usually has a short name as the project is already name spaced by the groupId. Notes: The artifactId cannot be a combination of: '-' (hyphen) and numeric character. For example, work-order-lib-12 is not a valid artifactId. Upper case and lower case letters. For example, Work-Order-Lib is not a valid artifactId. For more information, see Naming conventions in the Apache Maven documentation.	suggestion-box	work-order-lib
   version	Project version. You must provide the value in the following format: <major version>.<minor version>.<incremental version>-<qualifier> See Version number rules in Maven documentation and Releasing a version of your bundle.	1.0-SNAPSHOT	1.0-SNAPSHOT
   package	Default Java package for the project. The default value is groupId value.	com.example	com.example
   name	Friendly name of the bundle. This is used by the archetype to display the name of the application on the login page and in the BMC Helix Innovation Studio.	Suggestion Box	Work Order

4. Confirm the configuration of all the properties.

5. If any dependencies on other smart bundles, add the dependencies. See Using components from another developer's Digital Service application or library.
6. If any third party dependencies, add the third party dependencies. See Using code from open source.

To set up the development server environment properties in the project pom.xml file

After you create the application (or smart library) project, you must modify the user credentials in the project pom.xml file.  

1. Open the parent pom.xml file located in project folder. For example, projects\work-order-lib\pom.xml.
   

2. Modify the properties section that specifies the environment information provided with your Development Server instance.

   <!-- START: Bundle specific configuration. Verify and Change as per environment -->
    
      <developerUserName>developer</developerUserName>
      <developerPassword>mydeveloperpw</developerPassword>
    
      <!-- Server name with Jetty port. -->
      <webUrl>https://developer.innovate.bmc.com</webUrl>
    
   <!-- END: Bundle specific configuration.-->

   where, developerUserName is developer user that you create while requesting a sandbox. You do not need to use the domain name developer.com.

   Note

   You must provide the webUrl of your sandbox.

3. If you plan to use the Grunt utility for active debugging of Javascript, you must add the correct api-host in the parent project bundle\bundle.conf.json file. By default, it is generated as localhost, you must update it to match your development server host. The host typically remains as localhost that is where the JavaScript source code resides.  For example:

   "options": {
               "livereload-port": 39005,
               "skip-tests": "true",
               "skip-validation": "true",
               "api-host": "developer101.innovate.bmc.com",
               "api-port": 443,
               "api-https": true,
               "host": "localhost",
               "port": 9005
   },

4. Save the changes.

After you create a new project, add the dependencies and define the user (user credentials in the pom.xml file), you should create a deployment package and deploy the package to the BMC Helix Platform server. See Deploying your Digital Service application for the first time to start working in BMC Helix Innovation Studio.

To set up dependencies that are needed for your bundle

The dependencies on the other bundles are declared in the bundle\pom.xml file. If your application or smart library intends to make use of workflows for approvals, assignments, or the Foundation library, add the dependencies in the bundle\pom.xml, so that these capabilities can be tailored after the application is deployed. You can use the following content for the rx-sdk.bundledependencies tag. The syntax is bundleid;version using commas to separate each bundle.

	<properties>
		<!-- Comma separated Bundle Dependencies with version.  -->
		<rx-sdk.bundleDependencies>standardlib;${rx-sdk.version},com.bmc.arsys.rx.approval;${rx-sdk.version},com.bmc.arsys.rx.assignment;${rx-sdk.version},com.bmc.arsys.rx.foundation;${rx-sdk.version}</rx-sdk.bundleDependencies>
	</properties>

Projects created by the archetype

The Maven archetype creates the following projects:

The application bundle project and the deployment package project have their own build system pre-generated in the form of a Maven POM file. You can import these projects in Eclipse to customize and debug the application or library.

<mirror>
<id>central-over-https</id>
<mirrorOf>central</mirrorOf>
<name>Maven Central Repository</name>
<url>https://repo.maven.apache.org/maven2</url>
</mirror>

Smart bundle attributes

Smart bundle (application or smart library) attributes and properties are defined in the project pom.xml file and bundle pom.xml file respectively.

The following table describes the project pom.xml file and bundle pom.xml file:

<properties>
    <rx-sdk.bundleId>${project.groupId}.${project.artifactId}</rx-sdk.bundleId>
    <rx-sdk.bundleName>${project.artifactId}</rx-sdk.bundleName>
    <rx-sdk.bundleFriendlyName>${project.name}</rx-sdk.bundleFriendlyName>
    <rx-sdk.bundleDescription>${project.description}</rx-sdk.bundleDescription>
    <rx-sdk.bundleDeveloperId>${project.groupId}</rx-sdk.bundleDeveloperId>
    <rx-sdk.bundleDeveloperName>${project.groupId}</rx-sdk.bundleDeveloperName>
    <rx-sdk.bundleIsApplication>true</rx-sdk.bundleIsApplication>
<properties>

<plugin>
    <groupId>org.apache.felix</groupId>
    <artifactId>maven-bundle-plugin</artifactId>
    <version>${maven-bundle-plugin.version}</version>
    <extensions>true</extensions>
    <configuration>
        <instructions>
            <Bundle-Name>${rx-sdk.bundleName}</Bundle-Name>
            <Bundle-SymbolicName>${rx-sdk.bundleId}</Bundle-SymbolicName>
            <Bundle-Activator>com.mygroupid.bundle.MyApplication</Bundle-Activator>
            <Import-Package>*;resolution:=optional</Import-Package>
            <Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
            <Bundle-Description>${rx-sdk.bundleDescription}</Bundle-Description>
            <Bundle-Vendor>${rx-sdk.bundleDeveloperId}</Bundle-Vendor>
            <RxBundle-DeveloperName>${rx-sdk.bundleDeveloperName}</RxBundle-DeveloperName>
            <RxBundle-FriendlyName>${rx-sdk.bundleFriendlyName}</RxBundle-FriendlyName>
            <RxBundle-IsApplication>${rx-sdk.bundleIsApplication}</RxBundle-IsApplication>
        </instructions>
    </configuration>
</plugin>

The following table describes the smart bundle properties:

Where to go from here

Deploying your Digital Service application for the first time to start working in BMC Helix Innovation Studio