Releasing a version of your bundle

When you create a Digital Service application project using the Maven archetype, your application is created with bundle version 1.0-SNAPSHOT and you do the development work with same version. You may need to release this bundle and start the development work on a new version. For example, you want users to start using your application version 1.0 and you need to start with the development of your application 1.1.

To release an initial version

The following image shows the process to release the initial version of an application:T

Release app version process.png

Exporting bundle

Ensure that your definitions are up to date and run the following command to export your bundle:

projects\my-proj> mvn generate-resources -Pexport

Stopping bundle version 1.0 development

If you are using any sources in Source Control, branch or label your sources. Ensure that you do not modify definitions for version 1.0. Remove the bundle from your BMC Helix Platform development instance, using the following command:

projects\my-proj> mvn com.bmc.arsys:rx-sdk-maven-plugin:undeploy -N

Note that this is a required step.

Changing bundle to a released version

Note

If you have created or upgraded your application using BMC Helix Platform SDK release 17.08 or earlier, edit the /package/pom.xml file and update the <execution> tag to make the following changes:

<build>
   <plugins>
       <plugin>
            .
            .
           <executions>
               <execution>
                   <id>update-def-file</id>
                   <phase>generate-sources</phase>
                   <goals>
                       <goal>update-def-file</goal>
                   </goals>
               </execution>
               <execution>
                   <id>add-manifest</id>
                   <phase>generate-resources</phase>
                   <goals>
                       <goal>add-manifest</goal>
                   </goals>
               </execution>
                .
                .
                .
           </executions>
       </plugin>

Update your POM files using the following command:

projects\my-proj> mvn versions:set -DnewVersion=1.0.0

After you run the command, you receive a success message. The following snippet illustrates a sample message:

[INFO] Updating project com.myco:my-proj
[INFO] from version 1.0-SNAPSHOT to 1.0.0
expression: rx-sdk.groupId no value
expression: rx-sdk.groupId no value
expression: rx-sdk.groupId no value
[INFO]
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO]
[INFO] my-proj-all ....................................... SUCCESS [ 54.270 s]
[INFO] My Project ........................................ SKIPPED
[INFO] my-proj-package ................................... SKIPPED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

The version is created in the following format:

For example, 17.11.0, 17.11.0-SNAPSHOT, 1.0-SNAPSHOT, 1.0.0.RELEASE.

Packaging

Ensure that all the sources, and the renamed definition files, are correctly packaged together in the deployment zip file. Run the following command:

projects\my-proj> mvn clean install

The compiled deployment package is present at projects\my-proj\package\target\com.myco.my-proj-1.0.zip. The com.myco.my-proj-1.0.zip file contains the following files:

db
- record
  - <record-definition-name1>.def
  - <record-definition-name2>.def
  - <record-definition-name3>.def
  - <record-definition-name3>.options
  - <record-definition-name3>.data
  - <record-definition-name3>.delete
- process
  - <process-definition-name1>.def
  - <process-definition-name2>.def
- rule
  - <rule-definition-name>.def
- association
- view
  - <view-definition-name>.def
- named-list
  - <named-list-definition-name1>.def
  - <named-list-definition-name2>.def
- localized-string
  - <localized-strings.def>
- configuration.data
- role.data
code <jar file>
manifest file

Releasing

To provide the bundle to QA for black-box or integration testing, or to a pre-production shared system, make the package file projects\my-proj\package\target\com.myco.mypackage.my-proj-1.0.zip available to administrators for the next phase of delivery. Now you are done with bundle version 1.0.

Guidelines on creating a new version of an application

When you upgrade your application to a new version, ensure that the modifications made to the new version of your application do not affect the functionalities of the existing application version. The following table lists the guidelines to follow:

Guideline	Description
Add new functionality that is implemented by using new definitions	You can create a new functionality for your application by creating the following new definitions and new code modules: Record definitions and record definitions that extend Foundation record definitions Association definitions View definitions and view components Process definitions Java based services, data page queries, commands, and REST resources Named list definitions Specific rule definitions Roles Configuration settings Bundle data
Your application code changes must be backward compatible	View components You can add new properties that are not mandatory. You must not change any JavaScript method that is user facing. You must provide opt in consumption of the UI changes by adding configuration settings in your application. Java based services You must not delete the existing interfaces. You must not add new mandatory parameters. You must not modify a service that can affect the application configuration.
Your existing non customizable definitions changes must be backward compatible	Record definitions You must not delete record definition or fields. You must not change the field ID values. View definitions You can add parameters. You can add, modify, or delete view components. Process definitions Before you delete process activities, ensure that the activities are not used process instances. Before you modify properties of a process activity, ensure that are dependent on other definitions such as rule definition and process definitions. You must not delete a User Task or a Receive Task. If you add new activities, your process logic should must consider the activity results as optional. Rule definitions You must not add new rule definitions You must not modify the existing rule definitions that directly interact with business logic. You can modify the rule definitions that are independent on other definitions and do not affect application data and definitions.
You must not modify the existing definitions and data that can be customized all the times.	Named list definitions You must not delete or modify the existing named list definitions. You modify specific named list definitions that do not affect the users. Association definitions Do not modify or delete the existing association definitions. Roles Do not modify or delete the existing roles. Configuration settings Do not modify or delete the existing configuration settings. Bundle data Before you delete bundle data, ensure that the bundle data is independent on the customizable definitions.

To release a new version

Perform the following steps to release a new version of your application:

Update your POM files using the following command:
projects\my-proj> mvn versions:set -DnewVersion=1.1.0-SNAPSHOT
The new version is created in the following format:
<major version>.<minor version>.<incremental version>-<qualifier>
For example, 17.11.0, 17.11.0-SNAPSHOT, 1.0-SNAPSHOT, 1.0.0.RELEASE.
Note
BMC Helix Platform uses <major version>, <minor version>, and <incremental version> parameters for versioning an application.
- If you change the <majorversion> or <minor version> parameter in an application version, a new version of your application is created.
- If you change the <incremental version> parameter in an application version, the existing version of your application is updated.
Deploy the new version by using the following command:
projects\my-proj> mvn clean install -Pdeploy

By default only two versions of an application can be deployed on a system. If you deploy a third version, the following error is generated:

9164: Maximum number of allowed versions exceeded.

BMC SaaS Operations must undeploy the oldest version. If the latest version is undeployed, all versions of the application are undeployed from the system.