Getting Started with the Prime Radiant

!(media/image1.jpg){width=”4.734375546806649in” height=”1.859375546806649in”}

Getting started with the Prime Radiant

Normalized Systems Institute

Version: 2016-11-10 (995b46d) Contents

  1. Introduction 5

  2. Exemplary universe of discussion 5

  3. Getting started 6

    1. Accessing the Prime Radiant . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

    2. Starting the Prime Radiant . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

    3. Stopping the Prime Radiant . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

    4. Exploring the graphical user interface . . . . . . . . . . . . . . . . . . . . . . 8

    5. Creating a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

    6. Importing and exporting a model . . . . . . . . . . . . . . . . . . . . . . . . . 13

  4. Defining data elements 15

    1. Creating a data element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    2. Creating fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

    3. Setting value fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

    4. Setting link fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

    5. Setting calculated fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

    6. Changing the displayed name of a data element instance . . . . . . . . . . . . 19

    7. Defining finders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

    8. Defining waterfall screens for linked data elements . . . . . . . . . . . . . . . 22

    9. Defining document upload and download functionality . . . . . . . . . . . . . 25

    10. Automatic report generation . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

    11. Adding an additional data element in the model . . . . . . . . . . . . . . . . 27

  5. Defining flow elements 28

    1. Flows as state machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    2. Creating a flow element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

    3. Specifying default state transitions . . . . . . . . . . . . . . . . . . . . . . . . 30

  6. Defining task elements 32

    1. Creating a task element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

    2. Implementing a task element . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

  7. Generating and running applications 34

    1. Out of the box functionalities . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

    2. Preparing the first application generation . . . . . . . . . . . . . . . . . . . . 34

    3. Expanding, building and deploying an application for the first time . . . . . . 35

    4. Running a deployed application . . . . . . . . . . . . . . . . . . . . . . . . . . 37

    5. Stopping a deployed application . . . . . . . . . . . . . . . . . . . . . . . . . . 37

    6. Generating and running a new version of an entered application . . . . . . . . 37

  8. Run-time actions 38

    1. Loading sample data into an application . . . . . . . . . . . . . . . . . . . . . 38

    2. Defining possible values for a listed value field . . . . . . . . . . . . . . . . . . 40

    3. Managing flows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

  9. User management 44

    1. Managing user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

    2. Defining access rights at runtime . . . . . . . . . . . . . . . . . . . . . . . . . 45

    3. Defining access rights at design time . . . . . . . . . . . . . . . . . . . . . . . 46

  10. Inspecting source code 48

    1. Dimensions of variability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

    2. Standard generated code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

    3. Insertions and extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

  11. Some basic customizations 49

    1. Adapting the top navigation bar and its menus . . . . . . . . . . . . . . . . . 49

    2. Labels and order of waterfall tabs . . . . . . . . . . . . . . . . . . . . . . . . . 51

  12. Updating the Prime Radiant 52

    1. Preparing the update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

    2. Performing the update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Appendices 53

Appendix A Frequently Asked Questions 53

  1. Using NS applications (and the Prime Radiant) . . . . . . . . . . . . . . . . . 53

  2. Running the Prime or a generated application . . . . . . . . . . . . . . . . . . 54

  3. (Re-)expanding and building applications . . . . . . . . . . . . . . . . . . . . 54

  4. General configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Appendix B Useful tables 58

  1. Tested value types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

  2. Non-functioning value types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

  3. Link field types (multiplicities) . . . . . . . . . . . . . . . . . . . . . . . . . . 58

  4. Data element options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

  5. Field options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

  6. Special fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59

  7. Protected words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Appendix C Cheat sheet 61

  1. Starting the Prime Radiant . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

  2. Stopping the Prime Radiant . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

  3. Starting a generated application . . . . . . . . . . . . . . . . . . . . . . . . . 61

  4. Stopping a generated application . . . . . . . . . . . . . . . . . . . . . . . . . 61

  5. Setting up a new application . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

  6. Expanding, building and deploying an application for the first time . . . . . . 62

  7. Regenerating an existing application . . . . . . . . . . . . . . . . . . . . . . . 62

  8. Importing a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

  9. Exporting a model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

  10. Add a data element . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

  11. Add a data field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

  12. Add a finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

  13. Add a waterfall screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64

  14. Change the displayed name of a data element . . . . . . . . . . . . . . . . . . 64

  15. Provide document upload/download . . . . . . . . . . . . . . . . . . . . . . . 65

  16. Provide a report . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

  17. Add a flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

  18. Start/stop a flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

  19. Specify state transitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

  20. Add a task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

  21. Import sample data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

  22. Specify list values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

  23. Adapt navigation menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

  24. Adapts labels and order of waterfall screens . . . . . . . . . . . . . . . . . . . 67

  25. Specify user accounts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

  26. Specify access rights . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

  27. Update the Prime Radiant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

Figure 1: Invoice flow

Introduction

The Prime Radiant is an application allowing users to define (and view, update, etcetera) Normalized Systems elements, which can be used as an input to generate Normalized Systems software. Further, the Prime Radiant allows analysts and developers to inspect the resulting applications in terms of several dimensions (data model, custom code, expander versions and underlying technology platforms).

This document provides a very brief and elementary introduction on how to get started with the Prime Radiant. We provide a short universe of discussion, and discuss how this small example can be defined in, and generated by, the Prime Radiant.

Exemplary universe of discussion

Suppose we want to track data regarding the following concepts:

  • Persons (attributes: first name, last name, age, position);

  • Orders (attributes: number, product, units, person);

  • Invoices (attributes: invoice number, net amount, total amount, order number, status);

Suppose we want to define tasks for performing the following tasks operating on the previously defined invoices:

  • send an invoice;

  • receive payment of an invoice;

  • book the invoice;

Suppose further that we want to define a flow of tasks operating on invoices as represented in Figure 1.

We assume that an analyst does not apply complex customizations (insertions or extensions) by himself, so we consider all actions (tasks) to be merely “empty” tasks resulting in state transitions.

Getting started

Accessing the Prime Radiant

In order to start defining and generating applications, users should either access an instance of the Prime Radiant made available online or install a copy on their own desktop.

To use a local installation of the Prime Radiant, users should copy the full “NSF” folder under the directory C:\\ in their Windows environment. Copying the files into another subfolder should be avoided due to the long filenames. As from here, we will use “PR ROOT” to refer to the directory in which the NSF folder is installed. In a standard situation, this therefore means that PR ROOT = C:\\NSF-3.0. Due to the number of files which have to be copied, the copying process can take a considerable amount of time, up to several minutes or hours. Once the Prime Radiant is installed, one can log in via the obtained username and password. The Prime Radiant can be started and stopped as described in the sections below.

As a general remark, it should be noted that each account has a certain “time out” period: if the time of inactivity exceeds this time out period, the user will automatically be logged out. When the user then attempts to access a new page within the Prime Radiant, a message will appear prompting the user to re-enter his username and password. When a form was opened and the time out occurs, the user will be able enter values in the field, but will not be able to save the new or adapted instance with these values. In order to proceed, the user should “refresh” the screen (e.g., by pressing F5), re-enter his username and password, and re-enter the information he was adapting.

Starting the Prime Radiant

A locally installed version of the Prime Radiant can be started in the following way:

  • Open a command prompt;

  • Change the directory to PR_ROOT (in a Windows environment a directory can be changed by means of the cd command in the command prompt)

  • Execute “startup prime radiant.bat”;

Starting the Prime Radiant can take some time, depending on the machine one is working on. It is possible that during start up, one SQLException is shown in the log, which is no problem for the further execution of the Prime Radiant. The Prime Radiant is running as soon as the message “J2EEServer. info : JOnAS AS v5.1.4 named ‘jonas’ RUNNING” is shown in the command prompt and can then be accessed via http://localhost:9000/primeRadiant/ in a browser.

Further, it should be remarked that the command prompt which was used to start the Prime Radiant should not be closed as long as the Prime Radiant is running (i.e., as long as the procedure as discussed in Section 3.3 is not carried out). It is also in this prompt that several log messages concerning the Prime Radiant will be displayed. Command prompts showing up when performing a script by clicking on a button^1^ can and should be closed after they have completed their functionality as leaving all these prompts open may lead to the situation in which all sockets of the computer one is working may become used, causing all other requested activities to “hang”. Only the command prompts of deployed and running applications (such as the Prime Radiant, but also applications developed by the user) should not be closed as long as the application is running.

Stopping the Prime Radiant

In case a locally installed version of the Prime Radiant is running, it should be closed in the following way:

  • Within the menu Software Constructs, select the menu item ApplicationInstance, tab ApplicationDeployment. Click “do stop” and “cleanup” for each deployed application.

  • Execute “jonas stop” within the PR_ROOT\\infrastructure\\jonas-full-5.1.4. \\BASE\\apps directory. The Prime Radiant is stopped as soon as the message

“CarolRegistryService. doStop : Carol Registry Service Stopped is shown in the command prompt and will no longer be available via the localhost in the browser.

  • In order to be able to start the Prime Radiant again later on, it is important to execute the “jonasCleanup.bat” script within the PR_ROOT\\infrastructure\\jonas-full-5.

1.4.\\BASE\\apps directory.

After all this has been done, all open command prompts (including that used to open the Prime Radiant) can be safely closed.

!(media/image2.jpg){width=”4.90005905511811in” height=”3.2332589676290464in”}

Figure 2: A standard login screen

Exploring the graphical user interface

Figure 2 shows the standard login screen of a deployed NS application (including the Prime Radiant itself). After successfully logging in, the start screen of the application will be shown. Typically, this consists of a nearly empty web page, apart from a navigation bar at the top of the screen. The tabs in this bar represent drop down menus via which the different elements of the application can be accessed (in order to be created-read-updateddeleted). For instance, in Figure 3 the top navigation bar with tabs such as “Functional Elements”, “Functional Configs”, “Software Configs”, etcetera is shown. When clicking on the “Functional Elements” menu, several menu items pop up such as “Application Track”, “Application”, “Component”, etcetera.

Figure 4 explains a set of recurring symbols used within the Graphical User Interface (GUI) of the Prime Radiant as well as within the standard lay-out of its generated applications once a particular data element screen has been selected. While using the Prime Radiant or its generated applications, instances of a particular element are typically listed as rows in tables. The columns represent properties (attributes) of these instances. It is important to be aware that additional details (associated information/elements) of an element instance can often be seen by selecting that particular element instance in a table (i.e., clicking the concerning row). In such case, possibly requiring the user to scroll down, a new table will show up

^1^E.g., prepare, provision, do start, do stop, execute (within the screen utils), build, expand, request deploy, etcetera as will be discussed in the following sections.

!(media/image3.jpg){width=”4.8999825021872265in” height=”2.287215660542432in”}

Figure 3: The start screen of the Prime Radiant.

!(media/image4.png){width=”1.8375317147856518in” height=”2.24916447944007in”}

Figure 4: The GUI used within the Prime Radiant

below the table in which a row was selected. This mechanism is labeled as “waterfall screens” and will be discussed more elaborately in Section 4.8. Additionally, detail information of an element instance mentioned in one of the columns of a table (thereby representing a link to another element instance), can often be seen when it is clickable (typically shown in blue in a browser). Further, instances shown in a table can be sorted (ascending or descending) alphabetically (for Strings) or in order of magnitude (for Integers) by clicking on the first row of a table (entailing the headers), after which an upwards or downwards arrow will appear in that column.

Creating a new application

Figure 5 represents a high-level overview of the skeleton of an NS application to be generated through the Prime Radiant. To start with, NS software applications consist out of set of

!(media/image5.png){width=”4.9in” height=”3.066666666666667in”}

Figure 5: A high-level overview of the skeleton of an NS application.

components (each consisting out of a set of elements). Using the NS expanders, 4 base components are already put at the disposal of the developer: “utils”, “validation”, “account” and “workflow” (at this point, we do not focus on the details of each of these components). Therefore, a NS software application typically consists out of a (sub)set of these base components as well as one or multiple components developed specifically for this application (although, as indicated in Figure 5, base and other components can be re-used in several applications). Different versions of the same application (e.g., having an updated model, or using another set of platform technologies) belong to one application track. Consequently, in order to start developing a new application, the user should “create” this new application track (e.g., Tutorial), application (e.g., TutorialApp) as well as a component (e.g., tutorialComp) within it. These actions can be executed by respectively selecting the menu items ApplicationTrack, Application and Component from the Functional Elements menu at the upper left corner of the screen and then pressing the “+” button.

For each application track, the following information should be provided:

  • Name: a name to identify the application track. As a naming convention, all application track names start with a capital;

  • Business owner: the organization for which the application track is developed;

  • Description (optional).

In case of our proposed universe of discussion this would become:

Name TutorialApp

Business owner NSI

Description

For each application, the following information should be provided:

  • Name: a name to identify the application, typically structured as [abbreviation of target organization]:[short name of application]. As a naming convention, all application names start with a capital;

  • Short name: a short name of the application to be used in overviews. As a naming convention, all application short names start with a lower case letter. Application short names should be written in one word and camel case is advised to combine different nouns in the name;

  • Version: typically starting at 1.0;

  • Base version: typically starting at 1.0;

  • Release period: the date at which the application is to be released;

  • Application track: the application track to which the application is linked;

  • Business owner: the organization for which the application is developed;

  • Model owner: the organization developing the model;

  • First architect: the person in charge of the development;

  • Model repository: specifies the location where descriptors to be imported are located, if applicable (default value: “Descriptors 3.0”);

  • Custom repository: specifies the location where custom code is located, typically the same directory as specified within the field “model repository”;

  • Description (optional);

  • Components: the components included in this application (can be added later, see Section 7.2);

  • Layout styles (optional).

In case of our proposed universe of discussion this would become:

Name EE:TutorialApp ———————– ————————————– Short name tutorialApp Version 1.0 Base version 1.0 Release period 01-01-2016 Application track TutorialApp Business owner NSI Model owner NSI First architect Peter Model repository Descriptors 3.0 Custom repository Descriptors 3.0 DescriptionComponents account, utils, validation, workflow Layout styles

For each component, the following information should be provided:

  • Name: a name to identify the component. As a naming convention, all component names start with a lower case letter. Component names should be written in one word and camel case is advised to combine different nouns in the name;

  • Full name: typically structured as [short name of application]:[component name];

  • Version: typically starting at 1.0;

  • Business owner: the organization for which the application is developed;

  • Model owner: the organization developing the model;

  • First analyst: the person in charge of the development;

  • Model repository: should equal the “model repository” location specified in the corresponding application;

  • Custom repository: should equal the “custom repository” location specified in the corresponding application;

  • Description (optional);

  • Main screen: optionally, a central data element of the component can be specified here: if so, the screen associated with this element will be shown as the home page for applications with this component;

  • Application: the application to which the component belongs.

In case of our proposed universe of discussion this would become:

Name tutorialComp

Full name tutorialApp:tutorialComp

Version 1.0

Business owner NSI

Model owner NSI

First analyst Peter

Model repository Descriptors 3.0

Custom repository Descriptors 3.0

Description

Main screen

Application EE: TutorialApp

Current bug when adding new components: first, only enter a value in the “name” field and click “submit”. Then, select the newly entered component, click the “update instance” button to enter all other information regarding the component and click “submit” to save all information. Adding information for all fields specifying a component at once will currently not work.

Regarding the other items mentioned in the metamodel of Figure 5, we refer to Section 4 for how to define Data Elements as well as the accompanying Data Fields, Finders and Data Element Options, to Section 5 for how to define Flow Elements, and to Section 6 for how to define Task Elements. Defining an Application Instance is only required when expanding, building and deploying an application for the first time and is therefore discussed in Section 7.3.

Importing and exporting a model

Exporting a model

When the model of an application is specified within the Prime Radiant, the model can be exported at the level of the application and at the level of individual components.

Regarding the component level, the data elements, task elements and flow elements created within the scope of a component (see Sections 4 till 5), can be exported into a file representing the component model. This can be done by going to the Functional Elements menu, selecting the Component menu item and selecting the component of which the model should be exported. Then, select the Perform tasks tab and choose between “Export model to file” or “Export model to dir”. The former option will export the component model into one XML file, whereas the latter will create a hierarchical map structure containing separate XML files for each data element in the component (which may be beneficial when used in combination with a version management system to track changes in the model and facilitate collaboration among model builders). Afterwards, the model (hierarchy) can be found at PR_ROOT\\workspace
\descriptors\\components\\[componentname]\\models\\[timestampeddatamodel].

Regarding the application level, an overview of the components used within an application as well as the set of formulated data flow tasks can be exported into a file representing the application model. This can be done by going to the Functional Elements menu, selecting the Application menu item and selecting the application of which the model should be exported. Then, select the Application actions tab and click the “export to file” button. This will general an XML file which can be found at PR_ROOT\\workspace\\descriptors\

\applications\\[applicationname]\\model\\[applicationname]\\[model]. In addition, clicking the “Export dataFlowTasks” button within the same Application actions tab will generate a CSV file which can be used to import the default formulated state transitions in a deployed application (see Section 8.3). This file can subsequently be found at PR_ROOT\

\workspace\\descriptors\\applications\\[applicationname]\\data\\csv\\StateTasks. csv.

Importing a model

In order to import an existing model, check whether a Component for this model was already created previously in the Prime Radiant (i.e., a previous version of the model is present). If not, a new Component should be created, with a name and version corresponding to the component model to be imported (and values for the Model repository and Custom repository filled in as usual), as discussed in Section 3.5.

Next, the XML file containing the model (i.e., not the hierarchical set of XML files) should be placed at PR_ROOT\\workspace\\descriptors\\components\\[componentname]\\models and named as [ComponentName]-[ComponentVersion].xml. Remark that in case a component is imported from scratch, the directories \\[componentname]\\models have to created manually. Afterwards, go to the Functional Elements menu, select the Component menu item and select the component of which the model should be imported. The model can now be imported by clicking on the “Import model from file” button. Check the resulting command prompt for any errors. If no errors occurred, the imported data elements, fields, finders, etcetera can now be inspected by going to the Functional Elements menu, selecting the Component menu item and selecting the concerning component and its tabs.

Defining data elements

Creating a data element

After selecting the component one wants to create the data element in, an additional data element can be created by clicking on the the “+” in the Data elements tab.

For each data element, the following information has to be provided:

  • Name: a name to identify the data element. As a naming convention, all element names start with a capital. Data element names should be written in one word and camel case is advised to combine different nouns in the name;

  • Package name: the package name in which the data element will be incorporated (e.g., a domain name such as be.uantwerpen.ee);

  • Description (optional);

  • Component: the component of the application in which the data element will be incorporated, having a predefined value;

In case of our proposed universe of discussion this would become for our three data elements:

Name Person Order Invoice

Package name be.uantwerpen.ee be.uantwerpen.ee be.uantwerpen.ee

Description — — —

Component tutorialComp tutorialComp tutorialComp

Now, each of these data elements can be seen under the component tutorialComp.

Creating fields

When a particular data element within the component is selected, the set of attributes or fields for this element can be seen and updated. For instance, additional attributes can be created by clicking on the “+” in the tab Fields. For each attribute of a data element, the following information has to be provided:

  • Name: a name to identify the field. Avoid using names that are typically used as “reserved words” in most programming languages, such as ‘package’, ‘long’, ‘case’, ‘import’, ‘export’, ‘var’, ‘parameters’, ‘interface’, ‘name’, ‘string’, ‘function’, etcetera. As a (mandatory) naming convention, field names start with a lower case letter. Field names should be written in one word and camel case is advised to combine different nouns in the name (which causes the different nouns to be displayed as different words in the columns of tables later on);

  • Field type: VALUE FIELD (new value entered), LINK FIELD (value linked to an already existing data element) or CALCULATED FIELD (value calculated based on other fields);

  • Description (optional);

  • Is info field (checkbox): if checked, this field becomes incorporated in the generated overview screens. If not checked, the field will only appear when the details of individual instances of a data element are requested;

  • Is list field (checkbox): if checked, users can only pick a value from a limited list of possible values which is predefined for this particular field. The set of potential values for an attribute of a value field with the option “is list field” should be defined at run time. For more information about the specification of this set of values, see Section 8.2; • Data element: the element to which the field belongs, having a predefined value;

In case of our proposed universe of discussion, the requested attributes for the Person data element could be created as follows:

Name firstName lastName age position ——————- ————- ————- ————- ————- Field type VALUE FIELD VALUE FIELD VALUE FIELD VALUE FIELD Description — — — — Is info field x x x x Is list field — — — — Data Element Person Person Person Person

Now, each of these fields is automatically presented when the respective data element is selected in the corresponding component. In Section 4.9, we will discuss a way to configure fields so that they allow the user to upload or download documents.

Setting value fields

For a field of field type VALUE FIELD, a further specification of its type should be made by selecting the concerning field, selecting the tab Field type details in the table below and clicking on the “+” button, after which the following information has to be provided:

  • Name: a name to identify the Value Field, having a predefined value typically structured as ValueField:DataElement field;

  • Field: the field to which it is related, having a predefined value;

  • Data Element: the data element to which it is related, having a predefined value;

  • Value field type: basic Java data types can be chosen such as String, Integer, Short, Long, Double, StringLong, Date, etcetera;

In case of our proposed universe of discussion, this would become for the attributes of the Person data element:

+—————–+—————–+—————–+—————–+ | | > Name | ValueField:Pers | > ValueField:Pe | | | | on | rson | | | | firstName | > lastName | +=================+=================+=================+=================+ | | > Field | firstName | > lastName | +—————–+—————–+—————–+—————–+ | | > Data | Person | > Person | | | > Element | | | +—————–+—————–+—————–+—————–+ | and | > Value field | String | > String | | | > type | | | +—————–+—————–+—————–+—————–+ | | Name | > ValueField:Pe | ValueField:Pers | | | | rson | on | | | | > age | position | +—————–+—————–+—————–+—————–+ | | Field | > age | position | +—————–+—————–+—————–+—————–+ | | Data | Person | | | | Element | | | | | Person | | | +—————–+—————–+—————–+—————–+ | | Value field | String | | | | type Integer | | | +—————–+—————–+—————–+—————–+

Next to fields in which new values have to entered, also “link fields” can be created. These fields refer to an instance of another data element in the application. For such fields, the “field type” is set to LINK FIELD. For instance, the “person” attribute of an Order data element instance should refer to an instance of the Person data element. The general configuration of this field is as follows:

Name person ——————- ———— Field type LINK FIELD DescriptionIs info field x Is list fieldData Element Order

For a field of field type LINK FIELD, a further specification of its type should be made by selecting the tab Field type details and clicking on the “+” button, after which the following information has to be provided:

  • Name: a name to identify the Link Field, having a predefined value typically structured as LinkField:DataElement field;

  • Field: the field to which it is related, having a predefined value;

  • Data Element: the data element to which the field belongs, having a predefined value;

  • Link field type: defining the multiplicity (cf. infra);

  • Target class: the element to which the field refers.

  • Target package: the package in which the target class is situated. In case the the element to which the field refers is situated in another component, this value should be structured as [componentName].jar#[packageName];

Regarding the Link field type: the option Ln01 represents a many-to-one link (e.g., many Orders can be related to one Person). The option Ln05 can be used (but is not mandatory) to represent the associated one-to-many link (in that case, being the reverse Ln01, a Ln01 link needs to be defined at the other side of the relationship). When applied, the name of the corresponding Ln01 field needs to be identical to the name of the element where the Ln05 link is specified and a findBy<element>Eq finder (cf. infra) needs to be specified for the data element where the Ln01 relation is defined1.

In case of our proposed universe of discussion, this would become for the “person” attribute of the Order data element:

Name LinkField:Order person

Field person

Data Element Order

Link field type Ln01

Target class Person

Target package be.uantwerpen.ee

One can remark that the discussed Link field types do not contain an option for putting a

!(media/image6.jpg){width=”2.449925634295713in” height=”1.5947626859142607in”}

Figure 6: Selecting Persons for an Order without the specification of display name.

one-to-one relation between two elements. In case such relationship is required, we advice to define a regular many-to-one (Ln01) link between the concerning elements. Later on, a restriction or validation (by means of a customization) should be added to the code to enforce that only one child element instance may be related to the parent data element.

Setting calculated fields

A calculated field is a field whose value is determined by performing an operation or calculation on one or multiple other fields. For such fields, the “field type” is set to CALCULATED FIELD. For instance, the “totalAmount” field of the Invoice data element could be the result of multiplying the value of the field “netAmount” by 1.21 (e.g., due to the addition of VAT). The general configuration of this field is as follows:

Name totalAmount ——————- —————— Field type CALCULATED FIELD DescriptionIs info field x Is list fieldData Element Invoice

In the same way as discussed in Section 4.3 for value fields, calculated fields require a further specification of their value field type (e.g., String, boolean, etcetera). Implementing the actual calculation of such fields should be done by adding insertions, which are out of scope of this starters manual.

Changing the displayed name of a data element instance

When defining the fields of a data element, one can optionally create a field “name”. Such field will automatically be used to uniquely identify and display data element instances in a deployed application to the user, which is important to select a particular instance when linking it to another (e.g., selecting a particular Person as the customer placing a particular Order via its name). In case one does not choose to have such name field for a particular data element, the application will automatically generate a name such as a the first letter of the element followed by a serial number. It is clear that such ID is typically very difficult to be understood by the end user. For instance, the Person element in our proposed universe of discussion does not have a “name” field —as we had to create separate fields for the first and last name of a person— and when selecting a corresponding Person when creating a new Order we have to choose from a set of instances labeled as “P-1”, “P-2”, etcetera as shown in Figure 6. These IDs will for example also be used to display the references to Persons in the corresponding column of the Order table/screen. This automatically displayed name can however still be modified. This is done by selecting the concerning data element, going to the tab Data options and providing the following information:

  • Name: typically structured as DataElement:hasDisplayName;

  • Value: determines what will be shown to the user in the generated application, by specifying one or multiple data field names of the concerning data element. Multiple data fields should be separated by an underscore (“ “);

  • Data Element: the data element regarding which one is defining the data option, having a predefined value;

  • Data option type: standard value = hasDisplayName;

For instance, in case we want to modify the displayed name for Persons so that the first and lastname is shown, this would become:

Name Person:hasDisplayName

Value firstName lastName

Data element Person

Data option type hasDisplayName

Afterwards, Persons can be selected by means of their first and last name and will be shown in the corresponding column of the Order table/screen in this way as well, as depicted in Figure 7.

Make sure to only specify (a combination of) existing fields as the value of such hasDisplayName data element option as inserting non-existing fields will result in errors during the expansion and/or building of the actual application.

!(media/image7.jpg){width=”4.287456255468067in” height=”1.352638888888889in”}

Figure 7: The Order table/screen with a specified display name.

Defining finders

The NS expanders provide the possibility of automatically generating a set of search or finder methods for defined data elements. In order to create a finder for a specific data element, one has to select the tab Finders for that data element and press the “+” button. For each finder, the following information has to be provided:

  • Name: a name to identify the finder;

  • Description (optional);

  • Data element: the data element on which the finder is operating, having a predefined value.

By convention, a finder which has to return all instances of that data element is named findAllDataElements (remark the “s” added in the end). For instance, suppose we want to add a finder to the Person data element which returns all persons stored in the application, we define the following finder:

Name findAllPersons

Description

Data element Person

More complex finders can be defined as well. The name of such method starts with the prefix findBy. Next, the field used to perform the selection in the finder method (e.g., number) is mentioned, as well as a modifier (e.g., Eq). This modifier can take three possible values:

  • Eq: equal to;

  • Gt: greater than;

  • Lt: less than.

For instance, suppose we want to add a finder to the Order data element which returns all orders with an order number equal to the String specified by the user, we define the following finder:

Name findByNumberEq

Description

Data element Order

Also finders having multiple criteria can be defined. For instance, suppose we want to add a finder to the Invoice data element which returns all invoices exceeding a certain net amount and being in particular status. For this purpose, we first define the finder itself:

Name findByStatusEq NetAmountGt

Description

Data element Invoice

Remark that in case we have several criteria related to one finder, the criteria mentioned in the finder name are separated by an underscore (“ “). After a (new) finder has been created, the “complete data finders” button which can be accessed via Perform Tasks tab in the waterfall screen of each data element, needs to be clicked. This will automatically fill in some “field-operator pairs” (based on the name of the finders) in order to assure the correct expansion of these finders afterwards.

By default, two finders should be created for every data element, i.e., findAllElements and findByNameEq. By correctly executing the component tasks while preparing an application to be expanded and built (as discussed in Section 7.2), the Prime Radiant will automatically check whether these finders exist and, if not, create them at that point in time.

When performing search operations once the application is expanded, built and deployed, the “%” sign acts as a wildcard for all characters starting from the one where it is used. For instance, when entering “Ver%” as a search criterion for the last name of person, will return the values “Verelst”, “Verstegen”, etcetera. Further, it should be noted that search operations in NS software are case sensitive.

Defining waterfall screens for linked data elements

For elements having a one-to-many relation (via a Ln01 Link Field in the child data element, see Section 4.4), so-called “waterfall screens” can be defined between data elements. Such screens show all “child” instances related to one particular “parent” instance in a table below the table in which the parent instance is selected. Figure 8 for instance illustrates such waterfall screen for a Person data element being associated with one or multiple Orders.

!(media/image8.jpg){width=”4.594026684164479in” height=”3.2008278652668416in”}

Figure 8: Example of a waterfall screen Person-Order

Such waterfall screen can be added by selecting the parent data element in the screen after going to the Functional Elements menu and selecting the Component menu item. Select, after selecting the relevant parent data element, tab Data children, and add a new instance by providing the following information:

  • Data element: the data element in which the waterfall screen is embedded (the parent data element), having a predefined value;

  • Child component: the component in which the child data element is defined;

  • Child element: the name of the child data element;

  • Child field: the data field of the child data element which is referring to the parent data element.

In case of our proposed universe of discussion, it could be useful to have a waterfall screen for the one-to-many relationship between Person and Order as defined in Section 4.4:

Data element Person

Child component tutorialComp

Child element Order

Child field person

In order to allow a working waterfall screen, select the “Perform task” tab of the concerning parent data element and click the button “Extend user interface”. Additionally, a findByPar-

!(media/image9.jpg){width=”6.1248687664042in” height=”1.7479965004374454in”}

Figure 9: Example of a waterfall screen with multiple data children within one level

!(media/image10.jpg){width=”6.124882983377078in” height=”3.3550634295713038in”}

Figure 10: Example of a waterfall screen having multiple layers: Person-Order-Invoice.

entEq finder should be defined in the child element. However, clicking the “Create default finders” button while preparing the application expansion and building (see Section 7.2) will automatically check for the existence of such finder and create any required but missing finders. The definition of a(n) (additional) waterfall screen requires the re-expansion (as waterfall screens need to be injected) and building of an application (see Section 7.6). The result of specifying the Person-Order waterfall screen as mentioned above is the screen as shown in Figure 8 (after expansion, building and deployment).

For a data element having multiple one-to-many relations (e.g., a Person having multiple Orders and multiple Locations), multiple data children (within one level) can be defined. In such case, a waterfall screen with multiple tabs will automatically be generated (according to the number of data children defined) as is shown for another application in Figure 9.

Moreover, it is possible to define recursive waterfall screens. That is, if we define a data child instance to express the need for having a waterfall screen Order-Invoice in an analogous way as we did for Person-Order, not only the Order screen will provide a waterfall screen with a tab “Invoices” but also the Person screen will automatically have this waterfall screen embedded as a second-order waterfall screen as shown in Figure 10. Currently, up to 6 levels of waterfall screens can automatically be generated by the Prime Radiant. Circular links (e.g., ABCA) should be avoided.

Defining document upload and download functionality

Document upload and download functionality can be provided by adding a data field to a data element (for a more general explanation, see Section 4.2) with the (mandatory name) uploadUri. This field should be a Value Field of the type StringFile. Due to this mandatory name, it should be remarked that it is often more clear to separate this field in its own data element, for which the name can then be chosen freely.

In case of our proposed universe of discussion, it could be useful to have an upload/download functionality for each Invoice (e.g., in case the actual legal document needs to be stored). This could be done by (after selecting the Functional Elements menu, selecting the Component menu item and selecting the tutorialComp component) selecting the Invoice data element, and adding a new field within the fields tab as follows:

+——————-+—————+ | Name | > uploadUri | +===================+===============+ | Field type | > Value Field | +——————-+—————+ | Description | > — | +——————-+—————+ | Is info field | > x | +——————-+—————+ | Is list field | > — | +——————-+—————+ | Data element | > Invoice | +——————-+—————+

and afterwards specifying the field type details for this field as follows:

Name ValueField:Invoice uploadUri

Field uploadUri

Data element Invoice

Value field type StringFile

!(media/image11.jpg){width=”4.900040463692038in” height=”3.242770122484689in”}

Figure 11: Report of the Person instance Jan Peeters.

Automatic report generation

The Prime Radiant provides easy out of the box reporting functionality regarding data element instances. These standard reports contain tables showing all String fields2 and their values of a chosen data element instance, as well as the details of all first-order child data element instances. An example of such report can be found in Figure 11. Here, the report for one particular Person is shown: the values of all String fields (first name, last name and position) as well as those of its first-order child data element instances (i.e., in this case instances of Orders) are shown (in case a data element has multiple first-order child data elements, the instances of all different child data elements will be included in the report).

The need to generate and obtain reports regarding instances of a particular data element in a running application, should be indicated in the model of the application in the Prime Radiant (i.e., at design time) at the level of individual data elements. In order to do so, select the menu Functional Elements, menu item Component and subsequently the concerning component and data element. Select the tab “Perform tasks” of the waterfall screen of this data element and press the button “Create data reporting”. This will automatically create a new DataElementReporterTask allowing the user in the working application to generate a new version of a report for a particular instance of the data element with the most recent field values of that instance. This report will contain the logo located at PR\_ROOT\repositories\primeRadiant\conf\jasper\logoName.jpg. Furthermore, a new

!(media/image12.jpg){width=”4.9000656167979in” height=”2.951233595800525in”}

Figure 12: Report of the Person instance Jan Peeters.

field reportLink within the concerning data element will be created allowing the user to download a generated report via a clickable link (possibly only appearing after the user clicked the refresh button of that data element). As with the creation of any waterfall screen due to the addition of a task or data child, press the button “Extend user interface” so that the newly created DataElementReporterTask becomes accessible via a button in the tab “Perform tasks” of the waterfall screen of the concerning data element.

Suppose we want to create report generation functionality for the user of our application regarding instances of the Person data element. In order to do so, we click the “Create data reporting” button in the “Perform task” tab of the waterfall screen of the Person data element. After pressing the “Extend user interface” button and expanding, building and deploying the application (see Section 7.3), a report such as the one shown in Figure 11 can be created by selecting a particular Person instance and pressing the PersonReporterTask button in the “Perform task” waterfall screen tab as shown in Figure 12. A report link field next to the selected instance will be created (possibly only appearing after the user clicked the refresh button) and allow the download of the generated report. Alternatively, users can find all generated reports at the following location: PR\_ROOT\infrastructure\jonas-full-5.1.

4\[deploymentBase]\reports.

Adding an additional data element in the model

Currently, if an application is expanded, a resulting prototype is built, and afterwards some new elements are added to be incorporated in a next version of the prototype, the new data elements will be added to the application, but will not appear in the menu. This is because the Prime Radiant will not overwrite a menu file when this already exists, as it may be customized.

A current work around is to go the file located at PR_ROOT\\workspace\\descriptors\

\applications\\(applicationName)\\harvest\\control\\struts2\\resources\\menu and to edit the file in an analogous way for the new element added (see Section 11.1). Newly entered menu items and submenus will become visible in the application after a new expand/build of the concerning application. Alternatively, one could opt for deleting this file, clicking the button “Provision” of the concerning Application Instance and let the Prime Radiant automatically regenerate this menu (now with the additional data element incorporated).

Defining flow elements

Flows as state machines

In order to implement NS applications, traditional business processes have to be translated into state machines. This means that each flow is conceived as a sequence of tasks (i.e., a flow) operating on a single data element. A task embedded in a flow is executed whenever an instance of the data element (on which the flow is operating) is in a particular state (i.e., the “begin state”). During the time period in which the task is being executed, that state is altered into another state (i.e., the “interim state”). When the task has been completed, the state is altered again into an “end state” (in case the task was successfully executed) or a “failed state” (in all other cases). As a consequence, adding processing functionality to an NS application having data elements, should start with the creation of flow elements. An example of a visualization of a flow as a set of tasks (boxes) resulting in state transitions (black dots) operating on a data element was provided in Figure 1 on page 5.

Creating a flow element

After selecting the component one wants to create the flow element in, an additional flow element can be created by clicking on the the “+” in the tab Flow elements.

For each flow element, the following information has to be provided:

  • Flow: a name to identify the flow. As a naming convention, all flow elements start with a capital and carry the same name as the data element on which they operate;

  • Package name: the package name in which the flow element will be incorporated;

  • Target class: the data element on which the flow is operating, structured as [package name].[DataElement];

  • Status field: field of the data element in which the status of the flow is stored, typically called “status” In case the field “Status” is specified here but not present as a field in the concerning data element, a status field will automatically be created and set during expansion (cf. infra);

  • Workflow name: the name of the flow on the data element, typically structured as DataElementFlow;

  • Archive name: only required when using old version of EJB, may be left empty in all other cases;

  • Description (optional);

  • Component: the component of the application in which the flow element will be incorporated, having a predefined value;

As stated above, a status field (if missing) can also be generated by the Prime Radiant itself. Note that in the specification of the flow, “Status” is starting with a capital but the automatically generated field will be “status”, starting with a lower case letter. As several settings are automatically set to the appropriate values in this way, this option is currently recommended. However, in case a status field is created manually upfront, the field should be a value field of the value field type String (see Section 4.3), having two field options (one named “status:isExposedField” with option type “isExposedField” and one named “status:isStatusField” with option type “isStatusField”) defined onto it, and a findByStatusEq finder (see Section 4.7).

The required information to define a flow on the Invoice data element requested from our universe of discussion then becomes:

Name Invoice ——————- ————————– Package name be.uantwerpen.ee Target class be.uantwerpen.ee.Invoice Status field Status Workflow name InvoiceFlow Archive nameDescriptionComponent tutorialComp

After a flow is defined in this way, one should choose the Perform tasks tab while the respective component is still selected, and click the “Create flow environment” button. This will automatically create a status field if required, an additional data element (DataElementTaskStatus) and a test task (DataElementTesterTask). Afterwards, it is advised to click to the “Create default finders” button to check for and create any missing but required finders created by the previous action.

Specifying default state transitions

The definition of start states and end states in relation to the tasks which are actually executed within a flow can be configured and modified during the run-time of the actual application. This means that the specific filling-in of these flows can occur and be updated after the application has been expanded, built and deployed. In order to do so, the reader should first perform the actions as specified in Section 7 to expand, build and deploy an application. Remark that in case a flow is added to an application which was already build and deployed before, a variant of the activities to expand, build and generate an application applies (see Section 7.6). Afterwards, one can go to Section 8.3 in order to activate flows and specify actual state transitions. Obviously, the activation/deactivation and execution of flows (and their tasks) on instances of data elements can only happen once the application is running.

Alternatively, a standard or default flow can be specified within the model defined by using the Prime Radiant. For this purpose, first, a set of possible data states should be specified at the level of the data element on which the flow is operating. Therefore, within the Functional Elements menu, select the Component menu item. Choose the relevant component and (in the associated waterfall screen) the relevant Data Element. In the next waterfall screen, select the DataState tab. Now, data states can be added or modified.

For each data state, the following information has to be provided:

  • Name: the name of the state;

  • Data element: the name of the data element to which the state relates, having a predefined value;

Remark that states are preferably defined in one word (camel case is advised to combine different nouns). In case of our proposed universe of discussion, this would imply the specification of the following states for the Invoice data element:

Name Initiated Sent Paid Booked

Data Element Invoice Invoice Invoice Invoice

Second, the state transitions (i.e., which states cause a task to be executed, and in which state does this result) of an application can be specified at the level of the application. This is done by selecting the Functional Elements menu and the Application menu item. Choose the concerning application and select the DataFlowTask tab in the waterfall screen. Now, data flow tasks can be added.

For each data flow task, the following information has to be provided:

  • Name: the name of the task to be executed;

  • Begin state: the state (value of the status field of the data element on which the flow is operating) indicating that the task has to be executed, to be selected from the list of data states defined previously;

  • End state: the state (value of the status field of the data element on which the flow is operating) indicating the successful completion of the executed task, to be selected from the list of data states defined previously;

  • Failed state: the state (value of the status field of the data element on which the flow is operating) indicating the unsuccessful completion of the executed task, to be selected from the list of data states defined previously;

  • Interim state: the state (value of the status field of the data element on which the flow is operating) indicating that the task is in progress of being executed, to be selected from the list of data states defined previously;

  • Flow element: the name of the corresponding flow element;

  • Type: this field is currently not used, so should be left empty;

  • Application: the name of the application to which the flow belongs, having a predefined value;

From the above description, it becomes clear that not only successful states (indicating the “happy path”), but equally failed states (also enabling some kind of branching) and interim states should be formulated. This means that also for the Invoice data element within our universe of discussion, additional states are required to be created upfront (i.e., SendingFailed, PaymentFailed, BookingFailed, SendingBusy, PaymentBusy, BookingBusy). Afterwards, the following data flow tasks for the Invoice flow would become:

Name InvoiceSender InvoicePaymentReceiver InvoiceBooker ——————- ————— ———————— ————— Begin state Initiated Sent Paid End state Sent Paid Booked Failed state SendingFailed PaymentFailed BookingFailed Interim state SendingBusy PaymentBusy BookingBusy Flow element Invoice Invoice Invoice Type — — — Application TutorialApp TutorialApp TutorialApp

The name mentioned in each of the data flow tasks should clearly map a task element within the model (see Section 6). In our illustration mentioned above, the different state tasks are executed by different tasks, as could be expected in a realistic production environment. In an initial testing and prototyping stage of the system development lifecyle however, the same task for all specified state transitions (and therefore data flow tasks). Typically, an [DataElement]TesterTask will be used for this purpose (see also Section 8.3). This avoids that the analyst is required to actually implement working code in each of these tasks during these initial phases were a mere illustration of the flow of states itself is typically sufficient. Moreover, we do not explain task implementations in this starters manual and the main goal of analysts is to show the occurrence of flows, not their actual coded implementation.

In order to activate the specified flow(s) from the model, the data flow tasks should be exported into a CSV file (see Section 3.6) and subsequently be imported once the application itself has been expanded, built and deployed (see Section 8.3).

Defining task elements

Creating a task element

Referring to Section 5.3, we remark again that for analysis purposes, we propose to reuse to an automatically generated test task for a flow to demonstrate the working of flows. Furthermore, when using the automatic data reporting functionality (see Section 4.10), a DataElementReporterTask is automatically created by the Prime Radiant. However, other tasks can be manually defined as well in the Prime Radiant, if wanted. After selecting the component one wants to create the task element in, an additional task element can be created by clicking on the the “+” in the tab Task elements.

For each task element, the following information has to be provided:

  • Name: a name to identify the task. As a naming convention, all element names start with a capital. Task names should be written in one word and camel case is advised to combine different nouns in the name;

  • Package name: the package name in which the task element will be incorporated;

  • Target class: the details class of the data element on which the task will operate, typically structured as packageName.DataElementDetails;

  • Param class (optional): if included, typically structured as packageName.TaskElementParams;

  • Description (optional);

  • Component: the component of the application in which the task element will be incorporated;

In case of our proposed universe of discussion, this would become for the InvoiceSender and InvoicePaymentReceiver tasks operating on the Order data element:

Name InvoiceSender InvoicePaymentReceiver —————— ——————————— ——————————— Package name be.uantwerpen.ee be.uantwerpen.ee Target class be.uantwerpen.ee.InvoiceDetails be.uantwerpen.ee.InvoiceDetails Param class — — Description — — Component tutorialComp tutorialComp

Now, each of these data elements can be seen under the component “tutorialComp”.

Continue by selecting the “Perform tasks” tab of the data element on which the task will operate and click the “Extend user interface” button. After expanding, building and deploying the application (see Section 7.3), each task will be able to be executed manually via a button. This button can be accessed by selecting a data element instance on which the task can be executed and clicking on the “Perform tasks” tab which shows up in a waterfall screen (as is shown in Figure 12 on page 27 in the context of data reporting).

Implementing a task element

As stated before, we do not consider any customizations (insertions or extensions) at this point, so all actions (tasks) are merely “empty” tasks resulting in state transitions. In case actual business logic would be incorporated, this logic would be implemented between predefined anchors within the TaskElementImpl.java class.

Generating and running applications

Out of the box functionalities

Once data, task and flows elements are all defined, an application can be generated for a specific technology stack by the Prime Radiant based on this input. Not all accounts are granted the permission to perform this generation by themselves.

For every data element, typical CRUD (create-read-update-delete) functionality is provided by means of a similar GUI as used within the Prime Radiant itself and the symbols presented in Figure 4. Further, all specified finder (search) methods will be incorporated (see Section 4.7). Waterfall screens defined for elements having a many-to-one relation (as discussed in Section 4.8) or for task buttons to generate reports (as discussed in Section 4.10), are provided. For each defined flow, state transitions and engines can be specified. Finally, in such expanded application, insertions (e.g., providing specific business functionality in the provided tasks at well-specified places —“anchors”— in the generated code) and extensions can be added. However, as mentioned before, we currently consider complex customizations as they are out of scope for this starters manual.

Preparing the first application generation

Verifying all required components in the application

Before starting to expand the application or performing any of the other preparatory actions, users should check whether all required components are listed in the “Components” field of the considered application. Typically, this involves the base components “utils”, “validation”, “account”, “workflow” as well as one or more components for the specific application one is developing.

Performing component tasks

For all components which are specifically created for the application one is developing, one should choose the menu Functional Elements, menu item Component and select the considered component. Then, within the tab Perform tasks, the buttons “Create base dependencies” and “Create default finders” should be clicked. The other buttons visible in this tab are discussed in other sections (i.e., Sections 3.6 and 5.2), except from the “Create data command log” which is out of scope of this starters manual.

Expanding, building and deploying an application for the first time

In order to expand and build an application, an Application Instance should first be created. Go to the Functional Elements menu, and select the Application menu item. Select the concerning application in the table, and select the Application instances tab below. A new Application Instance can be created by clicking the “+” button. For each Application Instance, the following information should be entered:

  • Name: a name to identify the application instance As a naming convention, all application instances start with a capital;

  • Short name: a short name to be used in the overviews. Important remark: in the current version of the Prime Radiant it is required that this field has the same name as the short name of the corresponding application!

  • Application: the application regarding which the application instance is concerned, having a predefined value;

  • Version: typically starting at 1.0;

  • Description (optional);

  • Status: reflecting the status of the application instance, typically starting at Created;

  • Release date: the date at which the application instance is to be release;

  • Custom base: specifies the location where the custom code is situated, this should map the custom repository value of the corresponding application and component (at this moment, typically Descriptors 3.0);

  • Expand base: specifies the location where the expanded code is situated (at this moment, typically Expansions 3.0 - PR);

  • Expander version: the version of the expanders to be used (current version: 3.0.3);

  • Global option setting: standard value = 3.0 default;

  • Presentation settings: standard value = 3.0 default;

  • Business logic settings: standard value = Standard HSQL;

  • Technical infrastructure: standard value = 3.0 default;

  • Deploy base: currently two bases are provided in a locally installed Prime Radiant, allowing for two applications deployed via the Prime Radiant to be running concurrently.

Therefore, in a standard situation one should choose for “BASE 3.0 - 2” or “BASE 3.0 - 3”, depending on the applications one wants to run simultaneously.

For instance, for our exemplary application, this could become:

Name Tutorial App —————————— ——————— Short name tutorialApp Application EE:TutorialApp Version 1.0 Status Created Release date 01-01-2016 Custom base Descriptors 3.0 Expand base Expansions 3.0 - PR Expander version 3.0.3 Global option settings 3.0 Default Presentation settings 3.0 Default Business logic settings Standards HSQL Technical infrastructure 3.0 Default Deploy base BASE 3.0 - 2

Go to the Software Constructs menu, and select the ApplicationInstance menu item. After the newly created Application Instance has been selected, the buttons “Provision” (to set some configuration options and generate the menu), “Expand” (to expand the source code based on the provided model) and “Build” (in order to compile the expanded code) should be clicked within the Application instance actions tab. When letting the application expand, an error can be shown in the command prompt regarding a failure to read the input for injections. As long as no injections (or waterfall screens, which are automatically converted into injections) are provided for an application, this error is normal and will not hamper the proper building and execution of the application (the message will not be shown any longer as soon as injections or waterfall screens are incorporated in the expansion process). Other potentially occurring errors which show up during the provisioning, building or expansion of the application should be scrutinized and fixed before continuing (i.e., deploying/running the application). Afterwards, the button “Request deploy” should be clicked in order to request the deployment of the application instance. The other buttons visible in this tab are required to perform more advanced functionalities with the Prime Radiant and are not discussed in this starters manual.

Running a deployed application

In order to run a deployed application, one should select the ApplicationInstance menu item in the Software Constructs menu. Select the concerning application and go the tab ApplicationDeployment . Select again a deployed application and click the “Prepare” button to bring the JOnAS base and the database in the required state. Click the “Do start” button to deploy the application on JOnAS. The same SQLException as mentioned in Section 3.2 might be shown, but is not hampering the correct functioning of the deployed application. In order to retrieve the deploy base, one should click on the view instance button (see Figure 4) of the application instance and then on the link given in the “Deploy base” field. Typically this port will be 9200 (for deploy base 2) or 9300 (for deploy base 3). The application can now be reached via http://localhost:basePort/shortName in a browser.

Remark: it is advised to not run an application via the ApplicationDeployment menu item in the Software Constructs menu as here, less actions are available to manage running applications.

Stopping a deployed application

In order to stop a deployed and running application, select the ApplicationInstance menu item in the Software Constructs menu. Select the concerning application and go the ApplicationDeployment tab. After selecting the deployment, click the button “Do stop” and afterwards the button “Clean up”. The application will no longer be available via http://localhost:basePort/shortName.

Generating and running a new version of an entered application

In case a new version of an existing application is entered into the Prime Radiant, only a part of the activities described in Section 7 should be executed again.

Regarding Section 7.2, only the “Create default finders” button should be clicked when new data elements or waterfall screens are defined (in the standard case in which no new dependent components are added), or when a new status field was automatically created due to a new flow (see Section 5.2). Regarding Section 7.3, it should be mentioned that no new application instance should be created. Further, the button “Provision” should only be clicked when a new flow was added. In case of adding an additional data element to the application, the menu as mentioned in Section 4.11 should either be adapted as described in the concerning section or first be removed and then clicking the “Provision” button to generate a new and up-to-date menu. The buttons “Expand” and “Build” should always be clicked. The running and stopping of an application as described in Section 7.4 and 7.5, remain unchanged, except from the fact that the “Prepare” button should only be used in case an additional flow was added or one wants to start with an empty database.

Recovering the database after “Prepare” has been executed can be done by pushing the “Restore db” button, which will bring restore the old database. However, one should remark that this only holds for the data which was stored in the database before the last start of the application (due to specificities of the standard HSQL database). In order to be sure to restore all data (including all modifications performed in the between the last start–stop of the application) one should start and stop the application again without performing any actions within the application itself, before pressing the “Prepare” button. Afterwards, using the “Restore db” button will make sure that all data is indeed restored.

Run-time actions

Loading sample data into an application

When an application is generated from scratch or the “Prepare” button in the ApplicationDeployment tab was used (see Section 7.4), the application will not contain any data. These empty tables can easily be populated with sample data based on CSV (Comma Separated Value) files. In order to do so, place an ElementNames.csv file in the following folder: PR_ROOT\workspace
descriptors\components\[component]\data\csv. For instance, in case we want to populate the Person data element with sample data, we place a Persons.csv file in the directory as mentioned above. This CSV-file could look like this:

Elon;Musk;44;entrepreneur

Bill;Gates;60;philanthropist

Martin;Fowler:52;software engineer

Frederick;Brooks:84;computer scientist

The order of the fields separated by the commas should match the order of the fields as shown in the standard element screen in the deployed and running application (this might differ from the order as is shown in the Prime Radiant). Alternatively, the XML export file of the component or element (see Section 3.6), could be inspected for this purpose. More specifically, the order in which the fields of each element are listed in this file indicates the order in which the fields are read from the CSV file.

In the current version of the Prime Radiant, a value field (to make a link to another data element instance, see Section 4.3) should make use of the value of the name field of the data element instance to which the link is made. This means that in some cases, a new name field should be created for a particular data element if one’s goal is to populate other data elements which have value fields to this first data element. For instance, in case we want to import sample data for the Order data element (which makes a link to the Person data element), a new name field (which was otherwise not created) should be created, additionally to the already existing firstName and lastName fields.

It should further be noted that currently, a data element should have a name field, or have the data field option “nameNotWanted”. Otherwise the data instances will be reported in the console as being imported, but no data will be inserted in the tables. In case of our Person data element, this would therefore become:

Name Person:nameNotWanted

Value

Data element Person

Data option type nameNotWanted

After a CSV file is properly created and placed within the right location, one should select within the menu Utils, the menu item Execution. For each data element specified within the Prime Radiant, an Execution instance is automatically provided after expansion, building, and deployment (see Section 7.3) in order to allow its population with sample data via CSV files. These execution instances are specified as follows:

  • Name: “importCsv”;

  • Component: the component to which the element to be populated belongs;

  • Element: the element which is to be populated;

  • Package name: the package in which the data element is incorporated.

After selecting a particular execution instance and pressing the “Execute” button, the data from the ElementNames.csv file will be imported into the concerning data element. For instance, in case of the Person data element, one should look into the Execution menu for the instance with name “importCsv”, component “tutorialComp”, element “Person” and package name “be.uantwerpen.ee” to import the data from file Persons.csv located at PR_

ROOT\workspace\descriptors\components\tutorialComp\data\csv into the database for the Person data element. In case of importing data for multiple data elements which refer to one another, be sure to first import the data of data elements to which other data elements refer (importing data element instances referring to not yet existing data element instances will not be performed correctly).

A database populated with data can be emptied again by performing the “Provision” and “Prepare” actions in the Application instance actions and Application Deployment tabs in the Prime Radiant.

Defining possible values for a listed value field

In order to define the set of values, one should be logged in having administrator rights and go to the menu Utils, menu item TagValuePair. For each possible field value of a field, a “Tag” (typically structured as dataElement field; notice that the data element should start here exceptionally with a lowercase letter) and “Value” (the concerning possible value for the list field) have to be defined.

Suppose that we would change the option “Is list field” for the field “position” of the Person data element in the exemplary application we discussed and built so far. Suppose further that we would like to have three possible types of positions in our universe of discussion: clerk, manager and customer. The change of the “Is list field” option of the field should be changed at design time, i.e., while defining the application in the Prime Radiant:

Name position ——————- ————- Field type VALUE FIELD DescriptionIs info field x Is list field x Data Element Person

The set of possible field values should be defined once the application has been expanded, built and deployed via the TagValuePair menu item in the Utils menu as follows:

Tag person position person position person position

Value clerk manager customer

Managing flows

Provisioning and bootstrapping a flow

When the application is successfully deployed and a user with administration rights has logged in into the application, he should first select the Utils menu and the Execution menu item.

A provisionFlow and StartEngine entry for each defined flow is available within the table. Next, the flow should be provisioned by selecting the provisionFlow entry and clicking the “Execute” button. This provides an engine service and state task related to the flow (cf. infra). Finally, the flow should be bootstrapped by selecting the startEngine entry and again clicking the “Execute” button. This allows the flow to be started and stopped.

The engine service and state task of the flow can be seen when selecting the Workflow menu and the Workflow menu item. When the DataElementFlow instance in this screen is selected, a waterfall screen will appear in which the generated engine service (first tab) and state task (second tab) can be seen. The standard engine (DataElementService) has the characteristics that the flow is “up and running” (status: start), operating all day long and having a wait time of 30 (i.e., every 30 seconds it is checked whether any data element instances are in a state which requires them to have a state specified in the flow to be executed on them). Obviously, these standard options can be changed (e.g., increasing/decreasing the wait time or stopping the particular engine by changing the status to “stop”, or by clicking the button which appears when the DataElementService instance is selected).

Manually specifying and testing state transitions

When choosing the Workflow menu and the Workflow menu item, selecting the concerning DataElementFlow and then the State tasks tab, one can see that the standard test state task (DataElementTesterTask) is executed on all data element instances to which the flow is related having the state “TestStart”. Once this testerTask is executed (which in this case does not perform any functionality as it has no actual implementation), the status is set to “TestEnd”. In theory, the status of the concerning data element instance is set to “TestBusy” while the task is being executed and “TestFailed” in case it was not performed successfully, but this will typically not be visible for such test task as it is immediately completed and is always formed successfully.

To verify the fact that the test task will actually be executed (and therefore, the state will actually be changed), it suffices to change the value of the status field of one of the data element instances to “TestStart”. As long as the DataElementService is active (having a “start” status and being within the time window group), the system will automatically pick up this data element instance being in the TestStart status (after a maximum amount of time as specified in the flow’s wait time), execute the BookTesterTask, and set the status of that data element instance to TestEnd. An overview of the different states which have been taken by data elements on which flows were executed, can be obtained by going to the

.../shortName/Component/dataElementTaskStatus location via the browser. For instance, the different states taken by the Invoice data element due to our proposed InvoiceFlow, can be inspected by entering the .../tutorialApp/tutorialComp/invoiceTaskStatus link into the browser.

Via the workflow screen (selecting the Workflow menu item from the Workflow menu), more complex flows (such as the one we proposed in our universe of discussion and as represented in Figure 1) can be configured via the State tasks tab. For every state transition (state task), the following information should be provided:

  • Name of the state task (typically the name of the task to be executed);

  • Processor: generally structured as component:task;

  • Implementation: specifying the location of the implementation class, generally structured as [package name].[TaskImpl];

  • Params: generally put to “default”;

  • Begin state: value of the status field of the data element on which the flow is operating, at which the specified task should be executed;

  • Interim state: value of the status field of the data element on which the flow is operating, which is set while the specified task is being executed;

  • Failed state: value of the status field of the data element on which the flow is operating, which is set after the specified task has been executed non-successfully;

  • End state: value of the status field of the data element on which the flow is operating, which is set after the specified task has been executed successfully;

  • The workflow name of which the state transition is part, having a predefined value.

In case of our proposed universe of discussion, this would become for the InvoiceFlow operating on the Invoice data element:

Name InvoiceSender InvoicePaymentReceiver ——————– —————————————- —————————————- Processor tutorialComp:InvoiceTesterTask tutorialComp:InvoiceTesterTask Implementation be.uantwerpen.ee.InvoiceTesterTaskImpl be.uantwerpen.ee.InvoiceTesterTaskImpl Params Default Default Begin state Initiated Sent Interim state InvoiceSenderBusy InvoicePaymentReceiverBusy Failed state InvoiceSenderFailed InvoicePaymentReceiverFailed End state Sent Paid Workflow InvoiceFlow InvoiceFlow

and:

Name InvoiceBooker

Processor tutorialComp:InvoiceTesterTask

Implementation be.uantwerpen.ee.InvoiceTesterTaskImpl

Params Default

Begin state Paid

Interim state InvoiceBookerBusy

Failed state InvoiceBookerFailed

End state Booked

Workflow InvoiceFlow

Remark that states are preferably defined in one word (camel case is advised to combine different nouns). Further, one can notice that we referred to the same task for all specified state transitions. This is due to the fact that we do not explain task implementations in this starters manual and the main goal of analysts is to show to occurrence of flows, not their actual coded implementation. Clearly, different tasks can be used for each state transition for an application which is used in production. These tasks can be defined via the Prime Radiant (and later on implemented by developers) as discussed in Section 6.

Importing default state transitions

In case default state transition were defined during model specification (see Section 3.6), the procedure specified above can be shortened. First, copy the generated CSV file as obtained using the description in Section 3.6 to the following location: PR_ROOT\\workspace\

\descriptors\\components\\workflow\\data\\csv\\StateTasks.csv. Note that the directory ‘workflow’ (and its subfolders) might not yet exist and should be created in that case. Next, in the running application, select the Utils menu and Execution menu item. Add a new execution instance according to the following specifications:

  • Name: importCsv

  • Component: workflow

  • Element: StateTask

  • Package name: net.democritus.workflow

Finally, select the newly created execution instance and press the button “Execute”. The corresponding state tasks will now be added to the application. Note that executing the provisionFlow (cf. supra) functionality might override the (imported) state tasks.

User management

In case the standard technology stack was used while generating an application, some basic user right management is available by default and can be performed at run time (i.e., after the application has been expanded, built and deployed, see Section 7.3). More specifically, by using the base component “account”, a number of NS elements are provided which allow the management of access rights.

The structure of this default user management system is as follows. Every person who is able to log in into the application is considered as a User. Each User is linked to a certain Profile (such as “admin”, “master” or (regular) “user”). A User can belong to one or more user UserGroups, and also a UserGroup can be linked to a Profile. A Profile has a certain weight so that when a User logs on to the system, the Profile which the heighest weight is chosen (i.e., the Profile linked straight to the User or a Profile linked to one of the UserGroups).

Managing user accounts

A person who is considered to be the administrator of an application can create new user accounts in a running application by going to Account menu and selecting the User menu item. In this screen, the set of current users can be inspected (by default a user “admin”, “super” and “user1” with profiles “admin”, “master” and “user” respectively).

For every User, the following information should be provided:

  • Name: the name to be used by user to log in (avoid spaces);

  • Password: the password which allows the user to obtain access to the application (make sure that this is a sufficiently safe and non-trivial password);

  • Full name: a longer name in order to identify a user;

  • E-mail (optional);

  • Mobile (optional);

  • Language (optional): the chosen option might influence some menus and button for which translations in the chosen language are available;

  • First name (optional, but recommended);

  • Last name (optional, but recommended);

Personnel number;

  • Timeout: the time of inactivity (expressed in seconds) after which the user is automatically logged out of an application;

  • Account: the type of account (often related to an organization) the user is granted;

  • Profile: the profile which is granted to the user (standard options include “user”, “master” and “admin);

  • User groups: a set of groups to which this particular user belongs.

Defining access rights at runtime

A person who is considered to be the administrator of an application can define access rights in a running application by going to Account menu en selecting the DataAccess menu item. Here, the access rights of an operation on data element(s) (instances) for a certain Profile can be configured. The following types of operations are available:

  • status: the ability to show a screen with an overview list of the considered element and to show the detail screens of the considered element instances;

  • entry: the ability to create an element instance of the considered element and to modify instances of this considered element;

  • delete: the ability to delete or logically delete an instance of the considered element.

By default, all operations on all elements within an application are permitted for all users, regardless their profile. Consequently, if a User with a certain Profile is not allowed to perform an operation, an explicit DataAccess instance needs to be configured at run time.

For each DataAccess instance, the following information should be provided:

  • For profile: the profile to which the data access specification is related (only to be used when the fields “For user” and “User Groups” are left empty);

  • For user: the user to which the data access specification is related (only to be used when the fields “For profile” and “User Groups” are left empty);

  • User groups: the user groups to which the data access specification is related (only to be used when the fields “For profile” and “For user” are left empty).

  • Element: the element to which the data access specification is related;

Target: the element and operation configured by the data access specification, typically structures as DataElement operation;

  • Functionality: the operation configured by the data access specification;

  • Authorized: indicating whether or not the specified operation is allowed (default value: “no”).

For instance, suppose we want no regular users to delete invoices once they have been created, we define the following data access instance:

For profile user ——————- —————- For userUser groupsElement invoice Target invoice delete Functionality delete Authorized no

Important remark: at this point in time, the specification of data access rights at the level of users and user groups is currently not yet operational within the Prime Radiant. This functionality is soon to be added. However, the configuration of data access specifications at the level of profiles is currently working within the Prime Radiant.

Defining access rights at design time

Access rights can also be defined during the definition of the model of the application and its components. First, the access rights should be specified in the Prime Radiant. In order to do so, select Functional elements menu and the Application menu item. Select the concerning application and choose the Access Right tab in the waterfall screen below. Here, new access rights can be defined. For each AccessRight instance, the following information should be provided:

  • Profile: the profile to which the access right specification is related (only to be used when the fields “User” and “User Group” are left empty);

  • For user: the user to which the access right specification is related (only to be used when the fields “Profile” and “User Group” are left empty);

  • User group: the user group to which the access right specification is related (only to be used when the fields “Profile” and “User” are left empty).

May read: indicating whether read actions are allow (check if yes);

  • May edit: indicating whether edit actions are allow (check if yes);

  • May create: indicating whether create actions are allow (check if yes);

  • May delete: indicating whether delete actions are allow (check if yes);

  • Application: the application to which the access right relates, having a predefined value; • Scope: the data element to which the access right applies;

Important remark: at this point in time, the specification of data access rights at the level of users and user groups is currently not yet operational within the Prime Radiant. This functionality is soon to be added. However, the configuration of data access specifications at the level of profiles is currently working within the Prime Radiant.

Further, it has to be noted that —when using access rights— all access to all data elements of an application is denied by default (i.e., for data elements for which no specific access right instances have been specified within the Prime Radiant). This implies that access rights have to be specified for all data elements (including those within the base components, see Section 3.5) to which users should be able to have access in the running application. Additionally, it is important to know that in order to be able visit pages including waterfall screens, access should be granted to all elements in this screen.

Next, the specified access rights should be exported into a CSV file by going to the Application actions tab of the application and clicking on the button “Export accessRights to file”. The generated CSV file can now be found at the following location: PR_ROOT\\workspace
\descriptors\\applications\\[application]\\data\\csv\\DataAccess.csv.

Finally, in order to import the access rights in a running application, the above generated CSV file should be copied to the following location: PR_ROOT\\workspace\\descriptors
\components\\account\\data\\csv\\DataAccess.csv. Note that the directory ‘account’ (and its subfolders) might not yet exist and should be created in that case. Next, in the running application, select the Utils menu and Execution menu item. Add a new execution instance according to the following specifications:

  • Name: importCsv

  • Component: account

  • Element: DataAccess

  • Package name: net.democritus.acl

Finally, select the newly created execution instance and press the button “Execute”. The corresponding data access instances will now be added to the application. Note that, in order to apply the newly imported data access instances, the user should log out and log in again.

Inspecting source code

The source code of a prototype can be inspected at PR_ROOT\\[modelrepository]\\[expandbase] \\[applicationname-id]. However, the Prime Radiant also provides the functionality to inspect several aspects and dimensions of any prototype and its source in a highly structured approach.

Dimensions of variability

The Prime Radiant allows analysts and developers to inspect the resulting applications in terms of the following dimensions of variability throughout time:

  1. The model of the components (data entities and their relationships, tasks and flows) via the Component screen selected within the Functional elements menu. This also results in the standard generated code, see Section 10.2;

  2. Custom code (insertions and extensions, see Section 10.3);

  3. Expander version via the ApplicationInstance screen selected within the Software constructs menu;

  4. Platform technologies used via the ApplicationInstance screen selected within the Software constructs menu.

Standard generated code

The standard generated code by the Prime Radiant based on the specified model of the analyst can be “imported” into the Prime Radiant to inspect it in a highly structured way. In order to do so, an application instance should first be created (see Section 7.3). After the model has been expanded and build (also see Section 7.3), one should remain in the ApplicationInstance screen and the buttons “Instantiate” and “Import code” should be clicked. It is important to note that in the current version of the Prime Radiant, the “import code” button should only be clicked once for each new version (e.g., after the creation of a new data element) of the model (as otherwise, duplicate entries might be imported into the overview of the Prime Radiant). Now, the generated source code can be inspected by the selecting the tab Component Instances in the same ApplicationInstance screen.

Insertions and extensions

In order to inspect insertions and extensions, one should first select the Functional Elements menu and then the Application menu item. Select the concerning application, and press the buttons “Import extensions” and “Import insertions” to import, respectively, the extensions and insertions into the Prime Radiant. Then, one should selected the considered component after choosing the menu item Component in the Functional Elements menu. Next, the layers containing any insertions or extensions are listed in the tab Custom Layers. Once a layer is selected, the accompanying waterfall screen lists all extensions (additional classes) and insertions (customizations between anchor points) and properties such as their size, source type and technology. The listed insertions and extensions can be downloaded by selecting the considering insertion/extension, clicking on the view instance button (see Figure 4) and the provided link in the “code link” field within the resulting screen.

Some basic customizations

Adapting the top navigation bar and its menus

As stated in Section 3.4, a standard generated NS application has always the same graphical user interface. This implies among other things a top navigation bar, which allows to access standard screens in order to view-create-update-delete instances of the specified data elements of the included elements in the application. By default, for each component a tab is created in the top navigation bar, with its different embedded data elements as its menu items. Additionally, some standard configuration options are provided via some additional tabs. In certain situations, it might be preferable to adapt this menu. For instance, waterfall screens or customized screens might have been developed allowing to view and modify instances of multiple different data elements in one combined screen in a more user-friendly and ergonomic way, making some of the standard generated menu items (which might for instance only allow the modification of one of the data elements) unnecessary. As some applications might contain a very large set of data elements, the reduction of the number of available menu items might reduce the complexity to be managed by the user as well. In other situations, the analyst might want to reshuffle the “groupings” of menu items in the top navigation bar for usability purposes. Finally, people having different roles (see Section 9) might prefer or need different menus. For instance, someone with the role of administrator might want to have a different menu (i.e., being able to view and access about everything in the application) than someone being a “normal” user (e.g., only having to manipulate and a subset of elements and configuration options available in the application). Therefore, there are several occasions in which it might be convenient to adapt the standard generated top navigation bar and its menu items.

The specification of the standard generated menu can be modified by going to the file located at PR_ROOT\\workspace\\descriptors\\applications\\(applicationName)\\harvest\\control
\struts2\\resources\\menu, which can be opened with a standard text editor. The file is structured in an XML-fashion, having start-tags, end-tags and empty-element tags. When inspecting this file, it can be noticed that it is structured in a hierarchical way, having three major levels:

  • menu: defining the menu for a particular profile, such as admin (with start-tag <menu profile = ‘[profiletype]’> and end-tag </menu>;

  • submenu: defining a tab in the menu for the profile it is embedded in a particular profile (with start-tag <submenu name=’[tablabel]’> and end-tag </submenu>;

  • menu item: defining a menu item for the tab (submenu) it is embedded in (by means of an empty-element tag <menuitem ref=’[component]-[DataElement]-ko-page’/>.

Suppose for instance that we want to create a menu within our exemplary application for Users with the profile “user” for which we do not want that menus to access the elements from the base components menus (Utils, Validation, Account and Workflow) are visible. In that case, we can extend the tutorialApp.menu.harvest file by the following lines (but before the -- anchor:custom-menus:end anchor):

<menu profile=’user’>

<submenu name=’TutorialComp’>

<menuitem ref=’tutorialComp-person-ko-page’/>

<menuitem ref=’tutorialComp-order-ko-page’/>

<menuitem ref=’tutorialComp-invoice-ko-page’/> </submenu>

</menu>

Now, after re-expansion and building of the application, users with the profile “user” will see a top navigation bar only having one tab (i.e., “TutorialComp”) with the three data elements within the application (i.e., Person, Order and Invoice).

Important remark: the harvest file which is modified by this way of working is initially generated by the Prime Radiant. As we mentioned in Section 4.11, when adding new data elements in subsequent versions of models of an application, one could opt for deleting this file in order to let the Prime Radiant automatically generated a new menu which incorporates these new data elements. The generation of this menu file happens during the provision. Such regeneration means that all previous manually performed modifications to this file (i.e., adaptations regarding the top navigation bar and its menu items) are lost and have to be performed again. In case one manually adds the new elements within the menu file (i.e., without deleting it), this issue obviously does not occur.

Next, rebuild and start the application.

Labels and order of waterfall tabs

In Section 4.8, we discussed how waterfall screens can be created between elements having a one-to-many relation. For instance, we illustrated how a waterfall screen could be created for the Person data element showing each Order which was related to the selected Person. Further, for a data element having multiple one-to-many relations, multiple data children can be defined resulting in a waterfall screen having multiple “tabs” (e.g., a tab for showing all Orders and a tab for showing all Locations related to one Person). By default, all tabs in a waterfall screen are named as DataElements (i.e., an “s” is added to the name of the data child). While this is often an appropriate tab name, some situations might arise in which another tab name is preferable (e.g., when developing an application in another language). In such cases, it suffices to perform a small customization.

First, after the application has been expanded and built for at least one time, one should go to the following directory: PR_ROOT\\workspace\\descriptors\\components\\[ComponentName] \\harvest\\view\\knockout\\jsp\\[ComponentName]. Here, the file related to the “parent” data element for which the concerning waterfall screen is defined, should be selected. For instance, for the waterfall screen of the Person data element, the file Person-ko-page.jsp. harvest should be opened (e.g., by means of a standard text editor). Look for the HTML unordered list element (between the <ul> and </ul> tags): the different list item elements within the list element represent the different tabs in the waterfall screen. The order of items within this list element (from top to bottom) determines the order in which the tabs (from left to right) appear in the eventual waterfall screen. Therefore, in order to change the order of the tabs in the waterfall screen, one should simply switch different list items in the order as wanted. In order to change the name of a tab, one should change the value between of the anchor element (between the <a> and </a> tags) into a different value than the standard DataElements, for instance changing:

Dead Link

Important remark: as we mentioned in Section 4.8, the creation of an additional waterfall screen requires the re-expansion (and rebuilding) of the application and therefore this harvest file as well. This also means that all previous manually performed modifications to this file (modified labels and order of tabs) are lost and have to be performed again.

Next, rebuild and start the application.

Updating the Prime Radiant

Preparing the update

Updates of the Prime Radiant can be obtained by downloads from the Trantor server. First, close all deployed applications (see Section 7.5) and the Prime Radiant (see Section 3.3). Check whether you have PSCP available on your desktop. If not, download it (e.g., from the PuTTY download page at http://www.chiark.greenend.org.uk/~sgtatham/putty/ download.html) and put it into your PR ROOT folder.

Performing the update

Open the command prompt and go to the PR ROOT location. Be sure that all environment variables are set by executing the script set all env vars.bat. Download the Prime Radiant update by entering the following command:

pscp -r [username]\@trantor.normalizedsystems.org:/home/primeradiant/[updatefolder] . (space and point included) after filling in the provided username and update folder. When prompted for storing the key in cache, type “y” and enter the accompanying password. Go to the directory of the update folder (typically PR\_ROOT\PR-[timestamp]) and execute the update script: upgrade prime radiant [timestamp].bat. After the script has been executed, the new version of the Prime Radiant has been installed.

Appendix A Frequently Asked Questions {#appendix-a-frequently-asked-questions .ListParagraph}

A.1 Using NS applications (and the Prime Radiant) {#a.1-using-ns-applications-and-the-prime-radiant .ListParagraph}

Q 1: When I press a button in the Prime Radiant or my deployed prototype, nothing happens.

A: You might be logged out due to a time out. Refresh your web page (e.g., pressing F5), log in and try your action again. It might also be the case that to many command prompts are opened on your system. As an operating system has only a limited number of sockets, some of the command prompts need to be closed. Make sure to only close command prompts of ended scripts, not that of the Prime Radiant itself or any deployed application.

Q 2: My search operation does not provide any result although I know it should. A: Check whether you are not logged out due to a time out (see Question 1). Be aware that search operations in NS software are case sensitive (check for instance whether the first letter of your argument should be a capital or lower case letter). Remind that you can use the % character as a wildcard.

Q 3: Not all possible values for a particular field are shown when I press the dropdown arrow.

A: A dropdown box can only show a limited amount of possible values. Values which do not show up immediately after opening a dropdown box can be selected by starting to type the first letters of the value or by searching for it by using the “search instances” button next to the field.

Q 4: When I want to edit a listed field value of an already existing instance of a data element, I only get to see my original value but no other options.

A: When opening a dropdown box of an already filled in field, there is indeed a high chance that only the currently chosen value will be shown. This is due to the fact that only values consistent with the letters entered in the field will be shown (in fact, a search operation based on these letters will be performed of which the results are shown in the dropdown box). This can be solved by deleting some letters entered in that field or using the “search instances” button next to the field. See also Question 3.

Q 5: The menu bar at the top of the page is split over two lines.

A: This can be solved by zooming out (e.g., by using the key combination Ctrl + - one or multiple times).

Q 6: I cannot see all menu items (elements) when clicking a particular menu in the menu bar, because the list is too long.

A: See Question 5.

A.2 Running the Prime or a generated application {#a.2-running-the-prime-or-a-generated-application .ListParagraph}

Q 7: While starting the Prime Radiant or a generated application, I get some error messages.

A: It is possible that during start up, one SQLException is shown in the log, which is no problem for the further execution of the Prime Radiant (see Section 3.2 on page 6) or any other generated application. In case of other errors, make sure that the Prime Radiant or the generated application was appropriately closed and cleaned during its last usage. If not, perform the “jonasCleanup.bat” script or press the “Clean up” button (see Section 7.5 on page 37) and try restarting the Prime Radiant or generated application again.

Q 8: While starting the Prime Radiant or a generated application, the command prompt seems to freeze.

A: Be aware that, depending on the specs of your computer, starting the Prime Radiant or any generated application may take some time. It may even occur that the command prompt shows the C:\PR ROOT> prefix, which does not require you to do anything but waiting for the application to continue its starting up process. In exceptional cases, the command prompt may hang for several minutes after the “Starting JOnAS” message, in which pressing the Enter key might trigger the command to continue.

Q 9: I erroneously closed the command prompt window of the Prime Radiant or an application which I deployed myself.

A: In case of the Prime Radiant, open a new command prompt, set all environment variables (see Section 3.2 on page 3.2) and clean up the JOnAS application server by executing the “jonasCleanup.bat” script. Try now to restart the Prime Radiant. In case of a self-deployed application, select the Software Constructs menu and ApplicationInstance menu item. Select the concerning application and go the ApplicationDeployment tab. After selecting the deployment, click the button “Clean up”. Try now to restart the application (see Section 7.4 on page 37).

A.3 (Re-)expanding and building applications {#a.3-re-expanding-and-building-applications .ListParagraph}

Q 10: While the log of the build command displays “BUILD SUCCESSFUL”, I suspect that something has gone wrong anyway.

A: Building an NS application via the Prime Radiant is done by compiling each component of that application separately. This means that after the compilation of each component, a message “BUILD SUCCESSFUL” or “BUILD FAILED” is shown in the command prompt. This message is then expressing the (un)successful completion of the compilation of that individual component. Therefore, although the last message in the command prompt might suggest that the compilation process was successful, this message actually only relates to the last component which was compiled. Therefore, some things might still have gone wrong in this process despite the last shown message. In order to cope with this, the messages printed in the command prompt for every individual component should be inspected (i.e., multiple “successful” or “failed” notifications).

Q 11: In a new version of an application (after an update), the changes are not visible.

A: Check whether the application was restarted and redeployed after the modifications took place. It also possible that this is due to a caching issue of your browser. In Chrome, press F12, right-click on the refresh button and select “Empty Cache and Hard Reload”. In case of using another web browser, consult help or documentation pages on how to clear cache memory. Further, it could be the case that the application has been expanded and built, but that intermediate errors have occurred (see e.g., Question 10). Therefore, it is advised to check the remedies as mentioned in Question 19.

Q 12: When I run (a new version of) my application, the menu is not updated or the menu bar states “No Menu Found”.

A: Check all remedies as mentioned in Questions 10 and 11. Check whether you have adapted the menu file as described in Section 4.11 on page 27. Be aware that it might be the case that the menu has not been properly generated or a new version of the menu might not have been taken as an input during the compilation process due to some errors in the data model (and as a consequence, during expansion and building). Therefore, it is advised to check the remedies as mentioned in Question 19.

Q 13: While I pressed the “Prepare” button, the database of my application was not empty after restarting it.

A: In case the application/prototype was build using HSQL, all database entry modifications performed during the last deployment are only incorporated into the database when the application is restarted again. Check Section 7.6 on page 37 for more information.

Q 14: While I pressed the “Restore db” button, the database of my application was not completely backed up and recovered in the new version of the application. A: See Question 13.

Q 15: While I deleted a data element, finder, ... from my component model, errors regarding this data element, finder, ... keep appearing.

A: In case of a data element, check whether no other data elements have link fields referring to this data element. In all cases, check whether all child items (fields for data elements, field-operator pairs for finders, etcetera) related to that data element, finder, ... have been removed as well. This can be done by opening the Functional Elements menu, opening the Field and FieldOperatorPair menu items and inspecting the relevant instances listed here. Finally, try out deleting all generated code regarding the application and let the Prime Radiant generate the code again. This can be done by deleting (or renaming) the directory PR_ROOT\[modelrepository]\[expandbase]\[applicationname-id].

Q 16: After changing the names of some data elements, fields or components, some errors occur during expansion or building, or the generated application does seem to not correctly incorporate all specified changes.

A: Generally, it is advised to only carry out these kind of changes when really necessary. If you do so, make sure that all naming conventions regarding data elements regarding the data elements and finders were still respected (see Section 4 and page 15). Make sure that all references to data elements, fields or components with the old names are removed or adapted (his may also impact other data elements and components). Finally, try out deleting all generated code regarding the application and let the Prime Radiant generate the code again. This can be done by deleting (or renaming) the directory PR_ROOT\[modelrepository]\[expandbase] \[applicationname-id].

Q 17: After changing a VALUE FIELD to a LINK FIELD, the “type column” in the Fields table is not adapted accordingly or some errors occur during expansion or building, or the generated application does seem to not correctly incorporate all specified changes.

A: It is advised to first delete the Field type details instance, then remove the old field (with field type VALUE FIELD). Next, create a new field with the same name (but with field type LINK FIELD) and specify the appropriate Field type details (see Section 4.4 on page 17). Finally, make sure to execute the “Create default finders” button in the Perform tasks tab at the level of the component.

Q 18: I have two or more entries in the ApplicationDeployment tab of the Software Constructs screen.

A: You have clicked the button “Request deploy” button twice or more, while this is only required to be done once (during the first deployment of the application). This can be solved by deleting all ApplicationDeployment entries but one and use that last entry to start and stop your application.

Q 19: Something goes wrong during the expansion or build process, but I don’t know what or cannot derive it from the error message.

A: Check the following items which are frequently made mistakes while specifying the model of a prototype in the Prime Radiant:

  • Was the application properly stopped and cleaned up last time it was used or deployed (see Question 9)? Was the jonasCleanup.bat script properly performed the last time the Prime Radiant was used (see Section 3.3 on page 7)?

  • Are all necessary components (including base components) included as components in the application? (see Section 3.5 on page 9)?

  • Have the component dependencies of the application been specified (see Section 7.2 on page 34)?

  • Is the name of all data-elements starting with a capital and all fields with a lower case letter (see Sections 4.1 on page 15 and 4.2 on page 15)?

  • Has a tested value type been specified for every field of every data element (see Section B.1 on page 58)?

  • Have the default finders been created (see Section 7 on page 34)?

  • Are the finders defined by the analyst “completed” for each data element (see Section 4.7 on page 21)?

  • Are there no typo’s in the package names of the data elements?

  • Have you tried to delete the previously generated source code? This can be done by deleting (or renaming) the directory PR_ROOT\[modelrepository]\[expandbase] \[applicationname-id].

A.4 General configuration {#a.4-general-configuration .ListParagraph}

Q 20: How can I edit the standard administration password for generated prototypes?

A: Go to the following directory PR_ROOT\repositories\primeRadiant\conf\hsql. Open the file “db jonas.script”. Look for the entry starting with

“INSERT INTO USER VALUES(2,1,’no’,’beheerder\@nsx.normalizedsystems.org’ “. Change the sequence “ ‘admin’, ‘XXX’ “ in such way that XXX represents the password which should be attributed to the admin user account for generated applications by the Prime Radiant.

Appendix B Useful tables {#appendix-b-useful-tables .ListParagraph}

B.1 Tested value types {#b.1-tested-value-types .ListParagraph}

Value Type Description ——————- —————————————————————————————————————————————- Boolean has two possible values (true or false), typically visualized by means of a tick box String a short text (maximum 255 characters) in non-edited form StringMultiline same as the String value type, but allowing up to 16384 characters to be entered Integer a constant holding a value between −2^31^ and 2^31^− 1 Date represents a date expressed in day, month and year StringFile a String representing a file uploaded to the server, only to be used in combination with a field named “uploadUri” (see Section 4.9)

B.2 Non-functioning value types {#b.2-non-functioning-value-types .ListParagraph}

Value Type Description —————- ———————— FloatTime “object-object” in GUI DateTime

Link Field Type Description ——————— ———————————————————————————————————————————————————– Ln01 preferred many-to-one, NS element software manages the relationship Ln02 many-to-one, JEE container manages the relationship Ln03 many-to-many, JEE container manages the relationship Ln04 one-to-many (requires its reverse, Ln02, to be specified at the other side of the relationship), JEE container manages the relationship Ln05 preferred one-to-many (requires its reverse, Ln01, to be specified at the other side of the relationship), NS element software manages the relationship Ln06 many-to-many (requires its reverse, Ln03, to be specified at the other side of the relationship), JEE container manages the relationship

B.4 Data element options {#b.4-data-element-options .ListParagraph}

Field name Comments —————— ——————————————————————————————————————————————————————————– hasDisplayName can be used to change the way instances of data elements are displayed in an application by using the value of one or more other fields of that instance (see Section 4.6) nameNotWanted will prevent the expanders from making a name field for that data element (and therefore, in the database), may be needed to use in case of importing data (see Section 8.1)

B.5 Field options {#b.5-field-options .ListParagraph}

Field name Comments —————— ———————————————————————————————————————————– isExposedField generates getters and setters for a field, required when defining a status field on which a flow should operate (see Section 5.2) isStatusField indicates the field is a status field (see Section 5.2)

B.6 Special fields {#b.6-special-fields .ListParagraph}

Field name Comments —————- —————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————————- name Field which is by default used to uniquely identify instances of a data element and display them in a working application. Will be automatically generated in the background when not specified by user. Specification is required for each element to which is referred when importing data via CSV files (see Section 8.1). Some options may change the standard behavior of the field (e.g., see Sections 4.6 and 8.1). uploadUri Field in which a file can be uploaded and downloaded (see Section 4.9). enteredAt Field which will automatically store the date at which its parent data element is created.

B.7 Protected words {#b.7-protected-words .ListParagraph}

account long ——— ———— agent package boolean parameters case proxy date string export var

function import

integer interface

Appendix C Cheat sheet {#appendix-c-cheat-sheet .ListParagraph}

C.1 Starting the Prime Radiant {#c.1-starting-the-prime-radiant .ListParagraph}

  • Go to PR_ROOT in the command prompt

  • Execute “startup prime radiant.bat”

  • Do not close the command prompt as long as the Prime Radiant is running

C.2 Stopping the Prime Radiant {#c.2-stopping-the-prime-radiant .ListParagraph}

  • Close all running NS applications (see Section C.4)

  • Execute “jonas stop” within Prime Radiant command prompt

  • Execute “jonasCleanup.bat”

C.3 Starting a generated application {#c.3-starting-a-generated-application .ListParagraph}

  • Make sure the application has been properly expanded, built and deployed (see Section C.4)

  • Software constructs−→ApplicationInstance−→ select application −→ tab application deployment−→ select ApplicationInstanceDeployRequester instance

  • (if first time or empty database required or additional flow added) “Prepare”

  • (if after “Prepare” the previous version of database content should be restored) “Restore db”

  • “Do start”

C.4 Stopping a generated application {#c.4-stopping-a-generated-application .ListParagraph}

  • Software constructs−→ApplicationInstance−→ select application −→ tab application deployment−→ select ApplicationInstanceDeployRequester instance

  • “Do stop”

  • “Clean up”

C.5 Setting up a new application {#c.5-setting-up-a-new-application .ListParagraph}

  • Functional Elements−→Application Track−→ create new instance (see Section 3.5)

  • Functional Elements−→Application−→ create new instance (see Section 3.5)

  • Functional Elements−→Component−→ create new instance (see Section 3.5)

  • Define the model by adding data elements (see Section C.10), fields (see Section C.11), finders (see Section C.12), flows (see Section C.17), tasks (see Section C.20), etcetera

  • Expand, build and deploy the application (see Section C.6)

  • Start the application (see Section C.3)

C.6 Expanding, building and deploying an application for the first time {#c.6-expanding-building-and-deploying-an-application-for-the-first-time .ListParagraph}

  • Functional Elements −→ Component −→ select concerning application specific component

  • for all application specific components: tab Perform tasks −→ “Create base dependencies” and “Create default finders”

  • Functional Elements−→Application−→ tab Application instances

  • create instance (see Section 7.3)

  • Software Constructs−→ApplicationInstance

  • select concerning application instance −→ tab Application instance actions −→ “Provision”, “Expand”, “Build”, “Request deploy” (check for potential errors)

C.7 Regenerating an existing application {#c.7-regenerating-an-existing-application .ListParagraph}

  • for newly added components: Functional Elements −→ Component −→ select concerning component −→ tab Perform tasks−→ “Create base dependencies” and “Create default finders”

  • for components used before (when new data elements or waterfall screens are defined or when a new status field was automatically created due to a new flow): Functional Elements−→Component−→ select concerning component −→ “Create default finders”

  • Functional Elements −→ ApplicationInstance −→ select concerning application instance −→ tab Application instance actions

  • if new data element has been added: adapt file at PR_ROOT\workspace\descriptors
    applications\(applicationName)\harvest\control\struts2\resources\menu or delete the file and click “Provision”

  • “Expand” and “Build” (check for potential errors)

C.8 Importing a model {#c.8-importing-a-model .ListParagraph}

  • Place the xml file containing the model at PR_ROOT\workspace\descriptors\components\

[componentname]\models named as [ComponentName]-[ComponentVersion].xml

  • Functional Elements −→ Component −→ select component to be imported−→ tab

Perform tasks

  • “Import model from file”

C.9 Exporting a model {#c.9-exporting-a-model .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Perform tasks

  • “Export model to file” or “Export model to dir”

  • the model (hierarchy) can be found at PR_ROOT\workspace\descriptors\components\

[componentname]\models\[timestampeddatamodel]

C.10 Add a data element {#c.10-add-a-data-element .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Data

Elements

  • add new instance (see Section 4.1)

  • if the application has already been generated before: adapt file at PR_ROOT\workspace
    descriptors\applications\(applicationName)\harvest\control\struts2\resources
    menu or delete the file and provision during regeneration (see Section C.7)

C.11 Add a data field {#c.11-add-a-data-field .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Data Elements−→ select concerning Data Element −→ tab Fields

  • add new instance (see Section 4.2)

  • specify the Field type details: in case of a VALUE FIELD involving a data type (see Section 4.3 and Table B.1), in case of a LINK FIELD involving a link field type, target class and package (see Section 4.4)

  • in case of a LINK FIELD: tab Data Elements at component level −→ “Create default finders”

C.12 Add a finder {#c.12-add-a-finder .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Data Elements−→ select concerning Data Element −→ tab Finders

  • add new instance (see Section 4.7)

  • tab Perform tasks at data element level −→ “Complete data finders”

C.13 Add a waterfall screen {#c.13-add-a-waterfall-screen .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Data Elements−→ select parent Data Element −→ tab Data children

  • add new instance (see Section 4.8)

  • tab Perform tasks at data element level −→ “Extend user interface”

  • tab Perform tasks at component level −→ “Create default finders”

C.14 Change the displayed name of a data element {#c.14-change-the-displayed-name-of-a-data-element .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Data Elements−→ select concerning Data Element −→ tab Data options

  • add new instance with value “hasDisplayName” for the field Data option type (see

Section 4.6)

C.15 Provide document upload/download {#c.15-provide-document-uploaddownload .ListParagraph}

• add new field (see Section C.11) of field type VALUE FIELD with name “uploadUri” and with value type StringFile (see Section 4.9)

C.16 Provide a report {#c.16-provide-a-report .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Data Elements −→ select concerning Data Element −→ tab Perform tasks −→ “Create data reporting”

  • tab Perform tasks at data element level −→ “Extend user interface”

C.17 Add a flow {#c.17-add-a-flow .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Flow

Elements

  • add new instance (see Section 5.2)

C.18 Start/stop a flow {#c.18-startstop-a-flow .ListParagraph}

  • Run the concerning application

  • Utils−→Execution

  • Select concerning provisionFlow entry (with name “provisionFlow” and the element on which the flow operates as its element value) −→ “Execute”

  • Select concerning StartEngine entry (with name “startEngine” and the element on which the flow operates as its element value) −→ “Execute”

  • In top navigation bar: Workflow−→Workflow

  • Select concerning flow instance (with name “[DataElement]Flow” and the element on which the flow operates as its class name value) −→ tab Engine Services −→ select

[DataElement]Service instance −→ “Stop” or “Start”

C.19 Specify state transitions {#c.19-specify-state-transitions .ListParagraph}

  • Run the concerning application

  • Workflow−→Workflow

  • Select concerning flow instance (with name “[DataElement]Flow” and the element on which the flow operates as its class name value) −→ tab State tasks

  • Add or change instances (see Section 8.3)

C.20 Add a task {#c.20-add-a-task .ListParagraph}

  • Functional Elements−→Component−→ select concerning component −→ tab Task

Elements

  • add new instance (see Section 6.1)

  • tab Perform tasks at component level −→ “Create flow environment” and “Create default finders”

C.21 Import sample data {#c.21-import-sample-data .ListParagraph}

  • Each data element for which data is to be imported should have a name field or the data field option “nameNotWanted” (see Section 8.1). Each data element to which is being referred in imported data, should have a name field (as referrals are done based on the value of this field).

  • Create .csv file for each data element for which data has to be imported (the order of the fields can be retrieved based on the XML export file (see Section C.9)

  • Place the CSV files in the PR_ROOT\workspace\descriptors\components\[component] \data\csv directory

  • Utils−→Execution

  • For each data element for which data is to be imported, select the instance with name “importCsv” and the concerning element as its element value, and click “Execute”. Be sure to first import the data of data elements to which other data elements refer.

C.22 Specify list values {#c.22-specify-list-values .ListParagraph}

  • Run the concerning application

  • Utils−→TagValuePair

  • Add tag-value instances (see Section 8.2)

C.23 Adapt navigation menu {#c.23-adapt-navigation-menu .ListParagraph}

  • Go to directory PR_ROOT\workspace\descriptors\applications\(applicationName)

\harvest\control\struts2\resources\menu

  • Open the menu.harvest file

  • Adapt the file in an analogous way

  • Rebuild and start the application

C.24 Adapts labels and order of waterfall screens {#c.24-adapts-labels-and-order-of-waterfall-screens .ListParagraph}

  • Go to directory PR_ROOT\workspace\descriptors\components\[ComponentName]\harvest
    view\knockout\jsp\[ComponentName]

  • Open file [ParentDataElement]-ko-page.jsp.harvest

  • Adapt the order and labels within the HTML unordered list (see Section 11.2)

  • Rebuild and start the application

C.25 Specify user accounts {#c.25-specify-user-accounts .ListParagraph}

  • Run the concerning application

  • Account−→User

  • Add new instance (see Section 9.1)

C.26 Specify access rights {#c.26-specify-access-rights .ListParagraph}

  • Run the concerning application

  • Account−→DataAccess

  • Add new instance (see Section 9.2)

C.27 Update the Prime Radiant {#c.27-update-the-prime-radiant .ListParagraph}

  • Stop all deployed applications (see Section C.4)

  • If PSCP is not present in PR ROOT folder, download it (see Section 12.1)

  • Go to PR_ROOT in the command prompt

  • Execute “set all env vars.bat”

  • Execute “pscp -r

[username]\@trantor.normalizedsystems.org:/home/primeradiant/[updatefolder] .”

  • type “y”, then password

  • change directory in command prompt to update folder (typically PR\_ROOT\PR-[timestamp])

  • Execute “upgrade prime radiant [timestamp].bat”

  1. When using the multiplicities Ln01 and Ln05, the NS elements handle the concerning relationship. A similar link between elements (in which the container manages the relationship) can be made by using the links Ln02 and Ln04, respectively (for which the same naming and finder restrictions hold as with the Ln01 – Ln05 links). Many-to-many links can directly be defined by specifying Ln03 and Ln06 links (and in case the latter one is specified, the name of the corresponding Ln03 field needs to be identical to the name of the element where the Ln06 link is specified followed by the character “s”). In the generated application, this results in a “picking list” in which the user can select multiple items to be related to other items. However, from an analysis point of view, it needs to be mentioned that such many-to-many relationships are preferably implemented by splitting up the relationship in two many-to-one relationships (and therefore, via the creation of an additional intermediary element). 

  2. The possibility to include other types of fields in these reports will soon be added.