Orientation

images/docs/download/attachments/668429038/developers.jpg

As a developer you build solutions to solve complex business problems. When you first start a development project, you should thoroughly understand the business need, and design a solution to meet that need. Fortunately, we've already done the heavy lifting for you.

The Innovation Suite is an end-to-end framework that provides the enterprise features you need. Applications built using the Innovation Suite begin with an enterprise ready data management back end, authentication model, and security framework, leaving you with more time to design and develop solutions to meet your business goals and objectives.

In this module, you will review the business use case and application design to build a solution that touches upon many of the capabilities of the Innovation Suite. Then you will deploy the base application into Innovation Studio. Review this section as a detailed reference for the application design, and then follow the instructions for deploying the base application into Innovation Studio.

Application scenario

In our organization, work needs to be done. This involves someone requesting the work, someone approving the work, and someone, let's call them "engineers", implementing the work as a set of tasks that are assigned to them. Let's say that the requirements are as follows:

  • A "requestor" user submits a new work order to the system directly.

  • A "manager" can review new work orders before formal approval is requested.

  • There is some very configurable approval process that should happen on reviewed work orders before work starts.

  • There is some very configurable process for generating tasks and assigning them to an "engineer".

  • Engineers can view tasks that are assigned to them and update their status.

Work order application design

Usually a good place to start with the design of an enterprise application is by defining the domain data objects. For this tutorial, we will keep this fairly simple.

  • There are the following roles:

    • Work Manager
    • Work Implementor
  • We know we have a Work Order construct.

    • Has a description, contract
    • Has a lifecycle status of New, Reviewed, Assigned, Work in Progress, Cancelled, or Completed.
    • Has zero or more Work Task instances associated with it.
  • Work Task

    • They in fact are "part of" the Work Order (meaning that when the Work Order is deleted, the associated Work Task objects are deleted as well). This can be called a "direct" association.
    • Has a lifecycle status that includes New, Work in Progress, and Completed
  • Fulfillment of a work order is tracked using a business process that involves Work Tasks. We need to be able to support many different kinds of fulfillment which can be "tailored" after the application is deployed. This means that the actual fulfillment process needs to be pluggable into the overall Work Order process.

  • We have a Requestor who

    • Is one of the Person types in our enterprise.
    • Can be associated with multiple Work Order instances, but they do not "own" them.
    • Can be used to populate a requestor field
    • A query of Person should return Work Order Requestor instances.
  • The person who "owns" a work order is considered an "Agent" and is also based on Person.

  • The person who is assigned to work on a task is also an "Agent".

Data model: records and associations

To translate that into Innovation Suite constructs (Records, Associations, and Named Lists), the data model for the whole project looks like this:

images/docs/download/attachments/667810411/design-data-model.png

Note that some of the objects are part of other bundles, which implies a dependency on the Task Manager reference application.

Business logic: designing processes and rules

As an application developer, we cannot determine every single behavior of this highly configurable system, because this will inevitably be configured differently by every customer. However, we can lay down the "bare bones" business process that will be tied to the fulfillment of a work order as a set of tasks.

For this very basic process, we will not get too fancy with task creation. Instead we will delegate to another process dynamically, which by default will be an extremely simple one that creates a single task and associates it with the work order. Later, business analysts can easily create complex fulfillment processes as part of tailoring the application to the company's needs.

images/docs/download/attachments/667810411/design-business-logic.png

User interface: view designer components

Just as we are keeping the data model and business logic simple, we will also have a rudimentary UI at first. The uses cases supported are:

  • Look at the list of Work Orders

  • Look at the list of Work Tasks (along with some joined Work Order information)

  • Create a new Work Order

  • Edit a Work Order, which includes

    • View / modify the details, including marking the status as "Reviewed"
    • View associated Work Task instances (created once the process reaches that point) in a list
    • Edit associated Work Task instances
  • Go to the approval console and approve pending items

  • This flow will require creating at least 5 views. It can be diagrammed like this:

images/docs/download/attachments/667810411/design-ui-flow.png

Publishing: packaging bundles for deployment

Finally, part of the design is to identify what deployment packages should be created. Each one will either be supplied as part of the platform install, or created as new project using an appropriate Maven archetype.

For each package, we can take an inventory of what kinds of definition objects, as well as special coding like UI components and Java services and REST resources, that will be needed. This creates a roadmap and high-level architecture for development of the solution.

images/docs/download/attachments/667810411/design-packaging.png

Summary

Throughout the following exercises, you can and should refer back to these requirements and design notes as a guide to understand why the steps are being taken. This will help getting lost during some of the detailed steps that are part of the implementation.

Required development tools

To complete the lessons, you will need the following software and applications to be installed on your system.

Software or application

Where to find

Comment

Java JDK 1.8

Oracle Java SE/JDK downloads

Must be included in your system path.

BMC Remedy AR System server

BMC Remedy AR System server and database are installed in the Amazon Web Services (AWS) instance

Runtime engine

BMC Remedy Mid Tier

You can use a mid tier on other environment and point it to the development environment.

BMC Remedy Mid Tier is required to create a developer user account.

Apache Maven 3.3.9

Apache Maven downloads

Must be included in your system path.

Eclipse 4.6

Your choice of development environment

Recommended: Eclipse IDE, M2Eclipse plugin (may be provided with Eclipse)

Node.js 6.2.1

Nodejs.org downloads

Must be included in your system path.

Karma and Grunt

Grunt installation instructions

Karma - Test runner for JavaScript Grunt - JavaScript task runner for running and debugging custom web applications

Innovation SDK

com.bmc.arsys.rx.sdk-9.5.00-SNAPSHOT.zip

Contains the initial application and library modules required by this tutorial.

Web browser

Your choice

Recommended: Google Chrome, for its developer tools.

For detailed setup instructions, see the Developer Guide at Setting up your IDE and installing Innovation SDK.

Gaining access to Innovation Studio

As a developer, you can request access to the cloud-hosted Innovation Studio environment by filling out your information at developers.bmc.com, where you can deploy your projects and build the functionality to meet your use case.

Once you have been assigned a development sandbox, check:

  • That you can connect to Innovation Studio (Is there a local workstation <-> Innovation Studio (cloud) configuration?

  • That a developer user account as been created

Creating a developer user

In the instance a developer user has not been created in your Innovation Studio sandbox, follow these steps.

  1. Log in to Innovation Studio using the credentials supplied in your email invitation.

  2. Go to Administration > Configure My Server > People > Manage AR User Accounts.

  3. Give the developer user Administrator group access.

    images/docs/download/attachments/668429053/innovation-studio-create-user.png

  4. Create a developer user for yourself, for example, in this tutorial we are using:

- Login Name: Seth

- Password: Seth

Summary

At this point, the developer account is set up in Innovation Studio. You must deploy the Task Manager application as an initial framework for you to continue building your project.

Setting up your environment

You may be using a preconfigured development environment that already has all the necessary developer tools and AR Server runtime. In this case, this Lesson can be skipped. Or, you can review it to get an idea of what tools are required to exist in the environment.

Developer ID and namespace

Before getting started, you must record the Developer ID you have been assigned on the Development Server, and change the Developer ID temporarily to com.example. The com.example developer identity is used in all the working examples and sample code used in this tutorial. The bundles you deploy using the com.example developer identity will be deployed into the com.example namespace.

After you have completed the tutorial, you can restore the Developer ID you were assigned. You should not deploy any bundles in the com.example namespace which are not part of the learning modules. You should use your own developer identity to produce applications into your own namespace.

Changing the developer ID

Change the Developer ID field using the Mid-Tier AR System Administration Console.

  1. Log onto the Mid-Tier using the Administrator credential supplied with your Development Server.

    In most cases, the HTTP-TOMCAT-PORT port is 8080.

    http://DEVELOPMENT-SERVER-HOST:HTTP-TOMCAT-PORT/arsys/

  2. Click the blue Applications button on the left to open the menu.

  3. Select AR System Administration > AR System Administration Console.

  4. Go to Common Server Configuration > General > Server Information.

  5. Open Configuration.

    image2016-12-1_16_20_12.png

  6. Take note of the assigned Developer ID.

  7. Change the Developer ID to com.example.

Note: Once again, before you build any applications, be sure to restore the Developer ID to the value assigned to your company.

Preparing the SDK

You must have access to a command line terminal in order to build the initial bundle and deploy the package into your Innovation Studio sandbox.

Note: After installing tools, be sure to close any command windows that may not have the updated path and/or system variables.

  1. On your development workstation, locate the Innovation SDK archive.

  2. Using 7zip or another extraction tool, extract the SDK folders into your development environment (our example uses <SDK Location>).

  3. Initialize the Maven repository with the SDK libraries. Enter the following commands:

    cd <SDK Location>\lib
    lib> mvn clean install
    

    The result should look similar to the following:

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 23.928 s
    [INFO] Finished at: 2016-04-07T10:12:39-12:00
    [INFO] Final Memory: 9M/491M
    

Notes:

  • If you are planning to develop using multiple versions of Innovation Suite, it is a good idea to keep the SDK in a folder that is dedicated to a particular instance of Innovation Suite.

  • Before using the Maven commands that are available with the SDK, you must first initialize the Maven repository using the matching SDK.

Testing the development environment

To test the software that is installed in your environment, run the following commands. The output on your system may vary depending on exactly where things are installed.

Checking Java

> java -version
java version "1.8.0_65"
Java(TM) SE Runtime Environment (build 1.8.0_65-b17)
Java HotSpot(TM) 64-Bit Server VM (build 25.65-b01, mixed mode)

Checking Maven

> mvn -v
Apache Maven 3.2.1 (ea8b2b07643dbb1b84b6d16e1f08391b666bc1e9; 2014-02-14T05:37:52-12:00)
Maven home: C:\Innovation Suite\tools\apache-maven-3.2.1-bin\apache-maven-3.2.1\bin\..
Java version: 1.8.0_45, vendor: Oracle Corporation
Java home: c:\program files\java\jdk1.8.0_45\jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows server 2008", version: "6.0", arch: "amd64", family: "dos"

Checking Node.js

> node -v
v6.2.1

Checking Grunt CLI

grunt -version
grunt-cli v1.2.0

Deploying required application modules

The Work Order library depends on framework libraries, which are always deployed with the server, and the Task Manager reference application, which is not. If it has already been deployed, you can skip this step.

Otherwise you can build and deploy Task Manager yourself. You must have already installed the SDK.

  1. Set up the correct environment information in the task-manager\pom.xml file as documented in the Set the Development Server environment properties in the project's pom.xml file section of Creating a Project using Maven and the Archetype.

  2. Build the Task Manager application from its sample code. NOTE: do NOT use the -Pdeploy option here because the developer-id on your Development Server will not match task-manager. task-manager> mvn clean install

  3. Deploy it to your Development Server using the bundledeployment tool and your admin credential. This is required because this project has a different developer-id as noted above.

    task-manager>java -jar ..\..\lib\com.bmc.arsys.rx.bundledeployment-9.5.00-SNAPSHOT.jar -o deploy 
    -l package\target\com.example.taskmanager-1.0-SNAPSHOT.zip -u ADMIN -p ADMINPW           
                    -r http://HOST:PORT
    

Summary

To verify the bundle deployment, refresh Innovation Studio in your browser. The Task Manager application should appear in the workspace.

Cleaning up from previous tutorials

If by chance there are already bundles deployed in the workspace called Work Central and Work Order, and you wish to start from scratch to run the tutorial, then these bundles should be removed from Innovation Studio. When you remove bundles, all data associated with the bundles is removed as well.

Export the deployment package completely

  1. Export work-order-lib <projects>\work-order-lib> mvn -Pexport package

  2. Export work-central-app <projects>\work-central-app> mvn -Pexport package

Undeploy the bundles from Innovation Studio

  1. In a command shell, go to the sdk lib folder.

    Execute the following undeployment commands, replacing the correct host and port for Innovation Suite in each:

  2. Undeploy work-order-lib <sdk location>\lib> java -jar com.bmc.arsys.rx.bundledeployment-9.5.00-SNAPSHOT.jar -o undeploy -n com.example.work-order-lib-1.0-SNAPSHOT.zip -u Seth -p Seth -r http://SERVERNAME:PORT

  3. Undeploy work-central-app <sdk location>\lib> java -jar com.bmc.arsys.rx.bundledeployment-9.5.00-SNAPSHOT.jar -o undeploy -n com.example.work-central-app-1.0-SNAPSHOT.zip -u Seth -p Seth -r http://SERVERNAME:PORT

    Each time you run the undeploy command, you trigger a process that works in the background which can take up to a minute or two to complete.

    See the following sample output from running the command to remove work-order-lib:

    \com.bmc.arsys.rx.sdk-9.5.00-SNAPSHOT\lib&gt;java -jar com.bmc.arsys.rx.bundledeployment-9.5.00-SNAPSHOT.jar -o undeploy -n com.example.work-order-lib-1.0-SNAPSHOT.zip -u Seth -p Seth -r http://localhost:8008 14:08:37.704 [main] INFO c.b.a.r.d.b.BundleDeploymentTool - Operation is undeploy 14:08:37.954 [main] INFO c.b.a.r.d.common.BaseApplication - Authenticating User Seth ... 14:08:38.335 [main] INFO c.b.a.r.d.common.BaseApplication - User [Seth] is authenticated 14:08:38.340 [main] INFO c.b.a.r.d.bundle.UndeployApplication - Deploy Tool Utility Run Start time: Wed Sep 28 14:08:38 PDT 2016 14:08:38.340 [main] INFO c.b.a.r.d.bundle.UndeployApplication - UnDeploying the package com.example.work-order-lib-1.0-SNAPSHOT.zip 14:08:38.403 [main] INFO c.b.a.r.d.bundle.UndeployApplication - response status:204 14:08:38.404 [main] INFO c.b.a.r.d.bundle.UndeployApplication - The package is successfully staged (*not undeployed) and scheduled for undeployment. 14:08:38.406 [main] INFO c.b.a.r.d.bundle.UndeployApplication - ****************************************************** You may use the below status URI to check undeployment status under a valid logged in session. STATUS URI: http://localhost:8008/api/rx/application/bundle/deploymentpackage/com.example.work-order-lib ****************************************************** 14:08:38.407 [main] INFO c.b.a.r.d.bundle.UndeployApplication - **** Starting to poll completion status of the scheduled undeployment. This may take few minutes.. **** 14:09:38.547 [main] INFO c.b.a.r.d.common.BaseApplication - UnDeployment completed. UnDeployment Status as below : DeploymentPackage [packageDeployStatus=Undeployed, packageName=com.example.work-order-lib,packageVersion=1.0-SNAPSHOT, currentServersInSync=true, newlyAddedServers=[], jarToServerDeployStatusMap={WIN-COMPNAME-32.DOMAIN.com=Undeployed}] 14:09:38.547 [main] INFO c.b.a.r.d.bundle.UndeployApplication - Total time taken in msec completing the Deploy Tool run: 60211 msec ************************** Final Status:Undeployed ************************** Deploy Tool Run End time: Wed Sep 28 14:09:38 PDT 2016

Verify undeployment

  1. Bring up Innovation Studio on the development machine.

  2. Verify that the bundle no longer appears.

  3. If the bundle still appears, refresh the browser. The process may still be working in the background.

Summary

At this point you are ready to dive in and start creating libraries and applications.

Conclusion - Orientation

At this point you have a clean Innovation Studio environment and a project workspace, and are ready to dive in and start creating libraries and applications.