BMC Learning Lab - Module 1

Table of Contents

Module 1 - Building the application

In this module, you will turn the conceptual design discussed in the Orientation module into a working application. The process described shall be common to most Innovation Suite development projects, where you build and deploy a libraries into Innovation Studio, and extend all the components visually to complete a working application.

Creating the work order library and data model

In the first lesson, we will create a very simple library that includes a Work Order abstraction and a few views that trigger basic CRUD operations, such as list, create, and edit. We will hold off on creating an application for the moment since the application will use this library.

Generating and deploying the Work Order library

Before you can build an application, you must first deploy the required bundles into Innovation Studio. The Work Order management application project includes source code to create the required library and application bundles.

  1. Before getting started, be sure you have temporarily set the developer-id on the Development Server to com.example as mentioned in the setup instructions under Setting up your environment. Otherwise, deployment from a development environment will fail. Be sure to take a note of the correct developer id that was there in order to restore this after you are finished with the tutorial.

  2. Within your development environment, create a folder to contain your projects, if it does not already exist. You can give it any name. For example,

    mkdir c:\projects

  3. From your projects folder, run the maven archetype command as documented in Creating a Project using Maven and the Archetype.

    projects>mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-lib

    The archetype command syntax is documented at Creating a Project using Maven and the Archetype in the Innovation Suite online documentation.

  4. Accept defaults when appropriate but use these specific values when asked. Note that while you use your Developer ID as the groupId, you should have modified it to com.example as noted above, on the Development Server as part of setting up for this tutorial. So, for the tutorial purposes only, please use com.example as the groupId.

    Archetype Prompt Value to Provide
    Define a value for property 'groupId': : com.example
    Define a value for property 'artifactId' work-order-lib
    Define a value for property 'version': 1.0-SNAPSHOT (Enter to accept default)
    Define a value for property 'package': com.example (Enter to accept default)
    Define a value for property 'name': : Work Order
    Confirm properties configuration:groupId: com.example artifactId: work-order-lib version: 1.0-SNAPSHOT package: com.example name: Work OrderY: (Enter to accept default)
  5. Update the \projects\work-order-lib\pom.xml file to properties that are environment specific, using the information provided with your Development Server as documented in Creating a Project using Maven and the Archetype.

  6. One last check: make sure that the bundle\pom.xml (not the package\pom.xml) specifies a dependency on Approvals as documented in Creating a Project using Maven and the Archetype.

  7. Now, build and deploy the project. This can take a long time for the first build.

    projects> cd work-order-lib 
    work-order-lib>  mvn clean install -Pdeploy
    

Summary

After the system responds with build success, verify that the bundle you deployed appears inside Innovation Studio as a library. Open the URL (use your specific SERVERNAME:PORT).

http://SERVERNAME:PORT/innovationstudio/index.html

Should result in the following image

images/docs/download/attachments/668429636/innovation-studio-workspace-example.png

If the library does not appear, the background process may need more time to complete. Refresh your browser to see the library appear.

Creating the supporting Named Lists

A named list is a reusable set of values that you can attach to a record field, to give the user a choice of values to select for that field. Named list definitions have the following advantages:

  • Reduces input error and ensures consistency by constraining the input to a specified set of valid options.

  • Enhances the speed of data entry through type to complete a known value rather than a free-form value.

Create the Named Lists early on so that you can use them to create the primary Record Definitions more easily. The lists you define will be tied to fields of the Work Order in a later step.

For more information about named lists, see Working with named lists in the BMC Innovation Studio online documentation.

Creating the Registered Fulfillment record

The Registered Fulfillment record will be used as the data source for the Named List that provides the selection for configuring fulfillment processes.

  1. In Innovation Studio, navigate to the Work Order library.

  2. In the Records tab, create a new Regular Record Definition called Registered Fulfillment.

  3. Select the field whose Field Name is Description (not to be confused with the optional "Description:" area of the of field properties panel that appears for every field). Change the Name of the field from Description to Process Name. The actual process name that will be invoked as part of the workflow will be stored in this field.

  4. Add a new Text field called Fulfillment Type and make it required. This will be the visible label when users are choosing the kind of fulfillment they want.

    images/docs/download/attachments/668429643/work-order-registered-fulfillment.png

  5. Save and close the Record Designer.

Creating sample fulfillment data

  1. Select the checkbox beside Fulfillment Type (the record you just created) and click Edit Data.

  2. Click New button, and create one record instance for Registered Fulfillment with the following data:

- Process Name = "com.example.work-order-lib:Default Fulfillment Process"

- Fulfillment Type = "Default"

See the following example

images/docs/download/attachments/668429643/create-new-record.png

Creating the Registered Fulfillments Named List

  1. In the Named Lists tab, create a new Named List

  2. Enter the name Registered Fulfillments, and attach it to the Registered Fulfillment record definition.

  3. Use Fulfillment Type as the label field

  4. Use Process Name as the value field

    images/docs/download/attachments/668429643/create-named-list-registered-fulfillment.png

Defining additional supporting Named Lists

Follow the previous steps to create the following Named Lists as in the examples.

  1. Create a new Named List called Agents and attach it to the All Records > Foundation > Agent record definition.

    images/docs/download/attachments/668429643/namedlistagent.png

  2. Create a new Named List called Employees and attach it to the All Records > Foundation > Employee record definition.

    images/docs/download/attachments/668429643/namedlistemployee.png

  3. Create a new Named List called Work Sites and attach it to the All Records > Foundation > Site record definition. NOTE: Ideally, we should use the ID as the Source Field for Value of Selection. However, this will introduce a complication in that components (such as the Google Map we will introduce in a later lesson) are not yet capable of looking up the location address from the ID. There are two ways to solve this. 1) Add a hidden field to store the actual address, and use a rule and a business process to populate it whenever the location ID changes. 2) Add logic to our Google Map component to handle the ID as well as a street address. For now, we will work around this by simply returning the location name as the Source Field, and expect that this can be enhanced later.

    images/docs/download/attachments/668429643/work-order-named-list.png

Creating sample data

You have already created the required record instance of Registered Fulfillment. However you also need to have at least a few Agents, Employees, and Sites configured. You can do this in the Administration area of Innovation Studio.

  1. Switch at the top tab from Workspace to Administration

  2. In the list of Settings on the left, select Foundation Data, Manage People, then Agents. Create at least one Agent.

  3. Create at least one Employee under Foundation Data, Manage People, then Employees.

  4. Create at least one Site under Foundation Data, Manage Locations, then Site. Make sure the Location Name is complete with address information.

images/docs/download/attachments/668429643/creatingagents.PNG

Creating the work order Record Definition

Now we are ready to create the primary kind of record that will be the subject of the Work Order library.

Create a new Regular Record Definition called Work Order.

  1. In Innovation Studio, navigate to the Work Order library and go to the Records tab.

  2. Specify the name Work Order.

  3. Skip the Record Inheritance options.

  4. Change the "Assignee" field

    - Change the name to Owner

    - Attach it to the Named List called Agents (created in a previous Lesson)

  5. In the Record Designer, update the Status field to offer the following selection options. HINT: The easiest way to do this is remove all the existing options except New. Then click Add Option six times to create the new options with the proper numbering. Finally, change the option names to match the table above.

    Name Integer Value
    New 0
    Approved 10
    Rejected 20
    Assigned 30
    WIP 40
    Cancelled 50
    Completed 60
  6. Assign the Default Value of Status as New if it is not already set.

  7. Add the other fields required by the data model.

    Field Type Notes
    Contract Text
    Requestor Text Named List: Employees
    Fulfillment Text Required: TrueNamed List: Registered Fulfillments
    Site Text Named List: Work Sites
  8. Enable the aspects of the Work Order record definition that you shall allow others to customize.

    In the Record designer, click Choose what can be Customized in order to enable things like adding fields and setting permissions. The actual fields specified aren't very important here - the main idea is that as a developer you can control what happens later by non-developers.

    images/docs/download/attachments/668429645/work-order-customization-options.png

    ** **

  9. Save and close the Record.

    images/docs/download/attachments/668429645/work-order-record.png

Creating the initial user interface

Now that we have a basic data model for Work Order, the next step is to design a user interface so the user can interact with it.

Creating a sliding panel view

To enable entering work order information, we will create a panel that slides into view from the right side of the screen. We will keep this view fairly simple with only the fields needed to create a new Work Order.

  1. In Innovation Studio, navigate to the "Work Order" Library and go the "Views" tab.

  2. Create a new View with simple "Container" layout.

  3. Specify the name as "New Work Order Blade".

  4. Drag in a single Record Editor component

    - Specify the Record Definition Name as "Work Order".

    - Specify the Mode as "Create".

    - Use Quick Add/Remove Fields to add Description, Owner, Requestor, Site, Fulfillment, Contract

  5. Drag in a Button Bar widget.

  6. Drag in an Action Button into the Button

    - Give it the name "Submit"

    - Add/Remove Actions

    - Add a "Save" action

    images/docs/download/attachments/669191232/savebuttonactions.PNG

    images/docs/download/attachments/669191232/saveactionadd.PNG

    images/docs/download/attachments/669191232/saveaction.PNG

  7. Drag in an Action Button to the right of the Submit bu

    - Give it the name "Cancel"

    - Add/Remove Actions

    - Add a "Close View" action

    - Set "Act as Cancel" to true

    images/docs/download/attachments/669191232/actascancel.PNG

    images/docs/download/attachments/669191232/cancelbutton.PNG

  8. Save and close the view.

Summary

Next we will create the List Work Orders view as a full-screen table grid.

Creating a table grid view

Another common application design is a full screen view. To display the list of work orders, we will present the user with a table grid view in the main screen. Then we will add an user interaction to open the slide out view that we built in the previous exercise.

Design the main view component

  1. In Innovation Studio, open the Work Order Library, and go to the Views tab.

  2. Create a new View with the Layout: Header and 2 Columns (60/40)

  3. Specify the name as List of Work Order.

  4. Drag a Rich Text field to the top and enter the text Work Orders.

  5. Drag a Record Grid component to the main column area on the left. (Leave the right side empty for use in a later Lesson.)

  6. Specify the Record Definition Name as Work Order.

  7. Specify Enable Row Selection as Single Row.

  8. Use Add/Remove Grid Columns to set it up as shown below (see notes):

    - Remove Modified Date.

    - Rename Display ID to Work Order ID.

    - Add the ID (NOT GUID) column. Hide the column by clearing the Visible By Default checkbox.

    images/docs/download/attachments/669191247/view-list-of-work-order.png

Adding interactivity to open the sliding panel view

  1. Add an Action Button to the view, and place it above the Record Grid. Do not place it into the grid's button bar.

  2. Name the button label New.

  3. Set the button icon as Add.

  4. Open Add/Remove Actions.

  5. Under Available Actions, add the Open View action trigger, and assign the following properties:

    - View: New Work Order Blade

    - Presentation: Docked Right Modal

    - Title: New Work Order

    - Size: Small

    This defines the action to open the sliding panel view for the user to create a new work order.

  6. Under Available Actions, add the Refresh action trigger, and assign the following property:

    - Specify the View Component as the Record Grid component

    images/docs/download/attachments/669191247/newworkorderactions.PNG

    This action will refresh the main work order list after adding a new work order.

  7. Save the view.

Testing the view component

  1. Preview the view using the Preview button.

  2. Use the preview to create a few work orders.

    images/docs/download/attachments/669191247/previewworkorder.PNG

  3. To complete the preview, cancel out of the browser tab and confirm the navigation. This is normal behavior for View Preview.

Summary

We have now successfully created a simple Work Order library. It can currently be tested only by using Preview in Innovation Studio on it's main View, called LIst Work Order. Next up, we will add a concept of Work Task that is part of fulfilling a Work Order.

Defining work tasks

In this module we will extend and enhance the Work Order library to create an abstraction of Work Task. To define Work Task, rather than create a new definition completely from scratch, we will extend the existing definition of Task as defined in the Task Manager application.

Each Work Order can include tasks that are completed as part of the process of fulfilling a work order. The process will be described using BPMN using the Innovation Studio's Process Designer.

For this exercise, you must have completely deployed Task Manager as shown in Deploying required application modules. Simply seeing the library listed in Innovation Studio does not mean its definitions have been deployed.

Extending Task as Work Task

In this lesson we will create a record definition and add a field which we will reference later.

  1. In Innovation Studio, open the Work Order library to the Records tab.

  2. Create a new definition of the type Regular Record.

  3. In the Record Definition properties pane, enter the name Work Task.

  4. Under Record Inheritance ensure the three options are cleared.

  5. Click Inherit from a Record Definition.

  6. Select All Records >Task Manager >Task as the Record to Inherit. You will have to browse in All Records and then Task Manager to find Task, which is not in this bundle.

    images/docs/download/attachments/669191276/task-selected.png

    If you DO NOT see the Task Manager app under All Records, as in the preceding illustration, then you may have to repeat the Deploy Task Manager step in the setup phase.

  7. Enable the check box to specify the Core Fields property to be inherited.

  8. Clear the check boxes to specify the following properties will not be inherited:

    - Rules

    - Field Permissions

    - Associations

    See the following example:

    images/docs/download/thumbnails/669191276/inheritoptions.PNG

  9. Create a New Field of type Decimal.

  10. In the field definition properties pane, enter the name Hours Worked.

  11. Toggle Required to ON.

  12. Enter the Field ID 536882001. This value enables the Java code to work with it in later steps.

  13. Save and close the record definition.

Summary

When you return to the list of record definitions, the newly created definition should appear.

images/docs/download/attachments/669191276/work-task-hours-worked.png

Associating Work Task with Work Order

In this lesson we will bind data by creating an association between two records.

  1. In Innovation Studio, open the Work Order Library and go to Associations.

  2. Create a new association and name it Associated Work Tasks.

  3. Complete the following fields:

    - First Record: Work Order

    - Cardinality: Has Many

    - Second Record: Work Task

    - Role of First Record: Fulfills

    - Role of Second Record: Fulfilled By

  4. Select the check box to add the constraint to delete all associated Work Task records if Work Order is deleted.

  5. Ensure Enable Association checked.

  6. Save and close the Association.

    images/docs/download/attachments/669191274/createassoc.PNG

Summary

To show that the association has been created, open the record definition for Work Task. Scroll to find a foreign key field called FULFILLS_ID has automatically been generated, based on the Role of First Record property.

images/docs/download/attachments/669191274/work-order-work-task.png

Creating a Work Task console

In this lesson we will create place using a record and a view that shows a user the Work Tasks that need to be completed, along with some of the related Work Order information. We will use a Join Record to capture the desired information.

Creating a new Join Record

  1. In Innovation Studio, open Records and create a new Join Record.

  2. Select the Primary Record, Secondary Record, and Join Type as in the following illustration, then click Next.

    images/docs/download/attachments/669191273/create-join-record.png

  3. Click to open the expression builder. Drag and drop to create the following ON Statement: Work Order.ID = Work Task.FULFILLS_ID and click Next.

    images/docs/download/attachments/669191273/onstment.PNG

  4. Select the following fields to include from Work Order:

    - Work Order.Display ID

    - Work Order.ID

    - Work Order.Contract

    - Work Order.Status

  5. Select the following fields to include from Work Task:

    - Work Task.Display ID

    - Work Task.Assignee

    - Work Task.Status

    - Work Task.Description

    See the following illustration

    images/docs/download/attachments/669191273/create-new-join-record.png

  6. Click Save to close the wizard.

  7. In the record definition properties, enter the name Work Task with Work Order.

  8. Save the Record Definition.

Creating a simple console view

  1. In Innovation Studio, open Views and create a new view of type Header and 1 Column.

  2. Enter the name Work Task Console.

  3. Drag a Record Grid component into the main body.

  4. Select the Record Definition to pull records from Work Task Order.

    images/docs/download/attachments/669191273/work-task-console-view.png

Summary

We have a basic console that can show the details for the Work Tasks that are associated with specific Work Order records. The next step is to enhance the UI to show a list of them in the context of a Work Order.

Creating a Work Order console

The Work Order console is the main part of our application. From the Work Orders list, the user shall be able to open the associated Work Task records in the Work Task console we created earlier. The Work Order console shall also give users a place to enter new work tasks.

Creating a helper view to create new tasks

Before working on the Work Order Console view itself, let's create a helper view for creating new tasks, similar to the sliding panel used for creating Work Order. The difference here is that because Work Task belongs to Work Order in a 1:many association, our view requires the parent Work Order id to be passed in as a parameter.

  1. In Innovation Studio, open Views and create a new view with layout style Container.

  2. Enter the name New Task Blade.

  3. Add an input parameter called workOrderId, for use with the parent work order.

  4. From the palette, drag a Record Editor component onto the canvas.

  5. Select the Record Definition Name: Work Task.

  6. Select the mode: Create.

  7. Under Form Contents, click Quick Add/Remove fields, and add the fields needed to create a new task:

    - Description

    - Hours Worked

    - Priority

    - Status

  8. Add the foreign key field FULFILLS_ID, set to be Hidden at all times.

    images/docs/download/attachments/669191270/newtaskview.PNG

  9. Beside Value, click Edit to open the expression builder to assign a Value expression that automatically defaults to the workOrderId parameter of the view. This establishes the direct association.

    images/docs/download/attachments/669191270/setforeignkey.PNG

  10. From the palette, add an Action Button to Save and Close the view, similar to what was done before with the New Work Order Blade.

  11. Save and close the View.

Creating the Work Order console

Now we are ready to work on the console itself.

  1. Create another new View with layout Container. This is necessary in order to create a 3-column layout.

  2. Enter the name Work Order Console.

  3. Add an input parameter called workOrderId.

  4. From the palette, drag a Rich Text control to add the title Work Order Console.

  5. Drag a Container control below the Rich Text and set it to 3 columns.

  6. Drag a Rich Text control and enter label for each column left to right:

    - Work Order

    - Tasks

    - Task Detail

    Configure each of the columns as described in the following sections.

Building the Work Order column

  1. Drag a Record Editor component under the title Work Order.

  2. Enter the Record Definition Name: Work Order.

  3. Leave Mode as Edit.

  4. Under Record ID, open the expression builder and add the workOrderId View parameter, then close the expression builder.

  5. Select Show a read-only state for this component.

  6. Leave Default State as Read.

    images/docs/download/attachments/669191270/work-order-properties.png

  7. Under Form Contents, click Quick Add/Remove fields, and add the fields needed to create a new task:

    images/docs/download/attachments/669191270/work-order-properties-panel.png

  8. Change the Display Label of Display ID to Work Order ID.

  9. If you choose to preview the view, you will need to enter the ID of a Work Order.

Building the Task List column

  1. Drag a Record Grid Component under Tasks.

  2. Select Mode as "Association"

  3. Select Record Definition to Show: "Work Task"

  4. Select Association to Use: "Associated Work Tasks"

  5. Enable Row Selection: "Single Row"

  6. Select Associated Record ID: use expression builder to select "workOrderId" view parameter.

  7. Add/Remove Grid Columns:

    - remove the Modified Date Column

    - add the ID column but make it hidden by default.

  8. Drag an Action Button into the Record Grid Component header bar area within Record Grid, which shall be used for creating new tasks.

    - Label: New

    - Style: Primary

    - Size: Small

    - Icon: None.

  9. Click Add/Remove Actions and add the following:

    - Action: Open View

    - View: New Task Blade

    - workOrderID parameter is this view's workOrderId parameter

    - Presentation: Docked Right Modal

    - Title: New Task

    - Size: Small

    - Action: Refresh

    - Open the expression builder, and select the Grid Component to be refreshed after the New Task blade is closed.

  10. Drag another Action Button into the Record Grid Component header bar area within Record Grid, which shall be used for deleting tasks.

    - Label: Delete

    - Style: Primary

    - Size: Small

    - Icon: Delete

  11. Click Add/Remove Actions and add the following:

    - Action: Delete Records

    - Open the expression builder to set the Records as "Record Grid" You must click carefully on the plus icon to add it to the expression.

    images/docs/download/attachments/669191270/record-grid-action-button.png images/docs/download/attachments/669191270/record-grid-expression-builder.png images/docs/download/attachments/669191270/record-grid-actions-editor.png

Building the Task Detail column

  1. Drag a Record Editor under Task Detail.

  2. Set the Record Definition to "Work Task"

  3. Set the ID expression to the ID field of the First Selected Row of the grid.

    images/docs/download/attachments/669191270/work-task-expression-builder.png

  4. Add the important editable fields of Work Task as shown

    images/docs/download/attachments/669191270/work-task-editable-fields.png

    At this point the view should look something like this in the designer:

    images/docs/download/attachments/669191270/fullconsole.PNG

  5. Save and Close the View

Adding a control to open the Work Order Console

  1. Open the view created in Creating a table grid view: List of Work Order.

  2. Drag an Action Button to the Grid component's button bar area.

    - Label: Open Console

    - Style: Primary

    - Size: Small

    - Icon: Edit.

  3. Click Add/Remove Actions and add the following:

    - Action: Open View

    - View: Work Order Console

    - workOrderId: ID

    - Presentation: Full Width

    - Launch Behavior: Open in same window

    images/docs/download/attachments/669191270/work-order-console-action

Summary

At this point we have build the essential "plumbing" for both Work Orders and their associated Work Tasks. Preview the views starting with the List of Work Order view.

images/docs/download/attachments/669191270/work-order-preview.png

images/docs/download/attachments/669191270/work-order-console-associations.png

What is missing is the business logic that controls the life cycle of these and the interactions with the business, so that is what we will turn to next.

Defining the work order fulfillment process

Every Work Order will have an instance of a process running in the background that will monitor the Work Order, create Work Tasks associated with it, and keep track of when all the tasks are complete. We will add much more functionality to this process later on, but for now, let's define a bare-bones process that will generate a few Work Tasks and wait for them both to be complete.

If you recall from the introduction, there needs to be a business process centered around the the fulfillment of the Work Order generally, which can tie in specific processes for completion of Work Tasks towards that goal. In this Lesson, we will build the Work Order Process and Default Fulfillment Process as the skeleton for the business logic. Customers can later add their own more sophisticated fulfillment flows and rules.

images/docs/download/attachments/667810456/workflow-overview.png

Creating the default fulfillment process

We will start by creating a simple process to orchestrate fulfillment by creating Work Tasks and waiting for them to be completed. Later, we will fold this into an overall Work Order process an example of how tailoring can take place for fulfillment processes.

You may recall that we set up the data for "Registered Fulfillment" to have a single default entry in it, called "Default" in the Named List, mapped to the value "com.example.work-order-lib:Default Fulfillment Process". This is the process that we want to use by default; so, let's create that now.

In Innovation Studio, navigate to the "Work Order" Library and go to the "Processes" tab.

Create a new Process.

  1. Specify the Process name as "Default Fulfillment Process"

  2. Define a "Work Order" as a Variable

    1. Name is "WorkOrder"
    2. Do not specify a Parameter ID.
    3. Parameter Type is "Input" and "Input Required"
    4. Variable Type is Input/Output Parameter, both Input and Input Required.
    5. Date Type is "Record"
    6. Record Definition is "Work Order"
    7. Leave Use Sample Data as clear.

      images/docs/download/attachments/669191365/addremovevars.PNG

    8. Define "Description" as a Process Input Parameter (this is to make it easier to manage and debug execution).

      1. Name is "Description"
      2. Do not specify a Parameter ID
      3. Parameter Type is "Input Required"
      4. Data Type is "Text"

        images/docs/download/attachments/669191365/input-parameter-setup.png

  3. Set the Context Key to "Description". This will be very useful in following the progress of process execution with useful information.

    images/docs/download/attachments/669191365/add-remove-description.png

  4. Locate the start and end elements. They may be scrolled on both right and left depending on the resolution of the screen and size of the browser window. Drag the end somewhat closer to start.

  5. Add a User Task element from the palette and configure it. This element will not only create a Work Task, but it will be configured to wait until it's status becomes "Completed".

    images/docs/download/attachments/669191365/create-associated-work-task.png

    1. Change the label to "Create Associated Work Task"
    2. Mode is "Create Record"
    3. Record Definition is "Work Task"
    4. Completion Criteria has an expression based on "Create Associated Work Task"'s Status field value

      images/docs/download/attachments/669191365/completion-expression-builder.png

    5. Add the mapping for the important fields to be set for the new Work Task. Remember that this is just a default process and actual fulfillment processes can be much more complex and involve multiple flows and multiple tasks.

      images/docs/download/attachments/669191365/add-remove-input-map-fields.png

    6. Set the Hours Worked to some default value.

    7. Set the Description. A generic description can be generated with the expression:

      images/docs/download/attachments/669191365/edit-expression-for-description.png

    8. Set the parent Work Order ID as the foreign key. This is the easiest way to establish the association relationship

      images/docs/download/attachments/669191365/edit-expression-for-fulfills-id.png

    9. Set the Assignee of the new Work Task to "Seth" for now. This will make it easier to unit test the process.

    10. Set the Status to 1 (Staged)

    11. The input map with values should look like this:

      images/docs/download/attachments/669191365/input-map-fields.png

  6. Add a Send Message element from the Palette and configure it as follows. Note that you can access Task fields from the previous "Create Associated Work Task" element in the expression builder. Take care that all literal text is enclosed in double quotes, and all variable expressions are inserted with "+" to build the full expression.

    images/docs/download/attachments/669191365/send-message-parameters.png

  7. Connect all the flows appropriately.

    images/docs/download/attachments/669191365/complete-process.png

  8. Save the process (and fix any errors reported).

  9. We are now ready to unit-test the process.

    1. In the Records tab, use the "Edit Data" feature for "Work Order" to get a valid ID field value for a Work Order (this will be a guiid type of long string of numbers and letters). This will be the parent work order. Copy this into the clipboard.
    2. On the Processes tab, open the Manage Process console.
    3. Select "Default Fulfillment Process" and click Run
    4. Enter the three required parameters to run the process: the Work Order (specified by ID and fully-qualified Record name), and the Description (which serves as the Context Key for debugging).

      images/docs/download/attachments/669191365/run-default-fulfillment-process.png

    5. Click Run at the bottom of the right-hand blade.

    6. The process should appear in the process instance list. Filter by "Active" if you have other process instances you don't want to see right now.

      images/docs/download/attachments/669191365/worddav0dff8e35fe74444e858eefab799deff9.png

    7. Note the context key matches what we input.

    8. Click on the process ID to bring up it's current state, which should be waiting for the Create Associated Work Task to finish.

      images/docs/download/attachments/669191365/process-instance-information.png

    9. Preview the List of Work Order UI to bring up the parent Work Order you used for this test. You should now see the Work Task listed in the Grid. Select it to edit and change the Status to "Completed".

      images/docs/download/attachments/669191365/list-of-work-order.png

    10. After about 1 minute, this should unblock the process and cause the notification to be sent to "Seth".

      1. The easiest way to view the notification is to Launch some application that uses the UI Shell, which we will for Work Central in a later lesson.
      2. For now you can switch the workspace to "Task Manager" and click "Visit Deployed Application" to see the notifications in the Bell icon in the banner.
      3. NOTE: If you do switch to the Task Manager bundle in Innovation Studio, be sure to SWITCH BACK before resuming the Lesson.

        images/docs/download/attachments/669191365/task-status-notification.png

Creating the overall orchestration process

It's great that we have created a sample task fulfillment process. However, this is not really the Work Order process - it is simply one way of creating tasks in the context of a Work Order. What we would like to have is

  • A repeatable process that can be invoked for every Work Order, and can delegate fulfillment to a fulfillment process (such as the one we just created earlier).

  • Can handle Work Order - specific concerns such as approval of work orders

    • NOTE: we will not actually configure an approval process here - that is done as part of tailoring. However, we will introduce a User Task that will be updated during tailoring to invoke the actual approval process.
  • Stays agnostic about the actual work that is to be done

When finished, the umbrella Work Order process should look like this:

images/docs/download/attachments/669191400/process.PNG

To create this, we will use the Process Designer to create another New Process.

  1. Be sure you are in the correct bundle for Work Order within the Workspace.

  2. On the Processes tab, click New Process.

  3. Give it the name "Work Order Process"

  4. Set it up with parameters and context key, exactly like the default Fulfillment process we created above.

    images/docs/download/attachments/669191400/worddav3250d4eef8543219bf84634777a1eeff.png

  5. Add a User Task element and connect the Start element to it. This represents our future approval process.

    1. Specify the label as "Wait for Approval"
    2. Specify the Mode as "Update Record"
    3. Specify the Record Definition as "Work Order"
    4. Specify the Record ID using an expression so that it is set to the process variable "Work Order" -> ID.

      images/docs/download/attachments/669191400/worddav295e06abeb92517669dc73eb38b1b94e.png

    5. Completion Criteria. This represents the full-blown approval process that can be configured later. For now, we want it to wait until the work order is actually approved or rejected. Thus, the qualification is, using the Status field from the "Wait for Approval" User Task (NOT the Process Variable), Status = "Approved" OR Status = "Rejected" IMPORTANT: Make sure to pick the Status field from "Wait for Approval" and NOT from the "Process Variables" section. You will also notice that the little glyph icon in the front of the tag is different.

      images/docs/download/attachments/669191400/worddav647f2cfcf399836efb70703c97c09751.png

    6. Leave the INPUT MAP and OUTPUT MAP alone.

    7. The configuration should look like this:

      images/docs/download/attachments/669191400/worddavcc5c1e71534041829a61bd5f94f2b07e.png

  6. Add a Gateway to handle rejection

    1. Drag in an Exclusive Gateway element from the palette.

      images/docs/download/attachments/669191400/worddav201a9177a0b4b63f6a8f91f52595e288.png

    2. Label: "Is Approved"

  7. Drag in a Call Activity element

    1. Change its label to "Invoke Configured Fulfillment"
  8. Connect the "Is Approved" Gateway to the "Invoke Configured Fulfillment" with a new Flow

    1. Set the flow label as "Yes"
    2. Configure the condition of the flow as 'Status' = "Approved"
  9. Set the Status to "Rejected" in the case of rejection.

    1. All we know at this point is that the Work Order is not in Approved state.
    2. Force it to "Rejected" using an "Update Record" activity from the palette.
    3. Set the Record Instance ID of the Work Order using the expression builder.
    4. Change the label of the "Update Record" element to "Reject"
    5. Add Status to the input map and set it's value to "Rejected" using the expression builder. It will show as value "20".
  10. Add a Notification in the case of rejection

    1. Drag in Send Message element and configure it with a message that says "Work Order " + WORK ORDER EXPRESSION + " has been rejected"
    2. Connect it to the gateway as the "default" flow (this will be executed when the status is NOT "Approved"
    3. Add a flow to connect the User Message to the end of the process.
  11. Dynamically invoke the task fulfillment process based on the data configuration

    1. Select the "Invoke Configured Fulfillment" element.
    2. Configure the actual process name using an expression. Click on "Select" and choose "Build Expression". Then 'Click to build expression"

      images/docs/download/attachments/669191400/worddave3f2eed9e35ad10f710f4a120cb78b95.png

    3. The process name will be found in the Fulfillment field of the Work Order. Parameter (as you recall, this value is populated from the Named List created earlier. At runtime based on our sample data it will be "com.example.work-order-lib:Default Fulfillment Process").

      images/docs/download/attachments/669191400/worddav40e2dca0b73ec6d0933fff8379563e8c.png

    4. Pick the Sample Process as "Default Fulfillment Process". This tells the Process Designer what input map to require. Set up the Input Map to pass the Work Order and a context key down to the called process.

      images/docs/download/attachments/669191400/worddav2877cd1a53b6f037c199c5d3256b4589.png

  12. Add a User Task to wait for all associated tasks to be complete. This will use a BPMN looping feature called "Multi-Instance Loop". This is a bit complex so let's break it down into steps.

For the overall process, add a Variable called Task (this will be the "loop variable" for an individual Work

images/docs/download/attachments/669191400/var.PNG

Add a User Task and call it something like "Wait for all Tasks to be Complete"

Configure the MULTI-INSTANCE part of the properties. This defines the overall data set, and effectively turns the "Task" variable into an object that can be referenced each pass through the loop when it runs.

Loop type can be "Parallel" (simply because order of completion does not matter in this case.. For the "Input Data Item" choose the Task record variable created above.

images/docs/download/attachments/669191400/loop_props.PNG

The data set itself comes from the Associations when defining the expression. Note that the role defined by the association between Work Order and Work Task is called "Fulfilled By"; this refers to all the associated Work Task instances for the given Work Order.

images/docs/download/attachments/669191400/associations.PNG

We are almost there. Now we can configure the normal User Task properties just as though it were handling a single object.

images/docs/download/attachments/669191400/user_task_props.PNG

In this case, the Record ID needs to be grabbed from the Task variable since that represents an individual Task within the loop.

images/docs/download/attachments/669191400/task.PNG

As with any User Task, we can now configure it to block until the Status is "Completed". The difference here is that because of the MULTI-INSTANCE properties, this will actually repeat this blocking behavior for every associated task.

images/docs/download/attachments/669191400/criteria.PNG

We can add a bit of extra logic to make sure the Work Order is in a Completed state once all the tasks are completed. This is simply the inclusion of an "Update Record" element - it's configuration follows a familiar pattern:

images/docs/download/attachments/669191400/update.PNG

Finally, add another "Send Message" element to let the owner know that the Work Order is complete.

images/docs/download/attachments/669191400/notify.PNG

Resolve any validation errors and save the process.

NOTE: some kinds of errors allow the process to be saved in a disabled state. Others must be resolved in order to save.

Enabling the process to run for every work order

We now have a simple process, but there is nothing that triggers it to run at any time. For this we need to add a simple Rule that will make sure there is always one instance of the process for every Work Order. From now on, we will be able to test the process by creating a new Work Order rather than simulating this in the Process Manager.

In Innovation Studio, navigate to the "Work Order" Library and go to the "Rules" tab.

Create a new Rule.

  1. Specify the name as "Launch Work Order Process"

  2. Add/Remove Record Definitions

    1. Double-click on "Work Order".
    2. It should be added to the Selected Record Definitions list as the Primary Definition

      images/docs/download/attachments/669191434/worddavdf6ee635f9a918ada816f180823459bc.png

    3. Select the Trigger

      1. Leave Trigger Type as "Record Event"
      2. Select the "On Create" checkbox, but NO OTHER checkboxes.

        images/docs/download/attachments/669191434/worddav228dba4661c98371b5549fe2c7ced984.png

    4. Drag in a Start Process element into the canvas, automatically connecting it with the Trigger.

      1. Set the label as "Start Work Order Management"
      2. Set the Process to Start as "Work Order Process"
      3. Under INPUT MAP, generate the expression for the "Description" and "WorkOrder" process input parameters:

        1. For Description, create a context key for debugging the process.

          images/docs/download/attachments/669191434/worddavb9f2d320e2dc3644e7fa1dbd20e00d4e.png

        2. For Work Order, click to Build an Expression

        3. Under the General tab, double click on "Current Record"

        4. Click "OK".

          images/docs/download/attachments/669191434/worddav4b482349925a7ef8fbee82a77ecf8356.png

    5. Save the Rule

      images/docs/download/attachments/669191434/worddav4d43d7ce5acef9f4a3e1718f7454a5a8.png

Testing the process

This is very similar to how the Default Fulfillment Process was tested. One difference is that since there is a rule that creates the process, it can be kicked off simply by creating a new Work Order. Remember that it can take up to a minute for User Task elements to be executed after records change. To test it, this can be a combination of

    1. Use UI elements already created
    2. Use the Data Editor if desired to change the status of records
    3. Use the Manage Process screen to debug execution of the Process.
  1. This specific case:

    1. In this case, start the workflow by creating a new Work Order. Then check the state of the process using the Manage Processes feature as before - the work order should be in "Wait for Approval".

      images/docs/download/attachments/669191468/worddavba812f29483ef7f605c0a2e290fa8eff.png

    2. Bring it up in the List of Work Order,open the console for this work order, and change the status to "Approved".

      1. After some time (about one minute), the child task should appear when the grid is refreshed (also the Work Order process should now be in "Invoke Configured Fulfillment". Change the Task's Status to Completed.
      2. After some time, the parent Work Order process should become Completed.
    3. The correct notifications should appear in the Shell.

      1. You may have to use Task Manager until you have completed the next Lesson
      2. NOTE: If you do switch to the Task Manager bundle in Innovation Studio, be sure to SWITCH BACK before resuming the Lesson.
    4. Repeat the test, but this time specify the status as "Rejected"

      1. This time you should get the notification about rejection and no task should be created.
      2. The Work Order process for this Work Order should be in a Completed state and the appropriate notification should have arrived.

Summary

So far, we have built a simple Work Order library including a business process that creates and monitors tasks that fulfill it.

In order to do this, we have extended the data model to include associated tasks, and used the status of both Work Order and Work Task to orchestrate their relationship.

Creating the Work Central application

So far we have created a Work Order library with some data model, view, and process elements. However we have not yet created an application. Our application, which will depend on and utilize the work-order-lib for most of its functionality, is essentially an entry point and "home view" that supports global operations and defines a context for the use of Work Order.

Generating and deploying the Work Central application

Earlier, you generated and deployed the Work Order project as a library. In this exercise you will perform similar steps to generate a project as an application.

  1. From your projects folder, run the maven archetype command. The syntax is almost the same as when we created a library earlier, except that the archetype id ends with -simple instead of -lib.

    projects> mvn archetype:generate -DarchetypeGroupId=com.bmc.arsys -DarchetypeArtifactId=rx-sdk-archetype-simple

    The command line arguments have the following effect:

    Archetype Argument Meaning
    -DarchetypeGroupId=com.bmc.arsys Tells maven to use the BMC archetypes
    -DarchetypeArtifactId=rx-sdk-archetype-simple Selects the Simple application archetype. This will set the POM file to create an application package, which generates a working UI.

    The archetype command syntax is documented at Creating a Project using Maven and the Archetype.

  2. Accept defaults when appropriate but use these specific values when asked:

    Archetype Prompt Value to Provide
    Define a value for property 'groupId': : com.example
    Define a value for property 'artifactId' work-central-app
    Define a value for property 'version': 1.0-SNAPSHOT (Enter to accept default)
    Define a value for property 'package': com.example (Enter to accept default)
    Define a value for property 'bmcApplication' : : N (for non-BMC Developers)
    Define a value for property 'name': : Work Central
    Confirm properties configuration: groupId: com.example artifactId: work-central-app Version: 1.0-SNAPSHOT Package: com.example Name: Work Central Y: (Enter to accept default)
  3. Modify the package POM file so the deployment process will use the credentials of the developer user (by default, it puts Demo with no password in the POM file), and the target development AR System being used. This step is identical to the steps taken to configure the work-order-lib project.

  4. Now, build and deploy the project. This can take a long time.

    projects> cd work-central-app
    work-central-app> mvn clean install -Pdeploy
    
  5. Look for build success and verify that it shows up under your Innovation Studio as a library using the url. Note that you may need to refresh the browser.

    http://SERVERNAME:PORT/com.bmc.arsys.rx.innovationstudio/index.html

    Be sure to refresh your browser if needed after a redeploy of the client code.

Creating a home view

We will create a very simple landing page for our application.

In Innovation Studio, navigate to the Work Central Application and go to the "Views" tab.

Create a new View with layout "Header and 1 Column"

  1. Set the name to Home View

  2. Add a Rich Text component to the header area.

    1. Type a welcome message into the Rich Text area.
  3. Save the View (I told you it was very simple for our tutorial!).

    images/docs/download/attachments/667810489/worddavc0b970c3a1ac74b12cea8deed6ce7afe.png

Configuring the shell

  1. From the Application page for Work Central, click on the Edit button for the "BMC Modern Shell". The Shell will open in a special View Designer screen.

    images/docs/download/attachments/667810489/worddav0f6840902cb50c32d628a4d896b50d52.png

  2. Remove the Objects menu item.

  3. Change the Home navigation to our Home View.

    1. Select "Home"
    2. Change the Action to Trigger" to "Navigate to View" instead of "Navigate to State"
    3. Set the view as "Home View"

      images/docs/download/attachments/667810489/worddavd3d7b7916072c6298a2438dda6b2f30b.png

  4. Add navigation to get to the list of Work Orders.

    1. Drag in a new Menu Group to the right of Home
    2. Change the label to Orders
    3. Drag in a new Menu Item beneath Orders
    4. Change the label to List
    5. Change the "Action to Trigger" of List to "Navigate to View"
    6. Select the view as List of Work Order from the Work Order bundle.
  5. Add navigation to the Work Task Console.

    1. Drag in a new Menu Group to the right of Orders
    2. Change the label to Tasks
    3. Drag in a new Menu Item beneath Tasks
    4. Change the label to List
    5. Change the "Action to Trigger" of List to "Navigate to View"
    6. Select the view as Task Console from the Work Order bundle.
  6. Save the Shell.

Testing the Work Central application

From the Application page for Work Central, click on Visit Deployed Application.

images/docs/download/attachments/667810489/worddava61a341ff966d3f3eadafe5d8fb6a139.png

images/docs/download/attachments/667810489/worddava2263af26bbf22b9d5c7c2ab5368cb50.png

images/docs/download/attachments/667810489/worddav7477b1365322111f266ad5722100bd90.png

Summary

We have created a simple, though usable, application using just Innovation Studio.

Setting up security for the work order library

Creating the work order library security model

images/docs/download/attachments/667810497/worddav0f934a5f1c5a03d2841444323f2f44bb.png

In the Administration tab, navigate to Configure My Server->Application Permissions->Manage Role Permissions.

Create the following two Roles:

Application Name Role Name Role ID
com.example.work-order-lib Work Manager -57100
com.example.work-order-lib Work Implementor -57101

While not strictly required, for testing purposes at development time, you probably would like to create groups that can be mapped to the roles. Let's create corresponding dummy groups for the roles we just created.

  1. In the Administration area, configure the Work Manager role.

    1. Create a group to represent the Work Manager Role, such as "IT Managers"

      images/docs/download/attachments/667810497/worddav94d2d20e01a69623964ef409a73b9079.png

    2. Bring up the Work Manager role and map the "IT Managers" group to it. Note that this is purely done for unit testing and the groups created here will not be exported as part of the application package.

      images/docs/download/attachments/667810497/worddava0fef143f3616a7b1bea216c746324a6.png

  2. Repeat this for the Work Implementor role by creating a group called IT Staff with id 4302.

Creating a security label for work order access

Now that we have some roles, we would like to use them to control access to work orders. This is controlled dynamically by specifying a security label for this access, and mapping it to roles when the records are created. This is a little different from static security models, like permissions, that are not easy to change at runtime. Using security labels, you can map the roles based on conditions in the data or other workflows.Let's set this up for the Work Order record definition.

  1. Open the Record Designer for "Work Order"

  2. We wish to add some "dynamic security". The requirement is that Work Orders that are considered "sensitive" are visible only to work order managers and the person that created it and the one assigned to it. Other Work Orders are visible to all Work Order Implementor users. To enable this, we must first create a new boolean field for Work Order called "isSensitive" with the default value of "False".

    images/docs/download/attachments/667810497/worddav20735e87079e76d89a65b4c673717db5.png

  3. Add a Security Label to the Work Order Record Definition.

    images/docs/download/attachments/667810497/worddav3519a1777ed36b3699dea6df8087b0ec.png

    images/docs/download/attachments/667810497/worddav44e185608de53e129b8541c790864819.png

  4. It is not sufficient to simply create the Security Label. We must also arrange for it to be mapped to the right roles at runtime based on the desired business logic. In this case,when the record is created with isSensitive, it should only be visible to managers. We do this by creating a Rule in the Rule designer.

    1. The Rule can be called "Work Order Security - Sensitive"
    2. Add the Work Order record definition
    3. Trigger is On Create
    4. Qualification: Is Sensitive = "true"

      images/docs/download/attachments/667810497/worddav97aa8d52dcd9f27c813117015b6d11fe.png

    5. Action: Set Security Label Work Order Access with user General->Current User and Role "Work Manager".

      images/docs/download/attachments/669191530/Capture.PNG

  5. Save the rule and set up a similar rule for "Work Order Security - NOT Sensitive". This time, the roles are both "Work Implementor" and **"Work Manager".

    images/docs/download/attachments/669191530/Capture0.PNG**

Defining work order permissions

In addition to dynamically mapping roles to the security label for Work Order, we can also set static permissions that control access at all times, and with the granularity of specific fields that have or do not have access.NOTE: by default, none of the definitions (records, fields, etc) have any permissions applied to them, so only administrators can see them. Each field must individually have permissions applied in order to users who are in groups mapped to the appropriate roles can use the application.

  1. Specify permissions for the Work Order record definition for the two Roles we have created. This means that only members of groups that will be mapped to these Roles will have access to any Work Order information at runtime.

    images/docs/download/attachments/667810497/worddavf98853ad377412ec0403a32e50e39938.png

  2. We should still protect the fields of Work Order to restrict them to users with the correct roles. The requirement is that Work Implementor members can see all the fields of the Work Order except "Contract" and "Is Sensitive". This is restricted to Work Manager members. For each of the following fields, set up the Roles (or make sure they are already set up) as follows:

    Field Roles / Groups
    Display ID Work Order Access (View), Assignee (View), Submitter (View)
    Owner Work Manager (Change), Work Implementor (Change), Assignee (View)
    Status Work Manager (Change), Work Implementor (Change), Assignee (View), Submitter (View)
    Description Work Manager (Change), Work Implementor (Change), Assignee (View), Submitter (View)
    Contract Work Manager (Change)
    Is Sensitive Work Manager (Change)

Testing the security model

  1. Unit testing the security model that was just set up requires some additional configuration data.

    1. Create a user to represent the Work Manager Role, such as Manny Manager. Add "IT Managers" to his groups.

      images/docs/download/attachments/667810497/worddavbf2dffb27d6630a762e6cc75abce652f.png

    2. Using a different browser (the easiest way not to lose your Innovation Studio session), sign in to the Work Central application as "mmanager". You can launch it the first time as Seth and then log out to sign in as the desired user.

    3. Verify that you have access to the Contract and Is Sensitive fields.

    4. Create some Work Orders that are sensitive and some that are not.

    5. Verify that you have access to both kinds.

  2. Repeat this setup process for another individual, Ian Implementor (iimplementor@example.com). This time be sure he is in a group such "IT" that is mapped to the "Work Implementor" role.

    1. Verify that as this user you do NOT have access to the Contract or Is Sensitive fields.
    2. Verify that you do not have access to sensitive records, but do have access to non-sensitive records.

Summary

In this lesson we have defined a security model as part of the application and done some unit testing.

Note that when this application is packaged, group information is not included. Customers will create their own groups and map them into the security model as you have defined it. They may even tailor the security model itself by defining new roles, or mapping multiple groups into roles (using computed groups).

Enabling customization

Before you package up the application bundles for deployment, it is a good time to make sure that you have granted the ability for administrators to customize the important Views, Processes, Records, and Fields that will be deployed as part of the work management solution. This requires some judgement and caution. Being able to modify fields, for example, could break important processes and views that you are including with the base solution.

Although the default in Innovation Studio's Designers is to not allow customization, the actual setting takes some thought. Remember that once an application bundle is packaged, it is considered locked down from further changes. In order to change the application you must begin a development cycle to create new versions of bundles.

Rule of thumb for allowing/disallowing customization

Type of Object When to Allow Customization When to Restrict Customization
View Generally leave these open. Applications are usually not broken by customized views beyond the incorrect rendering of the view itself. Typically customers want to re-arrange, hide, or add components. Care should be taken with Views whose correct operation depends on View Parameters. Customers can break the invocation of these by removing parameters. Generally customers should only add parameters but this is not enforced.
Record Generally it is recommended that Records be left open, and do restrictions at the Field level. Records that are purely part of a complex mechanism that is not meant to be tailored should be locked down.
Field Fields which are just "data containers" without significant workflow out of the box, especially ones that don't appear in the default Views, can generally be left open. Sometimes business motivations outweigh maintainability concerns. For example, the Status fields of Work Order and Work Task are heavily referenced by the Work Order Process... but this is not a good reason to lock them down. Almost every customer will want to change the Status values and process to suit themselves, so neither these fields themselves nor the associated Processes should be locked down. Any fields that are referenced throughout the application, and have Views, Rules, Associations, or Processes dependent on them, should generally be locked down. This is especially true if the fields are used in custom Java or Javascript code, which can be impossible for customers to fix in Innovation Studio. They generally can and should have field permissions open for customization.
Rule Rules that are there for example workflows can be left open. For example, a Rule that performs a type of data validation that is business logic customers might not want, or which run a Process which does not affect the data in a way that would corrupt or break the application, should be left open so that customers can disable or modify them. Rules whose execution is important to maintain integrity of the data and process execution should probably be locked down.
Process Similar to the guideline for Rules. Usually Processes are subject to customization, unless they are part of implementing an important mechanism. Processes that are part of maintaining data integrity, too complex to be safely tailored, or interdependent with Java code which cannot be tailored, should be locked down.

Based on these recommendations, the following objects should probably be locked down for Work Central and it's companion library:

  • Views (None)

  • Record

    • Registered Fulfillment
  • Fields

    • Work Order

      • Hours Worked (used in Java code).
      • FULFILLS_ID (used in Associations)
  • Rules (None)

  • Process

    • Default Fulfillment Process (could be locked down to treat it like a template. Customers should save this as their own processes)

To set customization options, each Designer has a link as part of the object properties:

images/docs/download/attachments/671337210/image2016-11-22_16_52_21.png

Packaging bundles for deployment

In this module, we will be doing various important lifecycle operations with our projects, including:

  • Prepare a Deployment Package containing all definitions, data, and code for the purpose of deploying it on an external system.

  • Export definitions and data into a file for the purposes of maintaining it in Source Code Control System.

  • Undeploying a Deployment Package to remove it from the server runtime.

Creating a deployment package

  1. Generate the package from the package folder of your project. For this example, we will use work-order-lib because it has code, data, and definitions.

    <projects>\work-order-lib\package> mvn -Pexport package

  2. The package has been created in the file:

    projects>\work-order-lib\package\target\com.example.work-order-lib-1.0-SNAPSHOT.zip

  3. You can verify that the package contains the current code and previous definitions matching those seen in Innovation Studio. This requires looking in the def file embedded in the zip.

    Within this zip file you will find both the code bundle jar file and the def file containing your definitions.

    com.example.work-order-lib.manifest
    com.example.work-order-lib-1.0-SNAPSHOT.jar
    com.example.work-order-lib-1.0-SNAPSHOT.def
    

Preserving work using source control

The Innovation SDK does not mandate the use of any particular source control system. However the best practice is to check in any files that are edited and not generated. The definition file is a special case in that it is machine-edited by Innovation Suite (using Innovation Studio). The best practice is to coordinate with all developers on a project so that only one is current responsible for getting the def file from source control, and then deploying, modifying, exporting, and committing it back to source control.

Most likely you will wind up using a GUI or IDE plugin to manage source control, with or without Github. This article just captures the most basic use cases which can help in understanding what is happening with Github.

The rest of this article describes some specific techniques for using Github as the source control repository. There is no special support for Github and the best place to get information about Github is from github.com.

Using Github as the Original Developer

Set up the Github Repository

Go to Github.com, and if needed, create an account there.

Create a new repository "myproj" there. To avoid problems, do not initialize with any boilerplate files, such as README, license, or .gitignore.

images/docs/download/attachments/669191558/image2016-11-18_13_31_25.png

Back in your workspace (file system), create a small text file within the myproj folder called ". gitignore " . This will tell git not to place certain folders that are generated at build time under source control.

# exclude generated or boilerplate files
bundle/target/ 
bundle/node_modules/ 
package/target/

Initialize Local Repository

Within the project folder as the current working directory, use the following command to set up the git hidden files:

Root\myproj> git init 
Initialized empty Git repository in /Root/myproj/.git/ 
Stage Files 
Stage the files for first commit.  Note the "." as the current working directory. 
\Root\myproj>git add . 
warning: LF will be replaced by CRLF in bundle/Gruntfile.js. 
The file will have its original line endings in your working directory. 
warning: LF will be replaced by CRLF in bundle/karma.conf.js. 
The file will have its original line endings in your working directory. 
warning: LF will be replaced by CRLF in bundle/pom.xml. 
The file will have its original line endings in your working directory. 
warning: LF will be replaced by CRLF in package/src/assemblies/deployment-package.xml. 
The file will have its original line endings in your working directory. 
warning: LF will be replaced by CRLF in pom.xml. 
The file will have its original line endings in your working directory.

Commit Files

This begins the ability of tracking version changes to files.

Root\myproj> git commit –m "First commit" 
[master (root-commit) 772cbbb] First commit 
 Committer: jsmith <jsmith@example.com> 
 17 files changed, 1090 insertions(+) 

... (more output)

Add the Remote Repository

You will need the URL for the repository. This has a predictable pattern, or you can always get this from the Github repository page.

images/docs/download/attachments/669191558/image2016-11-18_13_31_49.png

Connect the local workspace and repository with the Github remote repository we created earlier, and verify it.

Root\myproj> git remote add origin https://github.com/dsulcer/myproj.git 
Root\myproj> git remote –v 
origin  https://github.com/dsulcer/myproj.git (fetch) 
origin  https://github.com/dsulcer/myproj.git (push)

Push the Files into the Remote Repository

We are finally ready to get the files up into the cloud.

Root\myproj> git push origin master 
Username for 'https://github.com': jsmith
Password for 'https://jsmith@github.com': 
Counting objects: 39, done. 
Delta compression using up to 4 threads. 
Compressing objects: 100% (26/26), done. 
Writing objects: 100% (39/39), 11.27 KiB | 0 bytes/s, done. 
Total 39 (delta 1), reused 0 (delta 0) 
remote: Resolving deltas: 100% (1/1), done. 
To https://github.com/jsmith/myproj.git 
 * [new branch]      master -> master

Verify that the files appear on Github .

images/docs/download/attachments/669191558/image2016-11-18_13_32_7.png

Working with Others

Getting Changes from Source Control

You can see what happens when other team members modify files by using the images/docs/download/attachments/669191558/image2016-11-18_13_32_25.png feature.

images/docs/download/attachments/669191558/image2016-11-18_13_32_37.png

Sync the workspace with remote changes:

Root\myproj> git pull origin master 
From https://github.com/jsmith/myproj 
 * branch            master     -> FETCH_HEAD 
Updating 772cbbb..72ec913 
Fast-forward 
 README.md | 2 ++ 
 1 file changed, 2 insertions(+) 
 create mode 100644 README.md  

Note that the README.md file has been brought down from the remote repository.

Root\myproj> type README.md 
# myproj
Share my amazing Innovation Suite library

Pushing Local Changes to Source Control

Let's say that I want to edit the file locally and push it back.

images/docs/download/attachments/669191558/image2016-11-18_13_32_58.png

Go through the staging, commit, and push.

Root\myproj> git add . 

You can check the status of the local repository.

Root\myproj> git status 
On branch master 
Changes to be committed: 
(use "git reset HEAD <file>..." to unstage) 
modified:   README.md  

Commit.

Root\myproj> git commit 

At this point, git automatically launches the "vi" text editor to get you to add a comment. If you don't know how "vi" works, type " i " to get insert mode, type your comment, then Esc- wq to save and quit.

images/docs/download/attachments/669191558/image2016-11-18_13_33_13.png

[master 4caa521] Update the readme. 
 Committer: jsmith <jsmith@bmc.com> 
 1 file changed, 2 insertions(+), 1 deletion(-)  

Push it to Github .

Root\myproj> git push origin master 
Username for 'https://github.com': jsmith
Password for 'https://jsmith@github.com': 
Counting objects: 3, done. 

Delta compression using up to 4 threads. 
Compressing objects: 100% (3/3), done. 
Writing objects: 100% (3/3), 350 bytes | 0 bytes/s, done. 
Total 3 (delta 1), reused 0 (delta 0) 
remote: Resolving deltas: 100% (1/1), completed with 1 local objects. 
To https://github.com/jsmith/myproj.git 
   72ec913..4caa521  master -> master

Verify it on Github .

images/docs/download/attachments/669191558/image2016-11-18_13_33_27.png

Setting up the Project as Team Member

Cloning the Project Source

This is simple enough.

OtherRoot> git clone https://github.com/dsulcer/myproj

One thing to be aware of is the project files that are specifically configured for your development server.

myproj\package\pom.xml 
myproj\bundle\bundle.conf.json

The correct settings are documented with the instructions for creating a new project from scratch.

When cloning a project that was checked in by someone else, be aware that t hese may contain settings that still point to the development server of a different team member. It is important to check this and be careful about not merging changes from GitHub here or excluding these files from checkin unless deliberately updating other settings in these files.

Building a Project Cloned from Github

Here is where it gets a bit tricky.

As a quick review, t he Innovation Suite uses the idea of a "package" as the unit of project management and deployment. It is also the scope of "definitions" authored and edited using an instance of Innovation Studio. These definitions are persisted in a single file known as a .DEF file.

If the package is known as " com.example. myproj ", the definition source file is found at:

OtherRoot\myproj\package\src\main\definitions\com.example.myproj-1.0-SNAPSHOT.def

This file can be thought of as a binary format, in that it is not very human readable, has arbitrary ordering characteristics, and in general is not safe to use with diff/merge tools. Therefore, it is imperative that only one developer and local development environment is used to manage updates to the definitions using Innovation Studio and commits and push to source control systems.

The collaborate development process is fully described at Developing collaborative smart applications.

What is s pecifically relevant here is that, either you are the owner of the definitions for this package or you are not – there can only safely be one.

If you already have the project deployed onto a existing working development instance with the latest definitions, y ou can resume building and deploying it in the standard fashion. Because the .DEF file may or may not be up to date, it is better to re-export it as part of your build.

OtherRoot\myproj> mvn clean install -Pexport -Pdeploy

If, however, you are setting up a new development instance of Innovation Suite, you should skip the export. In this case the assumption is that the .DEF file from GitHub is up to date.

OtherRoot\myproj> mvn clean install -Pdeploy

Updating the Repository

If you are NOT the definitions owner for the package, it is very important to exclude the .DEF file from any commit or push to GitHub. That's because the owner may be busy updating it, and merge is not supported.

You may still need to perform an export as part of your development cycle, for example to deploy code to your development instance, as described above.

If you ARE the package definitions owner, you should commit the .DEF file after any significant changes. An especially good time is after a successful –Pdeploy since it is certain to be in a valid state, and it will be easier to revert to an earlier version and redeploy if there is a problem.

OtherRoot\myproj> mvn -Pexport generate-resources 
OtherRoot\myproj> git add . 
OtherRoot\myproj> git commit 
OtherRoot\myproj> git push origin master

Conclusion

Obviously, experienced developers will apply their own best practices to manage code and definitions created with Innovation Suite. This article just points out one way to do it, and some of the considerations around special files that are used in the SDK and Innovation Studio.

Cleaning up after yourself

When preparing Innovation Studio for a new project, or after completing a project, you can reset the environment to remove bundles from a server so that they no longer appear. If your environment has not been used to develop any application or library bundles, then there is nothing to do.

If you have been following the exercises in this module, you can retain the current environment setup and proceed to future modules. Otherwise, you can remove any existing work from the server to set up the environment for another user, or to build a different application.

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 -b com.example.work-order-lib -u Admin -p adminpw -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 -b com.example.work-central-app -u Admin -p adminpw -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 Admin ...
    14:08:38.335 [main] INFO c.b.a.r.d.common.BaseApplication - User [Admin] 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.

Conclusion - Module 1

Congratulations! We have now covered the lifecycle of a development project, from requirements, design, creation, implementation, and packaging.

The work done in this learning path will be useful in subsequent tutorials, which will cover extending the application services in Java, extending the UI using AngularJS, and configuring and tailoring the application post-deployment.