Purpose

The guiding principle for programming standards and guidelines at Syensqo is to use what is generally accepted by the industry as “best-practice”, rather than defining a bespoke set of rules. By adopting this approach, it is more likely that developers engaged by Syensqo are already familiar with the “best-practice” approach and can work effectively in the Syensqo environment immediately.

This document’s purpose is to provide developers with the standards and guidance required to develop in Syensqo’s landscape.

Assumptions

All tools required to develop best-practice based are available.

Since SAP development tools and approaches are evolving so does this document.

The SAP Development Approach has been understood.

ABAP and CDS Programming Rules and Guidelines

It is intended that the following rules and guidelines for ABAP and CDS development will align as closely as possible with the SAP Custom Code Lifecycle Management roadmap.

ABAP Development Environment

Syensqo has a modern SAP environment. To best meet the development needs the ABAP Development Tools (ADT) in Eclipse will be used.

ABAP Cloud and clean core

ABAP Cloud is the programming model for cloud compliant custom developments. Implementing with ABAP Cloud ensures that the code will be considered clean core and upgrade stable. It is the standard for Syensqo.

Basic ABAP Cloud rules can be found here: https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_strict_rules.htm

The ABAP Cloud keyword reference documentation can be found here: https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm.

ABAP Cloud is tier 1 and has to be the default approach for new objects.

Tier 2 is a valid approach if tier 1 cannot be done completely.

Tier 3 is deprecated in general, but exceptions can be applied based on each requirement. For example a new classic ABAP program to be used for an Adobe form, or an implicit enhancement based on business justification and great negative impact if not implemented.

More details of how the different technologies and approaches map to the tiering can be found in the Development Id Definition and Counting Rules document.

Modern ABAP syntax

ABAP syntax has been significantly modernized as of ABAP 7.4. The new syntax supports a cleaner, more concise style resulting in code that is simpler, easier to read and more expressive. Use of ABAP Objects is mandatory.

Obsolete syntax has no place in a modern ABAP environment and must not be used.

All new development must adopt the following ABAP features; these will have the most immediate impact on code quality.

• Inline Declarations and Constructor Expressions. This will remove the need for intermediate variables and verbose initialization routines.

• Table Selection and Comprehension. More expressive use of internal tables will improve readability of the code.

Package Naming

ABAP uses a hierarchical package scheme to organize development artefacts. As discussed in Code Organization in the Development Approach, an organizational scheme based on vertical functional decomposition combined with horizontal architectural layering will be used to organize code artefacts in all development environments used at Syensqo. 

Good ABAP package naming is critical to ensuring code can be found quickly within the ABAP repository. All custom packages will be created under /SYQ/SYENSQO top parent.

For example:

ABAP Cloud compliant objects:

/SYQ/I2M (Business Function Level 1 - Name)

 /SYQ//I2M_E_12345 (Type of Functional Specification - Enhancement, Development Id - 12345)

Legacy objects or classic ABAP and Tier 2 wrapper objects:

/SYQ/I2M (Business Function Level 1 - Name)

 /SYQ/I2M_E_12345_CA (Type of Functional Specification- Enhancement, Development Id - 12345; using legacy or classic ABAP)

Note the package prefix in bold illustrates the requirement for the child package to reflect the parent package name in its prefix.

The above scheme uses only the first level of the Syensqo functional decomposition model. The third level is a package per Functional Specification type to reflect the code boundaries and to allow easier navigation between related objects during maintenance/BAU. 

Objects developed in classic ABAP are assigned to a package with postfix _CA.

Repository Object Naming

Each ABAP artefact of a specific repository type must be uniquely named. The name chosen must reflect the use and functional area of the object.

The naming scheme used for ABAP repository objects is comprised of the following components.

1. A namespace prefix that indicates the owner of the object. The SAP standards for this are:

• Objects starting with a /SYQ/ are considered Customer Objects. Syensqo has its own custom namespace.

• Objects starting with a Y are considered local Customer Objects only to be used for temporary POCs.

• Objects starting with /…/ other than /SYQ/ have been created using a prefix namespace registered to another specific organization. This may be SAP or a SAP Partner.

• All other objects belong to SAP

1. In specific circumstances the type of repository object is encoded in the prefix, for example CL for Class or T for Table. Most repository objects are only accessed from the Object Navigator or the Project Explorer where they are organized by object type making encoding redundant. Encoding becomes important if the repository object is referenced in the source code where it can’t be seen in the context of the repository.

2. A descriptive name for the object. This may contain encoded information about the functional area or business process that the object belongs to. The name needs to ensure that the functional alignment to the process reference model is clear.

The sections below illustrate the naming scheme used a Syensqo: The pattern [NS] refers to the namespace prefix /SYQ/ or Y.

Data Dictionary

Source Code

RESTful Application programming model

CDS

ABAP Managed Database Procedures

Classic Enhancements

Workflow

Workflow artefacts are assigned a unique identifier by SAP when they are created. Semantic information can only be provided in the Abbreviation field (12 characters) and the Name text. Abbreviations do not need to be globally unique, and the system will warn if a duplicate is found.

The Abbreviation Field should encode the intention of the artefact as best as possible and then use the Name text to clarify the objects’ purpose.

BRF+

Web Dynpro

Others

Repository objects that are not allowed

The following repository objects are not to be used at Syensqo. For further information see the SAP help entry on Obsolete Language Elements.

• Business Object Type (BOR). Custom Workflows must use ABAP Objects.

• (Web-)Dynpros and associated artefacts (does not include generated table maintenance screens). Modern SAP web technologies like UI5 are to be used instead.

• Logical Databases – These are now obsolete

• ITS Service – The Internet Transaction Server is an old web technology and should not be used.

• ABAP Type Groups – These are now obsolete

• ABAP Object Services - The object services framework delivers a lifecycle model for ABAP Objects, allowing them to be stored, queried and modified within a defined transaction scope. Although this sounds valuable, the overhead of the framework, the tight coupling to the database and the compromises made to the software architecture when using the framework mean that it’s not to be used.

Furthermore, the following repository objects are not to be used in ABAP Cloud and Clean Core:

• Custom transaction codes for ABAP report programs. Native Fiori apps are the default.

• Custom ABAP reports and includes except for programs used in background jobs.

• Custom function groups and modules except for generated maintenance views or if a RFC function is required.

• Implicit enhancements (unless the specific approval from DA has been secured)

• Classic CDS views. CDS View Entity type to be used.

• SAPScript and Smartforms. Adobe Forms with Fragments is the default with classic Adobe as fallback

• Custom Search help via exit. Search helps in UI5 apps need to use exposed CDS views or implementation in a RAP BO.

• Gateway service projects for oData services. RAP based services to be used instead.

Internal Program Names

Internal program names are those used within the source code, such as variables, types and methods. As per the naming guidelines in Code for Readability, choose names that include detailed semantic information relevant to the current program context. For example, the name should reflect if the object is singular or plural (a collection).

A minimal approach to prefix encoding is encouraged. Technical information about an object can be obtained from the ABAP IDE and so these details must not be encoded in the name. As ABAP is a strictly typed language the compiler will identify any type safety issues.

Names that conflict with ABAP keywords should be avoided. Although this is not strictly enforced by the compiler, it can affect readability. ABAP keywords are easily identifiable through syntax highlighting, and an effort should be made to change the name when a conflict occurs.

As ABAP is case insensitive, lower case is to be used for internal names. Underscores should be used for clarity between words, for example user_name or address_for_delivery.

Local classes and interfaces are not to be prefixed.

When using inline declarations ensure that the data type of the variable is clear from the right-hand side assignment.

Constants to be prefixed with c_.

Global variables must start with the prefix g_. This makes identification of global variables during refactoring and debugging clear. Any other Prefix encoding is not to be used for variables – this includes local variables and class attributes. In the case when a conflict occurs between class attributes and local variables then the me-> prefix should be used to explicitly identify the class attribute. This is considered more appropriate than using l_ for the local variable.

Parameters should be prefixed with i_ (importing), e_ (exporting), c_ (changing) and r_ (returning) allowing them to be distinguished from variables with the same semantic meaning. This applies to both method and function parameters.

Modularization

Modularization in ABAP is a process by which functionality is broken down into smaller manageable components. ABAP supports the following modularization techniques:

• Classes through the use of ABAP Objects (Global or Local)

• Methods

• Subroutines within a Program or Function Module using the FORM statement (Only allowed in the Syensqo environment for specific use cases)

• Function Modules within a Function Group (Only allowed in the Syensqo environment for specific use cases)
  
  

The process of decomposing functionality into smaller modules is a key practice for achieving a Separation of Concerns and adherence to the Single Responsibility Principle as discussed in Code for Maintainability  in the Development Approach.

Pretty Printer

It is generally considered best practice to use the ABAP workbench “Pretty Printer” function to provide a consistent formatting style for ABAP code. The reason consistent formatting is essential for good maintainable code is because the version management of ABAP code does not ignore formatting when comparing versions. Hence by ensuring a consistent formatting style, tools such as version management can provide better clarity on change.

Pretty Printer can be configured several ways, and the most common approach is to set “Indent” to true and set the Convert Uppercase/Lowercase option to “Uppercase Keyword”. The principle behind this is that when code is printed the language keywords standout from the rest of the code. This is not relevant for modern development, and so Syensqo will standardize on the following settings:

Indentation is essential as it is a core style element in code readability. Lowercase for all source is chosen as this aligns with the style guidelines of other languages in use at Syensqo, namely Java and JavaScript. Modern editors, including the ABAP Workbench and the ABAP Development Tools will colour keywords making the use of capitals for distinction irrelevant.

Comments

Although the goal of all developers should be to write code that is easy to understand, comments should be used to highlight areas of code that need further clarification. As described in Code for Readability, comments are not to be used as a replacement for well written, intention revealing code.

ABAP supports two types of comments and both are allowed within the Syensqo Development Standards. That said, the following rules should be followed for the use of these comment types.

Line Comments (those starting with a *) should be used be used in the first instance. These should be placed on the line above the target of the comment, allowing the reader of the code to read the comment before the source code. The comment should be indented to match the line of code it is referencing.

Inline or End of Line Comments (those starting with a “) should only be used in the following situations:

• After a type or variable declaration.

• At the end of a code block. Note that although this is allowed it is discouraged as it usually indicates that the section of code has become too complex (as it requires a comment to explain it) and should be broken into smaller parts – see Separation of Concerns.

• If a Pseudo Comment needs further clarification.

The practice of including a standard header in each ABAP artefact is not to be followed at Syensqo. The standard header contains information that is already available from the attributes of the relevant artefact and the version control system. Additionally, the standard header will be likely to be out of date almost immediately due to code changes not being reflected in the header.

Working with Existing Code and Continuous Improvement

When working with any existing code at Syensqo, the style and structure of the code should be maintained as consistently as possible. Mixing classic and modern ABAP styles significantly impacts the readability of the code.

If the existing code can be easily refactored to a more modern style, then this should be done as part of the change. In this case the scope of the refactoring must cover a single modularization unit, such as a method.

The ability of a developer to do this while implementing an enhancement or fixing a bug will depend on the complexity and size of the particular module, the time available, and the existence of unit tests to confirm no regression bugs have been introduced.

As part of working with existing code, deprecated functions should be removed when identified. Continually making improvements of this type will minimize the remediation work during an upgrade or support package.

Unit Testing

TBD

Exceptions

A common approach to exception handling significantly assists with the clarity of the code. Class based exceptions have many advantages over classic exceptions, providing a change in program flow rather than a simple return code. For this reason only class based exceptions are to be used at Syensqo.

When using class-based exceptions write the TRY/CATCH block first before writing any code. The normal program flow should then be written inside the TRY block.

Exceptions should be defined with respect to the caller as this is where the exception will be caught. The exception must provide enough context to allow the caller to handle the failure.

As discussed in Robust Software, class-based exceptions should be caught at an appropriate level in the code. If an exception is raised, allow it to propagate up through the call stack until a suitable handler is found.

When the code in the catch block exceeds more than a few lines it should be extracted into a separate error handling method to ensure the intent of the called method is clear.

Constants

TBD

ABAP Managed Database Procedures

ABAP Managed Database Procedures (AMDP) allow the execution of stored procedures from the ABAP runtime.

AMDP classes are used to perform data intensive logic with complex calculations. The AMDP methods can be exposed as CDS Table functions.

Custom Fields and Logic App

The Custom Fields & Logic application is used to create custom fields in a clean core compliant way. The fields can be added/ published to CDS model, Service model, UI & Reports, Email & Form templates. Clean core compliant Badis are also being implemented using the app.

The app supports different scope to be activated to use the new custom fields. Activation of all backend related field integrations for available oData, SOAP and BAPI to be done by default.  UIs and Reports, Email and Form Templates, Business Scenarios based on FS requirement only.

Enhancing the SAP Standard

SAP provides several options to change the standard solution. These generally fall into the categories of enhancement, where SAP standard is adjusted through non-invasive extension points, and modification, where the SAP supplied source code is modified directly or SAP artefacts are cloned and modified as required.

Syensqo supports the use of the SAP Enhancement Framework to make changes to the standard solution assuming all necessary approvals are obtained. This includes the use of BAdIs, User Exits and Enhancement Points.

When implementing changes using explicit enhancements it is preferable to add just enough code into the original program to collect any required information and then delegate to a global class where the additional functionality has been implemented. Delegation may be as simple as a calling a method on a class, or depending on the requirement, a custom BAdI may be used to take advantage of features such as Multiple Use and Filters, and if required, the BAdI can be added to the switch framework..

If this approach is followed, the enhancement will be quality checked in the same way as all other custom development, and easily unit tested independently of the original program.

ABAP Test Cockpit

The ABAP Test Cockpit (ATC) is the integration of the SAP Code Inspector into the ABAP development environment. The ATC allows for the continuous checking of developments against an agreed check variant without the overhead of requiring the developer to create Inspections and Object Sets as required by the SAP Code Inspector (SCI). The ATC allows the developer to choose from a list of available global check variants defined by the Code Inspector, or to run against the agreed default check variant.

Syensqo will provide a global check variant which all developments must run successfully agains. This process will be established as part of a quality gate for migration to test and consolidation systems.

SAP has provided a best-practice recommendation for the use of the ABAP Test Cockpit as a quality checking tool and this will be implemented at Syensqo. The approach recommended by SAP is as follows:

• Development System Checks.

  • ATC checks are run in an Ad-Hoc manned by developers on code they are currently working on

  • Scheduled ATC checks are run across the full code base in the development system

• Objects on transports are automatically checked on release (quality gates)

• QA System Checks

  • Checks are periodically scheduled on the code in the QA system

The ABAP test cockpit will be used to automatically inspect 100% of all custom code at Syensqo. The result of each inspection that is run is available to the development team via the ATC results browser in either the ABAP development workbench or the ABAP Development Tools. This provides a worklist for the development team and continuous feedback about the quality of its codebase. All warnings from the ATC are to be treated seriously.

Failing tests would stop the release of the transport. A review of the errors is needed and exceptions to be approved by the development architects.

Tier 2 wrapper

There are still many unreleased objects without contract in S/4 HANA. In order to use them it is necessary to build a tier 2 wrapper with contract C1 that enables the use in ABAP Cloud (tier 1) objects.

Examples are:

• Selects on tables or unreleased standard CDS views in custom CDS view entities: a wrapper CDS to be built

• All Function modules: a custom class to be built that wraps the FM call

• Unreleased standard classes and methods

SAP RESTful Application programming model

SAP Gateway Service Builder is not to be used to create oData services. Instead, the use of RAP generated oData services and Web APIs is mandatory.

SAP help for RAP keyword documentation can be found here: https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenabap_rap.htm

General Rules:

1. Use Eclipse to build RAP Business Objects

2. RAP business objects to be used when CRUD actions are needed in a Fiori app development

3. SAP delivers many standard RAP business objects already that need to be used instead of standard BAPIs if available.

Core Data Services

Core Data Services (CDS) is a modelling tool for defining semantically rich data models using a database independent syntax. The CDS model is then “pushed down” into the target database allowing it to be consumed. ABAP has a specific implementation of the general CDS concept allowing for the definition and consumption of CDS views from ABAP.

ABAP CDS view entities are implemented from the ADT using a Data Definition Language (DDL) artefact. CDS entities utilize a new authorization concept using a data control language (DCL), and this should be used to implement specific entity level authorizations.

CDS view entities need be used instead of direct table selects to follow the ABAP Cloud model.

SAP’s documentation can be accessed here:

ADT has provided various sample CDS templates, which should be used for more efficient development:

CDS VDM types: Rules & Guidelines

CDS can be categorized as Basic, Interface and Consumption CDS. 

CDS Selection List: Rules & Guideline

CDS Performance Specific Rules and Guidelines

Extension CDS View

A standard CDS view can be extended to add new fields, data source and associations.

General Rules:

1. Extension CDS view name should start with “/SYQ/E”, point to the standard CDS name, should reflect the serial number

2. Association Name should start with an “_” and should reflect type or name of associated data source.

3. Custom Field Name should start with “Z” & and can contain technical field name or reflect the meaning of the field.

4. Field Alias should reflect the meaning of the field from end user’s perspective.

CDS Annotations

An annotation enriches a definition in the ABAP CDS with metadata. It can be specified for specific scopes of a CDS object, namely specific places in a piece of CDS source code.

• Latest Fiori Element based apps are completely CDS annotations driven with minimum UI Coding.

• Annotations at oData service can be added at Metadata level and Reference Annotations

• Analytical apps like KPI, OVP can be easily built using CDS Annotations.

ABAP Proxies

ABAP proxies are classes generated to support the consumption and provision of Enterprise Services (via the ESR or Metadata Repository). For standards related to Interface design, please see the SAP Integration Approach.

Once a proxy is generated, the names of the generated repository objects (classes, interfaces, dictionary objects) as well as the field attributes of any structures must be adjusted to support the naming standards defined in this document. The names used for the generated proxy must clearly reflect the intention of the enterprise service it was generated from.

Client proxies, those used for the consumption of an enterprise service, only need to follow the defined naming practices.

Server proxies require implementation and must observe the following rules.

1. Business logic must not be included in the proxy implementation. The proxy must delegate to the appropriate business logic. A proxy implementation is an adapter (as described in Software Architecture) between the Enterprise Service domain (Infrastructure) and the Application domain.

2. The implementation approach should follow the pattern of forward error handling using specific tools and frameworks (FEH or AIF). By separating the concerns of mapping (between XML and application layer) and business logic (delegating to the appropriate component) the proxy can easily be converted to use Forward Error Handling or AIF at a later time.

3. Technical failures should raise detailed SOAP exceptions to ensure visibility in the Integration Engine monitoring infrastructure and transparency of the failure.

4. An explicit COMMIT must not be used in the proxy implementation. This is handled by the framework.

5. Proxy runtime should be minimized. If the business logic requires excessive runtime then appropriate technical level checks should be made, and if successful, the business logic executed via an asynchronous process (bgRFC, application job). This will technically complete the proxy execution and avoid blocked queues and timeouts.

Print Forms

The development of print forms at Syensqo will be based solely on the Adobe Document Services framework. Since the release of S/4HANA 1511, a new output management technique has been adopted by SAP utilizing BRF+ instead of the previous “NAST” condition-based technique. The target architecture in S/4HANA is now focused only on ADS and Adobe Forms. SAPScript and SmartForms are to be considered deprecated. With Clean Core the forms need to be built as Adobe with Fragments forms as default. Only if there is no output management support for these can a classic Adobe form be built instead or SAPScript/Smartforms as absolute exception.

SAP will continuously deliver Adobe Forms to replace its legacy SAPScript and SmartForms. During this transition period these legacy forms may be configured to be used through Output Management and minor modifications made (such as the addition of an Syensqo logo). Major changes to existing legacy forms are not permitted; instead confirm with SAP when the Adobe Form replacement will be delivered and if this is unsuitable a custom Adobe Form can be considered.

All print forms can be translated via the Translation Editor SE63.

If a form template is used in several countries having the same layout and content, then the translation in SE63 is required.

If a form template has major layout and/or content changes due to country specific versions, then a new form needs to be created to streamline the form configuration and maintenance.

Form Build Rules:

1. Logo:

   1. As default, use the black and white Logo in white background (42mm logo) if not specified otherwise. Logo should not be directly attached. We have the utility class /SYQ/CL_DYNAMIC_COMPANY_LOGO that needs to be used for all forms as default. No logos should be loaded/embedded into a form. 

   2. The MIME repository to be used is SAP/PUBLIC/Syensqo (tcode SO2_MIME_REPOSITORY)

2. Font: 8 - 11 points Arial Regular to be used unless specified for different sections of the form.

3. Page Margins: 5 mm at least on all sides so that the whole layout gets printed.

4. Table Header: Should have at least 1 space before the text and after or be center aligned if anything not specified for the build – should never look like it is on the Table border (line).

5. Address: Should have the same format/fonts for all the address in the same form like for Company address, Sold-to address, Customer address, unless specified in the build.

6. Date: Left Aligned as default, unless specified in the build. Use ISO 8601 standard of pattern YYYY-MM-DD if not specified otherwise.

7. Texts: Left Aligned as default, unless specified in the build.

8. Numbers: Should be ideally right aligned like for amount and weight.

Suggestions as below for better and clean output:

1. Form Header: Should stand out from the rest of the texts in the form for e.g. bold, bigger font size.

2. Free Texts: Remove extra space while printing texts.

3. Labels: If one header label has ':', then ideally all header labels should have that.

4. Last page: Should check for blank page as the last page unless required for build. Try to ensure blank page is not getting printed at the end unless required.

Workflows

Custom Workflows need to be built using the Flexible Workflow or BTP BPA. That complies with SAP’s clean core approach. The business objects and custom logic have to be done in ABAP OO and RAP. 

Transaction code SWDD_SCENARIO instead of SWDD is used. Using Flexible Workflows allows for flow configurations via the app “Manage Workflow”. For the agent determination the new “Responsibility Management” app.

If the agent determination has parallel branches with separate agent groups it may be needed to build the Workflow using BTP’s Build Process Automation. But that should be the exception and design should not have such complexity required.

ABAP Authorization Group

Custom ABAP code and tables will have a custom authorization group assigned to them to provide the mechanism to restrict access to them by users. 

For these custom developments the table below will be used depending on the relevant functional module.  The object BRGRU has a maximum of four characters to create a unique authorization group with.  The object(s) will be created using transaction SE54.  

To have a consistent naming convention for custom authorization groups, use the entries in the table for tables and programs. 

ABAP Authorization Check

Authorization checks are needed to limit access to data or to restrict who can create/update/delete data.

The ABAP keyword AUTHORITY-CHECK is deprecated in ABAP Cloud. Instead, the authorization checks need to be added to CDS view entities using DCLs (Data Control Language) to restrict access or inside the RAP Behavior handler class.

DCL authorization: https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/abencds_dcl_role_cond_rule.htm

RAP authorization: https://help.sap.com/doc/abapdocu_cp_index_htm/CLOUD/en-US/index.htm?file=abenbdl_authorization.htm

SAPUI5 and Fiori Elements Programming Rules and Guidelines

UI and UX Definition

User Interfaces (UI)

This term relates primarily to the screen technologies.  The intended SAP footprint spans a number of SAP user interface solutions, including cloud solutions acquired by SAP (eg. Ariba, SuccessFactors etc.), solutions developed by SAP (eg. Fiori applications), traditional screens (eg. classic SAPGUI transactions) yet to be updated by SAP, as well as non-SAP frameworks (eg. React).  This section seeks to provide a coherent approach to accessing the various technologies on offer in as simple a manner as possible.  This includes access across various channels (eg. desktop / tablets / mobiles). 

User Experience (UX)

The concept of user experience (UX) is a broad domain and concerns itself more with how users feel about a system after using it.  As such it is more difficult to measure and less technically focused than the area of user interfaces.  One definition of UX can be succinctly summarised as …   

A person's perceptions and responses that result from the use or anticipated use of a product, system or service - Ergonomics of human system interaction, ISO 9241-210

Concepts such as visual design, interaction design, theming, accessibility and performance can all contribute to the end UX.  When we describe the ‘look and feel’ of an application, whilst the user interface may deliver the ‘look’, the user experience can denote the ‘feel’ of that application.  From an SAP standpoint given the charter for ‘Standardization’ we place heavy reliance on SAP’s ability to delivery UX in its technology suite.  Therefore from a strategy perspective we align with SAP’s UX direction which is based on the ‘Fiori’ concept.

User Experience Principles 

The User Experience principles represent the guiding principles when making all decisions related to the User Experience. 

SAP UX Guidelines for Fiori

Custom UI5 Fiori apps need to follow the SAP UX guidelines. Its principles were described in section 2.2.

The SAP UX guidelines for Fiori can be found here:

https://experience.sap.com/fiori-design-web/

The standard app library for Fiori apps can be found here:

https://fioriappslibrary.hana.ondemand.com/sap/fix/externalViewer/

Development Tools

SAP offers the SAP Business Application Studio (BAS) for the development and extension of SAPUI5 applications. Although there are other tool choices available, the SAP BAS is to be used for all SAPUI5 development at Syensqo.

Naming Conventions

This guide is to be considered the Syensqo standard for SAPUI5 naming conventions and is to be followed for all SAPUI5 development. By adopting these conventions, code developed at Syensqo will be of a standard accepted by SAP.

The JavaScript standards defined in the Java and JavaScript Programming Rules and Guidelines section are to be considered in the context of working with the SAPUI5 library, SAPUI5 templates are regularly updated and we recommend developers to familiarize themselves with above document as per SAPUI5 release version.

SAPUI5 application namespaces are used to guarantee code written by Syensqo does not clash with SAP delivered code or 3^rd party frameworks. The namespace scheme used at Syensqo will start with the prefix com.syensqo as per SAP best practice. Following this prefix, a combination of the Process Reference Model hierarchy will be used to uniquely assign the SAPUI5 component to a relevant functional process.

Once the root namespace of the SAPUI5 component is determined, it should be used as a prefix for all other namespaces used in the repository.

For example, the following namespace is used for a new SAPUI5 component in the learning and development process type in HR.

com.syensqo.hr.learninganddevelopment.Component – Component Configuration

com.syensqo.hr.learninganddevelopment.controller.createcoursematerial – Course Material Controller

The namespace postfix will vary based on the application design. The application structure should always follow the current guidelines from SAP.

SAPUI5 ABAP Repository

Syensqo will host a majority of its SAPUI5 applications in the embedded Fiori server in S/4HANA, with the exception being extensions to the SAP Cloud Portfolio. When SAPUI5 applications are hosted on an ABAP system the rules below need to be followed to ensure the integrity of the application.

• Do not modify any SAPUI5 applications directly in the ABAP editor. This can lead to source code inconsistencies

• The SAPUI5 ABAP Upload/Download tool should not be used in the development process. Only the SAP BAS IDE can be used for working with SAPUI5 applications using the ABAP Repository.

Note that although SAPUI5 applications are stored as BSP applications they do not support the BSP runtime hence BSP concepts such as Flow Logic are not supported in SAPUI5 development.

Github Repository

Syensqo uses Github (www.github.com/xxxx) to host its SAPUI5 git repositories.

To access the Syensqo Github account users will first need to be granted access by an administrator of the Github account. Two-factor authentication on the Github account is mandatory to be enabled to provide an additional layer of security for the organization.

Once a user has been granted access, they will then need to create a Github Personal Access Token. This can be found under User > Settings > Developer Settings > Personal Access Tokens (https://github.com/settings/tokens). This Personal Access token needs to be saved and used in lieu of a password when accessing a git repository from SAP BAS.

The source code for all SAPUI5 applications needs to be managed in Github and a new repository should be created for each application. When creating new git repositories, the repository should be named with the same name as the BSP application name and Development Id plus more information added as description. This convention makes it easier to identify the git repository for any SAPUI5 application.

Git commits should follow best practice. This means commits should be small and done often; committed code should be complete and tested; and commit messages should be meaningful and explain what was changed and why.

More details about the Git process in section xxx.

Version Management in Github

Every change to an existing app needs to be done via branch created in Github.

The app will still be assigned to a transport and moved to QA and Prod via it. Github is only for version management, collaboration and governance review.

Before a change moves to QA it is required to merge the branch with the master. Before a change moves to production it is required to ensure that there is o open branch with changes missing in the master.

Rules for Fiori applications

The ABAP application server offers CDS, transactional application frameworks and traditional ABAP coding that expose user interface consumption services through the OData protocol, which significantly simplifies template-based SAP Fiori applications.

Unit Testing

TBD

Localisation

To support translatable texts, all viewable labels and literals must use the UI5 localization concept and provide a resource bundle. Resource bundles are stored in the i18n folder of the web app. The default bundle is called i18n.properties and must be provided for all SAPUI5 applications. Additional language bundles can then be created on an as needed basis.

Accessibility

All SAPUI5 applications must at a minimum not interfere with any accessibility features delivered by the framework. For more information about accessibility see the Accessibility section of the SAPUI5 documentation.

Fiori Elements

Fiori Elements allow SAPUI5 applications built directly from annotations provided by the consumed OData services. As each template is provided by SAP, applications built using Fiori Elements Templates will benefit from enhancements delivered by SAP in future releases of the SAPUI5 library. Additionally, applications built from templates will meet Fiori design guidelines and follow established floorplan patterns. 

Application built with Fiori Elements require no or minimal code to be written as the application is based on views and controllers provided by SAP. For this reason, Fiori Elements should be considered before creating a custom SAPUI5 application.

UI Extensibility

SAP introduced several new UI extensibility options in S/4HANA that are to be used as of 1809 (See appendix for full extensibility presentation slides).

Customer enhancement of SAP delivered applications is managed by an extension process that does not modify the standards application directly. This means that any changes made by the customer will not be lost when the original application is upgraded.

JavaScript Programming Rules and Guidelines

The JavaScript standards defined in this document are to be considered in the context of working with the SAPUI5 library. 

Development Tools

SAP offers the SAP Business Applicaation Studio (BAS) for the development and extension of SAPUI5 applications. Although there are other tool choices available, the SAP Web IDE is to be used for all SAPUI5 development at Syensqo. 

Naming Conventions

SAP has provided the Development Conventions and Guidelines document for working with JavaScript. This guide is to be considered the Syensqo standard for naming conventions and is to be followed for all SAPUI5 development. By adopting these conventions, code developed at Syensqo will be of a standard accepted by SAP for contribution to the SAPUI5 library.

The following high level rules should be noted

• Classes and Controls are to be started with a capital letter and then follow camel case

• Functions and Variables are to start with a lower case letter then follow camel case.

• Pre-fixing of variables is encouraged due to the weak typing in JavaScript. A list of acceptable prefixes is provided in the SAP Development Conventions and Guidelines document.

• Constants are to be all UPPER CASE

• Use “strict mode” during development to identify any potential coding issues.

Github Repository

Syensqo uses Github (www.github.com/xxxx) to host its SAPUI5 git repositories.

To access the Syensqo Github account users will first need to be granted access by an administrator of the Github account. Two-factor authentication on the Github account is mandatory to be enabled to provide an additional layer of security for the organization.

Once a user has been granted access, they will then need to create a Github Personal Access Token. This can be found under User > Settings > Developer Settings > Personal Access Tokens (https://github.com/settings/tokens). This Personal Access token needs to be saved and used in lieu of a password when accessing a git repository from SAP BAS.

The source code for all SAPUI5 applications needs to be managed in Github and a new repository should be created for each application. When creating new git repositories, the repository should be named with the same name as the BSP application name and Development Id plus more information added as description. This convention makes it easier to identify the git repository for any SAPUI5 application.

Git commits should follow best practice. This means commits should be small and done often; committed code should be complete and tested; and commit messages should be meaningful and explain what was changed and why.

More details about the Git process in section xxx.

Version Management in Github

Every change to an existing app needs to be done via branch created in Github.

The app will still be assigned to a transport and moved to QA and Prod via it. Github is only for version management, collaboration and governance review.

Before a change moves to QA it is required to merge the branch with the master. Before a change moves to production it is required to ensure that there is o open branch with changes missing in the master.

Mobile Neptune App Programming Rules and Guidelines

For Fiori the SAPUi5 Standard must be followed and for ABAP development, the Syensqo ABAP Standard must be followed. However, this section revisits the SAP Fiori Guidelines from a Neptune access perspective.

• Neptune Launchpad which is the home page must be the single point of entry and central point of all navigation paths. The tiles on the home page of the Neptune Launchpad represent navigation anchors to the individual apps. By selecting a tile, the user navigates to the corresponding app. It is also possible to integrate legacy UI technology through such tiles.

• Neptune Launchpad is configured in the Neptune Cockpit hosted on one S/4HANA server, it can host multiple Launchpads and mobile clients.

• It is Neptune and SAP Fiori best practice to design all UI5 apps stateless.

• Neptune is utilizing SAP UI5 as the default HTML5 GUI framework for Neptune apps. Even though it is technically possible to use any HTML GUI framework, you should use Neptune applications on the UI5 framework.

• Minor design adjustments can easily be added by applying custom CSS classes directly in Neptune Application Designer. Custom icons can be included using the sap.m.Image control.

• It is recommended to define the Title/Group attribute in the app settings as this is the wording that will be displayed on the browser tab.

• Every app should start with the sap.m.Shell control, typically named 'oShell'.

• Beneath sap.m.Shell, always place the sap.m.App or sap.m.SplitApp control as a subnode. The App/SplitApp control is the de-facto root control of the app that will be used to control all navigation and busy-state of the app. For example, you can name it 'oApp'. You can have multiple App/SplitApp controls under one Shell.

• As subnodes to the App/SplitApp control, it is recommended to define a set of sap.m.Page controls that define the needed screens of the app. Hierarchically all pages should be placed at the same level.

• The page control that is placed as the first subnode of the App/SplitApp control will be the starting page which is rendered/displayed at app start.

Neptune Application Naming

• Every object of an app must have a unique name (exception: neptune.BarContent).

• Just as SAP Fiori, the 'camelCase' notation applies - starting lowercase and using uppercase letters for all leading characters of the composite name.

• It is UI5 best practice to start every object name with a lowercase 'o' (for object). Neptune only uses the 'o' notation on Pages, App/SplitApp and Shell controls.

• The maximum name length for an UI5 control in Neptune is 23 characters.

• Name the sap.m.Shell control 'oShell'

• Name the sap.m.App/SplitApp control 'oApp'

• Following the above guidelines for the object names should be similar to this example:

Neptune Application User Experience

• SAP Fiori Design Guidelines must be followed when designing UI5 apps with Neptune.

• The app should be based on sap.m.Page as the basic design container.

• Every page should include a header section.

• Every page should include a footer section.

• All process specific design, e.g. forms, tables, tabs, etc., should be placed between header and footer of a page.

• Basic process triggers like buttons to save, cancel, submit should be placed in the right section of the footer.

• Back buttons should be placed in the left section of the page header or footer. 

SplitApp environment:

• The Master Page should be the leading function, providing e.g.

• a list of (searchable) items, or an input form to define/search for datasets, or a list of sub-functions, etc.

• The Detail Page should display process/data details and functional triggers, e.g.

• Infos to a specific dataset selected on the Master Page, or Sub-items of a dataset, or Input fields to create a new dataset, etc.

• Both sections should have a footer displaying buttons to trigger further actions.

Buttons:

• Buttons should follow a basic color concept, which can be set via property 'type':

• blue (type: Emphasised): Core function trigger of a page, e.g. Search, Submit. In general used to emphasise a certain button object in contrast to un-styled buttons on the same footer/toolbar

• green (type: Accept): Positive function trigger used mostly in combination with a negative trigger, e.g. Save/(Delete).

• red (type: Reject): Negative function trigger used mostly in combination with a positive trigger, e.g. Decline/(Approve).

• none (type: Default/none): Used for standard functions. Button blends in with footer/toolbar, e.g. Settings.

• The button function should either be displayed applying text OR SAP-UI5 icon. All available UI5 icons are listed in the Neptune Icon Explorer.

Unit Testing

TBD

ABAP Application Class

All Neptune Applications have an associated backend ABAP Class. The application class is where the logic of the application is implemented. In terms of the Model View Controller design pattern the application class hence plays the role of ‘model’.

• Follow Syensqo's ABAP Development guidelines.

• The app-corresponding backend class must implement the /NEPTUNE/IF_NAD_SERVER interface.

• Using UI5, the only applicable handling method is HANDLE_ON_AJAX.

• In HANDLE_ON_AJAX, implement a case statement based on input parameter AJAX_ID to redirect to the corresponding private methods of the class.

• All attributes that are used for binding in Neptune Application Designer need to be declared public.

• Attributes for binding can be flat structures or internal tables.

• Attributes can be based on local structures or data dictionary.

• Define small/lean private methods.

Backend Calls

In order to successfully design a backend call, you need to define the following parts:

• Bind the backend attributes to the corresponding UI5 controls.

• Define the Ajax ID for the backend call at one of the bound controls.

• In online scenarios, the main receiving UI5 control should define the Ajax ID.

• In offline scenarios, use sap.m.Ajax control to define the Ajax ID for backend calls.

• If you want to send/receive more than one data model, use the 'Additional Model Send/Receive' option next to the Ajax ID.

• Implement corresponding backend code in the ABAP class based on the incoming Ajax ID.

• Based on the definition of the Ajax ID (e.g. at UI5 table control 'tabMyTable'), Neptune will automatically create an anonymous function that can be used to trigger the backend call via Javascript function call.

• This function always uses the following naming convention: 

  'getOnline' + nameOfUI5ObjectWhereAjaxIDisDefined().

Event Handling Success / Error events

• AjaxSuccess:

When the server answers with an expected result, the AjaxSuccess event at the UI5 control with the Ajax ID is triggered automatically. We recommend making use of this event in order to handle further process control after fetching data from the backend. This will also prevent wrongful process control on the client-side if the server does not answer or the connection is broken during a call. Typical examples of needed client-side code in the AjaxSuccess event are disabling the busy state, navigation, and further data processing/updates. Below you find a common AjaxSuccess coding example:

• AjaxError:

Implementing the AjaxError event (always implement both!) will prevent wrongful process control on the client-side if the server does not answer or the connection is broken during a call. For example, if you trigger a server-side search call, you do not want to show an empty result list if the server is down, the ABAP logic dumps, or connection is lost. Correct process-handling would be to let the user know that the server did not respond.

Client-side Scripting using JavaScript

• All custom JS functions create a ScriptCode control named 'Functions'.

• More ScriptCode can be added to the controls based on the need for specific Javascript functions grows.

• For all code that should run initially when starting the app, create a ScriptCode control named 'Init'.

Neptune Launchpad Events - OnInit / OnLoad 

• There are two events provided by sap.n (which is the Launchpad-specific namespace) which are executed when launching an App in the Neptune Launchpad:
• sap.n.Shell.attachInit triggered the first time an app is launched. It is the equivalent to sap.ui.getCore().attachInit.
• sap.n.Shell.attachBeforeDisplay triggered every time an app is displayed (launch and switching views).

Mobile Client Build

Mobile Clients can be built in 2 ways:

• Neptune Mobile Build Service (MBS) (Preferred option)
• Manual build using the Cordova CLI

Using MBS

TBD

Using the Cordova CLI

• Download the cordova project from Neptune dev system and unzip.

• Make sure that the the correct SDK tool version is installed (for Androis build to be set in Android Studio)

• Run in terminal in project root folder:

  • cordova platform add android

• Copy build.json to root folder.

• Copy keystore file to root folder (if applicable)

• Change App name in config.xml to [sysid] -

• Run in project root folder:

  • cordova build [android/iOS] --release --buildConfig=build.json OR

  • cordova build [android/iOS] --debug --scan (for debug version)

• Change file name to ([sysid] - [Application Name] [version].apk)

Publishing custom Plugins to npm

To publish custom plugin to npm, follow below steps:

1. Plugin can be published via VS Code or Node JS command prompt.

2. Open Command prompt and login to npm

   • Command - > npm login

3. After login use below command to publish the changes to npm

   • Command - > npm init --scope=@syensqo

4. After initializing publish to npm with below command

   • Command - > npm publish --access public

5. Plugin is now plublished to npm

6. It usually takes 24hrs for the plugin to be available in MBS tool. If it doesn’t appear then contact volt build team.

System refresh preparations

Any S/4HANA system refresh needs to be prepared for in case of Neptune.

Since the configuration of the Neptune environment will be overwritten it is necessary to export it BEFORE the system refresh and imported again after the refresh.