Reference architecture guidelines and how to create a change request

[Kenny]

Reference architecture guidelines and how to create a change request

Introduction

Novulo’s Reference Architecture consisting of concepts, features, enumerations and processes. In today’s fast moving development cycles, the dependency on Novulo developers for addition is unwanted, therefore the Reference Architecture can be expanded by anyone who has rights to produce new elements. In order to prevent wildgrowth and ensure quality, processes and work agreements are in place as well as a review structure. In the rest of this post you can read about the guidelines, work agreements and how to create a change request. This post will not adress how to produce.

Guidelines

The following guidelines apply to all elements.

1. Only produce if needed, don’t produce everything!
2. The element should not exist already. If you are unsure search and check in the appserver, search in the architect concept manager or ask a novulo developer.
3. Fine-grained
4. Unambiguous
5. Not limited to a single country, region or industry
6. Language: English

For concepts, features, attributes, enumerations and processes specific guidelines exist, these can be found below

Concepts

1. Name starts with N_, followed by NameInPascalCase. The name is singular and in English and may only contain A-Z, a-z characters.
2. Only introduce a new concept when your type cannot be mapped to an existing concept. Some concepts are generic enough to be used in multiple ways, so compare not only the name, but also features and related processes​. Don’t overdo this principle and discuss when in doubt.

Features

1. Name starts with N_, followed by the name, starting with a capital letter. The name is in English and may only contain A-Z, a-z characters and spaces.
2. A feature describes an indivisible property of an instance of a concept.
3. Only introduce a new feature when your type cannot be mapped to an existing feature of the concept
4. If a concept has multiple links to the same other concept, make sure that the name of the feature describes what it means. For example, an N_Delivery could have an “N_Delivery to address” and an “N_Delivery from address”.
5. The concept name must clearly describe what it means. For example,N_Delivery date should be either N_Receiving date or N_Sending date.
6. Until the App Server and Architect support read-only attributes: If the feature is a function, always add “ (fx)” at the end of the feature​

Attributes

1. Name is in snake_case. The name is in English and may only contain a-z characters and underscores.
2. If the attribute can be implemented by a function (i.e. it is read-only), suffix it with ‘_fx’.
3. Multiple attributes can be grouped into a single feature. Only do this when all these attributes are always required to describe that feature.
   1. Good example, the N_Coordinate feature of an N_AddressLocation requires two numeric attributes: ‘longitude’ and ‘latitude’. The one attribute is meaningless without the other.
   2. Bad example: For a Product, the code and name are put together in 1 feature. This should not have happened.

Enumerations

1. Name starts with N_, followed by NameInPascalCase. The name is in English and may contain A-Z and a-z characters, and if necessary spaces and (braces).
2. A logical name that describes the values of the enumeration as a group is preferred. If that is not possible, and the number of values is limited (max. 3),the values may be concatenated to form the name of the enumeration (e.g.N_DebtorCreditor).
3. Only use enumerations for sets of values that are immutable. Once a reference architecture enumeration is used, it cannot be expanded.​
   1. If the list might change in the future, consider creating a feature with a couple ofYesNo attributes describing its interpretation.​
4. The names of the values are free form, as long as they are in English and understandable in the context of the enumeration name.

Processes

1. Name starts with N_, The name is in English and may contain A-Z and a-z characters, and if necessary spaces and (braces).
2. If the process is closely related to a concept (i.e. can be considered a ‘method’ to that concept), start the name of the process with the name of the concept followed by ‘ – ’ and then a clear and unambiguous description of what the process does.
3. The concept name is singular if it relates to a single instance, or plural if it relates to a list of records of that concept.
4. Parameters and return values are in snake_case and in English
5. A process can either have both a success (Boolean) and error (Messages) return values, or neither. They should be used for exception handling.​
6. The interface of a process is immutable (when it has been consumed in an active revision)
7. Adding a parameter or return value means creating a new process concept. Preferably the old one is still produced and calls the new one with default values for the extra parameters. Callers should call the new one,and if not produced, call the old one.​
8. The (update only) suffix is used if the process is only usable when a record is locked. With the addition of the‘GetRecordTransactionStatus’ action of the Record Tools plugin, this has become less important​
9. The (UI) suffix is used if the process may have user interaction (dialogs etc.)

Create a change request

After producing the required elements a review is needed. In order for a correct review by the Reference Architecture Board, some additional information is needed.

1. Go to the appserver and log in.

2. Create a new change request via all apps → reference architecture → change requests, and fill in a short discription. The PI number does not need to be filled out.

   

3. Find your elements in the 4 grids, select them and add them to the change request using the Include grid action

   

4. Add general information in the notes by submitter such as a short explanation of what the produces are used for.

5. Open the first element in your change request, this brings you to the change request item. Then click on the link to the actual element.

   
   Fill out the documentation in english (only for concepts, features and processes, attributes do not need to be documented). Repeat this step for all elements in your change request.
   

6. Once finished with all documentation click on the submit button on the change request. The reference board now gets notified of your change request and will review it within 10 working days.